Skip to content

feat: support native Windows Codex and protected Crew tools - #24043

Closed
muhmuhkuh wants to merge 2 commits into
kirodotdev:mainfrom
muhmuhkuh:feat/native-windows-mxc
Closed

muhmuhkuh wants to merge 2 commits into
kirodotdev:mainfrom
muhmuhkuh:feat/native-windows-mxc

Conversation

@muhmuhkuh

@muhmuhkuh muhmuhkuh commented Oct 25, 2026 •

Copy link
Copy Markdown

Problem / Motivation

Goal: Allow operators on compatible native Windows hosts to run Codex ACP with Crew's OS credential masks and readable, immutable governance files.

Selecting Codex on native Windows currently refuses every session because Crew has no OS sandbox backend capable of applying the required credential mask.

Why it matters

Windows users need a working Codex harness while retaining the filesystem isolation required by Crew's enforced permission routing.

Not a goal

  • Automatic installation or release packaging of the native helper.
  • Replacing the Linux namespace or macOS Seatbelt backends.
  • Allowing an enforced adapter to run without its credential mask.
  • A claim of general Windows release support.

What changed (motivation → approach → change)

Native Codex can use Crew tools without exposing the SEL key, and routing changes can retire the processes that pin protected settings before replacing those settings.

Behavior Owner areas
Probe and apply an authenticated MXC policy; keep credential denies, governance seals and descendant confinement native/windows-sandbox, sandbox_windows.py, sandbox_plan.py, sandbox_windows_policy.py, sandbox_windows_launcher.py
Connect through minimal runner-mediated handles to the unchanged owner-only broker pipe; verify SID, runtime/session scope, expiry and current launch approval mcp_gateway, src/kiro_crew/agent_sdk/host_auth.py, src/kiro_crew/security/paths_lists.py
Refuse privileged direct fallback with structured errors; retain permitted third-party fallbacks mcp_gateway/required.py, stub.py
Finalize MCP routing after member/panel mounts, sign the child channel and await MCP readiness on create/resume; admit assigned, unrestricted Work broker stubs mcp_gateway/native_session.py, acp/runtime_session_create.py, acp/runtime_session_load.py, providers/mirrors/codex.py
Confirm interruption, fence new starts, drain owned trees, save atomically, rebuild and verify broker activation src/kiro_crew/dashboard, config, atomic_write.py, windows_settings.py, platform_compat_wintree.py, src/kiro_crew/slack
Carry native launch metadata and private visibility through common planning, delegation and immutable seals sandbox.py, sandbox_argv.py, sandbox_delegation.py, sandbox_leaves.py, sandbox_seals.py
Keep Windows Crew history in a persistent private Codex profile; import only Crew-mapped rollouts and configuration, not desktop auth.json or indexes acp, scripts
Show saved/active/restart-required/failed states from effective overrides and layers website/src/pages, website/src/api, website/src/i18n
Document setup, stopped-app recovery, rollback and opt-in tests; commit isolated UI evidence docs, test, website/temp-screenshots

The pinned SDK's direct ConnectPipe and minimal data-read/write/synchronize CreateFileW both return WinError 5 on the measured host. The outside helper authenticates canonical REGISTER before transferring a data handle. It derives scope MACs from the existing host key. No pipe DACL is broadened and no HTTP MCP substitute is introduced.

Protected document pins retain their no-delete-sharing flags. Publication leases are task-scoped and revoked on exit; mutating workers drain before final hashes or lease release. Cross-process status claims use PID/start identity and transition-ID compare-and-set. Failed activation keeps admission closed. Explicit recovery activates current saved files without replaying an unsaved request.

Backwards compatibility

The backend remains experimental and opt-in through KIROCREW_WINDOWS_SANDBOX_EXE; build the helper from the matching source. Unsupported guarantees refuse the launch. Linux namespace, macOS Seatbelt and explicit Kiro delegation keep their existing paths.

Windows Codex defaults to <Crew data home>/codex. Explicit CODEX_HOME remains authoritative. Existing desktop chats are left intact; the private profile has independent auth-file state. Other server routing and backend sharing choices remain operator-controlled.

Reader: src/kiro_crew/acp/harness/codex.py:resolve_spawn_masks -- entry: chat -- still refuses an enforced spawn without its credential mask.
Reader: src/kiro_crew/sandbox_spawn.py:shielded_prepare_off_loop -- entry: cron|subagent|app -- retains one policy-artifact cleanup path; the runtime-owned channel descriptor lives in private scratch.
Reader: src/kiro_crew/sandbox_wrap.py:wrap_argv -- entry: chat|cron|subagent|app -- retains the existing non-Windows and Kiro delegation decisions.

Reader: src/kiro_crew/mcp_gateway/native_session.py:finalize -- entry: chat|cron|subagent|app -- binds the final native MCP roster after runtime mounts and requires enabled broker routes.

Tests

  • Native routing regressions: 146 passed across session create/resume, Codex projection, native scope, private profile and final-roster composition.
  • Real Windows MXC fixture: Core and Cron complete authenticated tool calls; Work and Dashboard return nonempty tool lists through the final-session broker path while the agent cannot read the SEL key. Missing launch approvals and tampered scope MACs are rejected.
  • Actual Codex ACP 2.2.2 + Codex 0.164.0 under native MXC: source and installed 0.10 backport both expose all four managed catalogs to the synthetic model; skill_search and cron_list complete through two ACP approval requests. The agent cannot read the SEL key. Global MCP configuration is empty, so the test exercises the session array. Production key metadata/ACL and Crew settings are unchanged by the local repair.
  • Normal Crew AcpRuntime.spawn() / create_session() also completes with all four catalogs and two trusted, approved tool calls in both the source tree and installed backport. Late mounts republish their claim even when the base roster was empty.
  • Reproduced and fixed per-entry channel signing and asynchronous MCP startup; create/load metadata, final-roster claims and scope tampering are covered by regressions. An additional 18 architecture contracts and 20 launch/profile regressions pass.
  • mypy: 3,660 source files; targeted lint/import checks, pinned Black 26.10.1, subprocess encoding, file-size, comment-history, brand and harness-parity checks pass.
  • Native helper: 8 Rust tests, rustfmt and the locked offline release build against the pinned SDK. The real tests use Windows 10.0.26200 and Codex 0.164.0.
  • Local gate reached 98% before a Windows worker crashed and its replacement restarted collection; the run was stopped and is not a pass. Comparing 72 recorded failing cases against unchanged upstream 66c0a876 reproduced 67 failures on both trees. The one current-only launch-golden failure was fixed and its 20-case launch/profile suite passes. A scoped-runner timeout also reproduces on both trees. Missing POSIX APIs and Windows symlink privilege account for several baseline failures; remaining setup errors still need the repository CI environment.

The draft does not claim the complete local gate floor or Linux/macOS CI is green. The configured Opus review model is unavailable locally, and the final revision still requires independent maintainer review. GitHub's fork workflows require maintainer approval before they can execute.

Manual verification

Real MXC and the installed Crew servers load Core, Cron, Work and Dashboard through gatewayd. The finalizer also handles the direct managed entries appended by member/panel mounts; session creation and resume are covered separately. Privileged servers retain the required-broker refusal path, current launch approval and signed per-call identity.

The provider and business API are authenticated loopback fixtures with synthetic homes and keys. The Codex fixture uses a synthetic Responses provider and does not contact a model account. The installed 0.10 backport additionally completes actual ACP tool calls with the SEL key still inaccessible to the agent. This does not claim a whole-app real-provider GUI end-to-end test. The separate CreateDesktopW denial from Codex shell sandbox startup is not covered by the MCP repair.

Operations and rollback: docs/guides/windows-install.md, scripts/configure_windows_codex_home.py, and scripts/recover_windows_native_routing.py.

Screenshots / video

Actual rendering of the isolated component fixture, with synthetic state: saved but failed activation (desktop), and explicit interruption confirmation (390px).

Saved settings with failed activation

Explicit restart confirmation on a narrow viewport

Related Issues

Part of #16406

Related alternative: #7140 uses WSL2; this proposal runs natively.

Sibling sweep

Swept: git grep -nE 'fallback_exec|write_config_atomically|agent_model_state.json|stub_overrides|CODEX_HOME|_terminate_process' -- src/kiro_crew
Sibling: src/kiro_crew/mcp_gateway/stub_fallback.py -- changed here -- blocks masked-trust managed servers before resolving a direct command.
Sibling: src/kiro_crew/config/loader_document.py -- changed here -- fences supported config aliases before resolution.
Sibling: src/kiro_crew/atomic_write.py -- changed here -- fences all three protected-document publication paths, including model-state writers.
Sibling: src/kiro_crew/acp/runtime_session_setup.py -- changed here -- builds the base roster; native create/load sign only after member and panel mounts.
Sibling: src/kiro_crew/mcp_gateway/manager.py -- changed here -- keeps original owned Windows receipts through confirmed tree retirement.
Sibling: src/kiro_crew/sandbox_plan.py -- changed here -- preserves immutable ancestors and independent credential floors around private windows.

Pattern harvest

Use the existing ownership receipts and an exclusive publication lease rather than weakening immutable file pins. Keep transport failure distinct from authorization and activation state.

Checklist

  • Conventional Commits feature and follow-up fix; two commits total.
  • Native integration, regression and deterministic-order evidence recorded.
  • Self-review completed.
  • Independent review of the final revision and maintainer design review.
  • Owning security, ACP, MCP lifecycle, config, runtime ownership and Windows docs updated.
  • No accounts, credentials, installer payload or binary helper in the diff.
  • Complete local gate floor and cross-platform repository CI pass.

Contribution License Agreement

Submitted under the repository's Apache-2.0 contribution terms.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Oct 25, 2026
@muhmuhkuh
muhmuhkuh force-pushed the feat/native-windows-mxc branch from 8a72fa0 to d17bf80 Compare October 26, 2026 02:06
@muhmuhkuh muhmuhkuh changed the title feat: add an opt-in native windows sandbox for codex feat: support native Windows Codex and protected Crew tools Oct 26, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 26, 2026
@muhmuhkuh
muhmuhkuh force-pushed the feat/native-windows-mxc branch from d17bf80 to 34fdc5c Compare October 26, 2026 12:01
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 26, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 27, 2026
@muhmuhkuh
muhmuhkuh force-pushed the feat/native-windows-mxc branch from 0135f47 to f45942b Compare November 3, 2026 08:51
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 3, 2026
@muhmuhkuh
muhmuhkuh force-pushed the feat/native-windows-mxc branch 2 times, most recently from 19108a7 to 2abbd1c Compare November 4, 2026 12:17
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 4, 2026
@muhmuhkuh
muhmuhkuh force-pushed the feat/native-windows-mxc branch from 2abbd1c to f4c1de7 Compare November 4, 2026 16:09
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 4, 2026
@muhmuhkuh
muhmuhkuh force-pushed the feat/native-windows-mxc branch 2 times, most recently from c2b3149 to 6b8f01b Compare November 4, 2026 20:13
@muhmuhkuh
muhmuhkuh force-pushed the feat/native-windows-mxc branch 2 times, most recently from a392fd4 to fd41c79 Compare November 5, 2026 04:04
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 5, 2026
@muhmuhkuh
muhmuhkuh force-pushed the feat/native-windows-mxc branch from fd41c79 to 0f6adcc Compare November 5, 2026 08:05
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 5, 2026
muhmuhkuh and others added 2 commits November 5, 2026 13:08
Finalize managed broker entries after runtime mounts, bind their claims
and channels, and await MCP readiness before the first turn. Keep
protected SEL material outside the native agent sandbox and admit
assigned Work broker stubs.
@muhmuhkuh
muhmuhkuh force-pushed the feat/native-windows-mxc branch from 0f6adcc to 4cf59e3 Compare November 5, 2026 12:08
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 5, 2026
@muhmuhkuh muhmuhkuh closed this Nov 11, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 11, 2026
@muhmuhkuh
muhmuhkuh deleted the feat/native-windows-mxc branch November 11, 2026 08:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant