Windows parity plan: PR sequence, validation, and follow-up gaps

[smota]

Hi maintainers — I’d like to reset this Windows parity discussion around a clearer architecture and review plan.

I closed the earlier upstream PR stack because it had become too noisy to review productively. Since then, I consolidated the fork work into a bounded Windows enablement strategy: the goal is to make native Windows a first-class supported platform for the workflows we can support reliably now, while being explicit about what is not yet equivalent to POSIX.

The proposed ADR is here:

• ADR: https://github.com/smota/omnigent/blob/windows-parity/integration/docs/windows-first-class-support-adr.md

Detailed supporting docs are indexed here:

• Windows docs folder: https://github.com/smota/omnigent/tree/windows-parity/integration/docs/windows

Core proposal

The first Windows enablement wave should support native Windows for:

• installation and setup;
• server / host / runner / web usage;
• core spec/store/session behavior;
• Windows-safe developer and test workflows;
• Omnigent-managed terminal lifecycle via psmux;
• process-containment-only sandbox boundaries, with unsupported filesystem/network/egress policies failing closed.

It should not claim full POSIX parity yet.

Explicit non-goals for this first wave:

• hard filesystem/network sandbox isolation equivalent to Linux bwrap or macOS seatbelt;
• a new Windows isolation backend before the project chooses a threat model;
• POSIX-only terminal/test surfaces on native Windows;
• full browser terminal fidelity parity if psmux only supports capture/polling attach;
• making local TCP/UDS runner transport part of the initial Windows support claim.

Why this shape

I’m trying to avoid both extremes:

1. Overclaiming parity — saying “Windows is supported” while hiding security or terminal fidelity gaps.
2. Boiling the ocean — blocking useful Windows support until every Linux/macOS behavior has a Windows-equivalent implementation.

The ADR proposes a middle path: first-class support with a clear product/engineering boundary.

That means Windows can be supported for real workflows now, while limitations are documented, validated, and not presented as solved.

Capability groups

The fork backlog is organized around these areas:

1. QA / evidence / developer workflow

   • define what “review-ready Windows support” means;
   • document native PowerShell setup and test commands;
   • separate hard CI from non-blocking broad sweeps;
   • require trustworthy evidence for browser/UI-visible behavior.

2. Native terminal support

   • use psmux as the candidate native Windows terminal backend;
   • preserve existing POSIX tmux behavior;
   • support launch/read/send/close lifecycle;
   • run a real psmux lifecycle test in native Windows CI;
   • document browser attach fidelity limits unless a better psmux streaming/control interface is accepted.

3. Sandbox / egress boundaries

   • treat Windows Job Objects as process containment only;
   • fail closed for unsupported filesystem/network/egress policies;
   • keep parser, validator, docs, and tests aligned through one capability model;
   • defer AppContainer/WFP/restricted-token/etc. until the project chooses a Windows isolation approach.

4. Installer

   • provide a native PowerShell installer path;
   • keep psmux optional/detected until terminal support is accepted;
   • separate release-pinned and preview/from-source usage;
   • avoid promising unsupported capabilities.

5. Runner transport

   • keep the WebSocket tunnel as the default supported runner path;
   • defer local TCP/UDS transport from the first Windows enablement wave unless maintainers want it.

Proposed upstream PR sequence

I propose reopening upstream work as a smaller sequence:

1. Windows QA + native developer workflow

   • no feature code;
   • establishes review/evidence expectations and native Windows commands.

2. psmux terminal backend lifecycle + CI

   • backend selection;
   • missing-binary diagnostics;
   • launch/read/send/close lifecycle;
   • native Windows psmux CI test;
   • explicit browser attach fidelity limitation, not a parity claim.

3. Windows sandbox capability model

   • shared capability source of truth;
   • fail-closed parser/validator behavior;
   • docs/tests for unsupported Windows sandbox/egress combinations;
   • no claim of full filesystem/network isolation parity.

4. PowerShell installer

   • once terminal and sandbox boundaries are accepted.

Runner local TCP/UDS transport would stay deferred unless maintainers think it belongs in the first wave.

Evidence standard

One important correction from the earlier PR stack: visual evidence must be real and specific to the behavior under review.

For future Windows PRs, I plan to use:

• native Windows PowerShell transcripts for CLI/test behavior;
• real screenshots or recordings only for browser/UI-visible behavior;
• unlocked Windows desktop captures showing the actual Omnigent app/terminal;
• a live typed value, timestamp, or nonce in recordings so the evidence proves liveness;
• no reused generic evidence bundle across unrelated PRs.

For psmux browser attach specifically, evidence should show:

• Omnigent web terminal attached;
• a command typed;
• output round-trip;
• if browser fidelity is discussed, an ANSI/cursor/TUI-like example showing the current limitation clearly.

Input requested

I’d appreciate maintainer guidance on these decisions before opening new PRs:

1. Is the bounded “first-class Windows support” statement in the ADR acceptable?
2. Is psmux an acceptable native Windows terminal dependency?
3. Is documented reduced-fidelity browser attach acceptable for the first terminal milestone, or should browser attach wait for a streaming/control-mode bridge?
4. Is “process containment + fail-closed unsupported policies” an acceptable first Windows sandbox boundary?
5. Should the first upstream PR be QA/developer workflow only?
6. Should local TCP/UDS runner transport be deferred from this wave?

I’m happy to reshape the fork work to fit the project’s preferred architecture and review style before reopening upstream PRs.

[smota]

Implementation update from the fork:

The bounded Windows ADR scope has now been completed on smota/omnigent@windows-parity/integration and the corresponding fork issues have been closed.

Implemented/closed areas:

• psmux-backed native Windows terminal lifecycle, with real psmux lifecycle test coverage;
• native Windows developer/test workflow and stable Windows-safe test subset;
• Windows sandbox/egress support boundary with fail-closed unsupported policy checks;
• native PowerShell installer path, dependency diagnostics, release-pinned and preview/from-source modes;
• runner transport fallback with WebSocket tunnel as default and env-selected local transport as opt-in;
• QA/evidence matrix and detailed Windows documentation;
• psmux browser attach fidelity decision: current bridge is documented as capture/send behavior, not POSIX tmux parity;
• shared sandbox capability source of truth for parser/validator/docs/tests.

Relevant docs:

• ADR: https://github.com/smota/omnigent/blob/windows-parity/integration/docs/windows-first-class-support-adr.md
• Windows docs index: https://github.com/smota/omnigent/tree/windows-parity/integration/docs/windows

Latest implementation commits include:

• 8140e2b3 fix(windows): centralize sandbox capability checks
• 6f1578b1 docs(windows): define installer and psmux attach boundaries
• e797e2c7 test(windows): expand native stable subset

Validation performed locally on native Windows:

uv run pytest tests/terminals/test_registry.py::test_windows_psmux_backend_launch_send_read_close \
  tests/terminals/test_registry.py::test_psmux_backend_missing_binary_error_is_actionable -q
2 passed

uv run pytest tests/inner/test_proc_and_platform.py tests/runtime/test_process_manager.py \
  tests/runner/test_routing.py tests/server/test_runner_transport.py \
  tests/inner/test_sandbox_capabilities.py \
  tests/spec/test_parser.py::test_parse_windows_jobobject_rejects_network_deny \
  tests/spec/test_parser.py::test_parse_windows_jobobject_rejects_egress_rules \
  tests/spec/test_validator.py::test_os_env_windows_jobobject_rejects_network_deny \
  tests/spec/test_validator.py::test_os_env_windows_jobobject_rejects_egress_rules \
  tests/scripts/test_install_oss_ps1.py -p no:cacheprovider -q
68 passed, 6 skipped

One repo-wide pre-commit run --all-files attempt was not retained because it rewrote line endings across thousands of unrelated files on Windows; the worktree was reset immediately and only targeted validations above were kept.

[smota]

Completed the missing browser/UI evidence and Windows E2E evidence package on windows-parity/integration.

New commit:

• 84bdfbe6 test(windows): add browser terminal evidence package

Evidence package:

• https://github.com/smota/omnigent/tree/windows-parity/integration/docs/windows/evidence
• Full-page browser attach screenshot: https://github.com/smota/omnigent/blob/windows-parity/integration/docs/windows/evidence/browser-psmux-terminal-attach.png
• Focused terminal panel screenshot: https://github.com/smota/omnigent/blob/windows-parity/integration/docs/windows/evidence/browser-psmux-terminal-panel.png
• Environment inventory: https://github.com/smota/omnigent/blob/windows-parity/integration/docs/windows/evidence/environment-inventory.txt

The browser evidence was collected from the actual Omnigent web UI on native Windows using the same terminal_session fixture flow as tests/e2e_ui/shells/test_new_shell.py: open the Shells rail, create a psmux-backed shell, wait for data-state="connected", type a live nonce command into xterm, verify the bridge remains connected, and capture screenshots.

Validation:

uv run pytest tests/e2e_ui/shells/test_new_shell.py::test_new_shell_accepts_typed_command -q --ui-skip-build --browser chromium
1 passed

uv run pytest tests/terminals/test_registry.py::test_windows_psmux_backend_launch_send_read_close tests/terminals/test_registry.py::test_psmux_backend_missing_binary_error_is_actionable -q
2 passed

A small Windows test harness fix is included: browser E2E SPA build now invokes npm.cmd on Windows because Python subprocess with shell=False does not reliably resolve the PowerShell npm.ps1 shim.

This evidence still intentionally does not claim POSIX tmux PTY/control fidelity parity; it demonstrates the documented psmux capture/send browser attach boundary.

[smota]

Final parent-orchestrated review loop completed on windows-parity/integration.

Final implementation commits added after reviewer feedback:

• cfb42294 fix(windows): harden psmux terminal evidence path
• d70f0de7 fix(windows): align psmux cwd policy and evidence checks

Review loop summary:

• Round 1 reviewers found real blockers: psmux runner-auth env leakage, unreproducible temporary evidence test, weak browser evidence, and evidence hygiene issues.
• Fix worker applied security/evidence/workflow fixes.
• Round 2 reviewers found remaining psmux cwd/parent-os-env policy blockers plus docs/evidence assertion gaps.
• Fix worker applied psmux cwd inheritance/containment alignment, stronger evidence transcript checks, docs/link fixes, and pushed d70f0de7.
• Round 3 reviewers returned PASS/no blockers across browser evidence, security/CLI validation, and ADR/scope.

Final focused validation from the parent session:

git diff --check upstream/main...HEAD
# passed, no output

uv run pytest \
  tests/terminals/test_registry.py::test_psmux_backend_rejects_outside_cwd_override \
  tests/terminals/test_registry.py::test_psmux_backend_resolves_inherited_parent_cwd \
  tests/terminals/test_registry.py::test_windows_psmux_backend_strips_runner_auth_secrets \
  tests/terminals/test_registry.py::test_windows_psmux_backend_launch_send_read_close \
  tests/e2e_ui/windows/test_psmux_terminal_evidence.py::test_windows_psmux_browser_evidence \
  -q -p no:cacheprovider
# 5 passed, 1 skipped

Final branch state:

• windows-parity/integration pushed to origin/windows-parity/integration.
• Open fork issues: none.
• Reviewers confirmed the evidence demonstrates the documented psmux capture/send bridge and does not claim POSIX tmux PTY/control parity.

[SchneiderSam]

Thanks for working on this. Really like the idea behind omniagent. Tried to install it on my windows device but feels very "unmature" and buggy.