roadmap(windows): make Windows a supported platform

[liugddx]

Problem

Maka can already build and launch its CLI and Electron desktop app on Windows, and the codebase includes Windows-specific paths for named pipes, PowerShell/cmd shell detection, ConPTY, process-tree termination, and filesystem behavior. However, Windows is not currently a supported platform because these paths are not continuously tested or released, and several product guarantees remain platform-specific.

A local Windows baseline on Node 22 found:

• the full repository build succeeds;
• script tests can pass after removing POSIX-only assumptions from macOS development helper tests;
• managed workspace tests require Git for Windows long-path support (core.longpaths=true);
• the storage suite currently reports 514 pass / 100 fail / 40 skip;
• most remaining storage failures are EBUSY cleanup failures caused by SQLite handles still owning runtime.sqlite or runtime.sqlite-shm, which POSIX permits unlinking but Windows does not;
• restricted sandbox profiles fail closed on Windows;
• computer-use has no Windows backend.

Being able to open the app is therefore not the same as having a tested, secure, releasable Windows product.

Desired outcome

Define and deliver an explicit Windows support tier for Maka. At minimum, supported CLI and desktop workflows should build, test, install, update, recover from crashes, and fail safely on every release. Features that cannot initially be supported, especially sandboxing and computer-use, must be clearly surfaced rather than silently degraded.

Current support status (2026-08-25)

Windows 11 x64 remains an active preview target, not a fully supported Maka platform. Phase 0-2 build, baseline, crash-recovery, process-cleanup, and durability evidence are in place. Phase 3 preview packaging, checksum/install documentation, closed-app upgrade/uninstall, automatic update, Runtime Host update handoff, and the accepted Abort/Quit recovery boundary are complete; Authenticode signing is the only remaining Phase 3 implementation gate and is tracked by #3414.

The shipped W1 filesystem-worker AppContainer surface has now completed its Phase 4 automated and independent-review gates. #3558 promotes the lifecycle checks into the shared pull-request/formal-release verifier and protects its trigger/source closure; #3586 verifies explicit post-dispatch client cancellation; #3722 closes Runtime Host parent-death, owner binding, Job drain, a 64-launch soak, quarantined ACL-ledger non-reuse, and the scoped adversarial matrix. All three are merged, and #3722 received exact-head independent maintainer approval with no P0-P3 findings.

This completes the current W1 preview sandbox gate, not general Windows support and not the wider W2 command tier. Full support still requires signed artifacts, a current authoritative Windows baseline with required gates, and a final support-declaration cutover. Windows computer-use and the explicitly deferred sandbox-hardening rows remain separate future work.

Phase 0: establish the baseline

Tracking PR: #2156

• Document supported Windows versions, architecture, Node version, shell prerequisites, and Git requirements.
• Run the complete test plan on windows-latest and publish pass/fail/skip results.
• Inventory every process.platform === 'win32' skip and classify it as POSIX-only, portable, or missing Windows implementation.
• Add a Windows CLI smoke test and Electron startup smoke test.

Phase 1: continuous Windows correctness

Tracking PR: #2173

Current status (2026-08-08): the combined Node 24 main Windows storage baseline is 703 pass / 6 fail / 47 skip, improved from the original 514 / 100 / 40. The non-blocking baseline lane retains complete diagnostics as artifacts.

Completed Phase 1 failure groups include project-catalog and usage-store SQLite shutdown, portable Codex/sandbox path handling, and deterministic Git worktree retirement on Windows. Current implementation focus is grouped by root cause rather than individual failing tests:

• root-authority file identity, replacement, lock, and initialization races: completed by fix(storage): serialize root marker repair on Windows #2438;

• session-bundle deterministic metadata and atomic hydration semantics: completed by test(storage): cover Windows session bundle metadata #2449;

• managed Git head-ref long-path fixture: completed by test(storage): enable long paths for bare Git fixtures #2435;

• Windows skip inventory refresh: completed by docs(windows): refresh test skip inventory #2434.

• Add a required or explicitly non-blocking windows-latest CI lane while the backlog is being burned down. Completed by ci(windows): add non-blocking baseline lane #2173.

• Enable Git for Windows long-path handling in managed workspace operations. Completed by test(windows): establish support baseline #2156.

• Close SQLite stores, owners, and leases deterministically before temporary-root cleanup; do not mask open-handle bugs with broad retry loops. Completed across test(storage): close project catalogs before cleanup #2339, test(storage): close agent run stores before cleanup #2341, fix(runtime): classify expired probe budget as timeout #2344, test(computer-use): synchronize session cancellation #2345, and fix(storage): close usage stores after lease revocation #2365.

• Validate named-pipe endpoint lifecycle and two-client runtime-host flows on Windows. Completed by test(runtime-host): validate Windows named-pipe clients #2464.

• Validate ConPTY, cancellation, taskkill /T, and descendant cleanup behavior. Completed by test(runtime): validate Windows process lifecycle #2465.

• Unskip portable tests and retain narrowly explained skips only for genuinely POSIX-specific contracts. Completed by test(windows): resolve portable skip inventory #2470.

Phase 2: crash and recovery guarantees

• Run managed-workspace, SQLite, runtime continuation, and runtime-host failpoint/crash harnesses on Windows. Completed by test(windows): validate crash recovery boundaries #2475, test(runtime-host): validate Windows artifact recovery #2488, test(runtime-host): validate Windows crash recovery #2492, test(windows): run managed workspace crash gates #2509, and the dedicated Windows recovery lane in ci(windows): require crash recovery evidence #2562.
• Verify atomic publication/replacement semantics and document any weaker Windows durability guarantees. Recovery evidence completed by test(runtime-host): validate Windows artifact recovery #2488; the Windows durability boundary is documented by docs(windows): define crash durability boundary #2553.
• Ensure test and production process trees leave no orphaned host, CLI fixture, shell, or Git processes. Windows ConPTY, cancellation, descendant cleanup, and taskkill behavior were completed by test(runtime): validate Windows process lifecycle #2465; the baseline retains a residual-process audit.
• Define dedicated Windows recovery evidence. ci(windows): require crash recovery evidence #2562 adds the windows_recovery lane and validates SQLite, Runtime continuation, Runtime Host owner-death, and managed-workspace crash recovery on every pull request and main push.

Repository administration follow-up:

• Configure windows_recovery as a required check in the effective GitHub ruleset. The workflow is green on the ci(windows): require crash recovery evidence #2562 merge commit, but the current token cannot verify or modify organization-level rulesets.

Phase 3: distribution

Current status (2026-08-25): Windows x64 preview packaging, checksum verification, installation documentation, closed-app upgrade/uninstall, CI-verified automatic updates (#3240), safe Runtime Host update handoff (#3382), and the accepted Abort/Quit recovery boundary (#3265) are complete. Authenticode identity acquisition and release-workflow signature verification remain the only Phase 3 implementation gate and are tracked by #3414.

• Produce a Windows installer and portable ZIP from CI. Completed by chore(release): add the Windows x64 release path #2182.
• Verify clean install, successful closed-app upgrade, process drain, real NSIS uninstall, and installation-directory removal. Completed by test(windows): verify installer upgrades #2658.
• Publish Windows preview installation and checksum-verification documentation without claiming full support. Completed by docs(windows): document preview installation #2926.
• Add Authenticode signing and verify signatures in the release workflow. Tracked by infra: obtain ASF code signing identities for Desktop artifacts #3414; blocked on obtaining the ASF signing identity and provisioning it to the release workflow.
• Land and independently review Abort-path rollback with backup retention. Completed by feat(win): Abort-path installer rollback with backup retention #3265 (merged as 9de05e266): the final exact head passed CI/audit/Windows L3 with 234 entries restored with 0 diffs, registry-mismatch 103 retention/recovery, stale and incomplete backup 101 refusals, hookless Quit retention/adoption, registration-less 101 refusal, and fixture-scoped uninstall-registry ownership.
• Decide the formal-support boundary for hookless template Quit, hard-kill, and power-loss failures. Accepted for the Windows 11 x64 preview: verified Abort-path failures recover automatically; hookless Quit supports exact-identity rerun recovery with retained backup evidence; hard-kill and power-loss scenarios remain outside the automatic rollback guarantee and may require repair or reinstall. Full automatic recovery is deferred to a future release-hardening slice.
• Integrate and verify automatic updates. Completed by feat(release): verify Windows automatic updates end to end #3240: the packaged electron-updater path (check, background download, NSIS handoff, relaunch, full packaged smoke) is verified end to end in CI against a loopback feed; the production GitHub feed configuration is pinned by unit tests. fix(desktop): drain untracked Runtime Host before update #3382 closes the Runtime Host update-handoff process-drain defect exposed by that gate. Updates remain unsigned until Authenticode lands.

Phase 4: sandbox security (shipped W1 preview surface)

Current status (2026-08-25): the Maka-owned packaged AppContainer backend (#2961), production-identity readiness probe, per-launch private desktop, and EN/zh RFC alignment (#3174) are on main. The supported claim remains limited to the Windows 11 x64 W1 filesystem-worker preview surface with packaged fail-closed enforcement; it does not claim the wider W2 general-command tier or escape-proof GUI/window-station isolation.

The remaining W1 lifecycle and adversarial evidence is now merged:

• ci(windows): gate packaged sandbox lifecycle evidence #3558 merged as 7edc971c1: the pull-request and formal-release lanes share the packaged lifecycle verifier; esbuild-derived source closure, release-workflow triggers, and the gate workflow's own release-contract route are protected by tests.

• test(windows): verify packaged sandbox client cancellation #3586 merged as 1ecd9bd6d: explicit post-dispatch FilesystemWorkerClient cancellation drains the packaged broker/AppContainer process tree and permits a clean recovery launch.

• test(windows): close packaged sandbox lifecycle evidence #3722 merged as 7235069ad: Runtime Host parent death, validated owner-handle binding, kill-on-close Job drain, an 8-wave x 8-way (64-launch) soak, quarantined ACL-ledger non-reuse, and the scoped packaged adversarial matrix are verified. Exact-head test, package, and W0 checks passed, and independent maintainer/security review approved the head with no P0-P3 findings.

• Complete the comparative threat-model/RFC research. The initial docs(windows): define sandbox backend security contract #2940 proposal is retained only as history and is superseded by the updated RFC in feat(windows): add brokered AppContainer sandbox support #2961.

• Merge the packaged AppContainer backend, Runtime/filesystem-worker integration, release resource, and updated RFC in feat(windows): add brokered AppContainer sandbox support #2961. Completed by feat(windows): add brokered AppContainer sandbox support #2961 (merged 2026-08-17, squash commit d3a21f9).

• Align the RFC's implemented guarantees with the shipped slice. Completed by feat(windows-sandbox): place sandboxed children on a private desktop #3174: production-identity readiness and initial private-desktop placement are enforced.

• Promote cancellation, parent-death, concurrency, process-drain, and residual ACL/state evidence to the packaged/per-release gate. Completed by ci(windows): gate packaged sandbox lifecycle evidence #3558, test(windows): verify packaged sandbox client cancellation #3586, and test(windows): close packaged sandbox lifecycle evidence #3722.

• Complete the automated adversarial matrix for the shipped W1 preview surface. test(windows): close packaged sandbox lifecycle evidence #3722 covers filesystem aliases/reparse points, restricted TCP, host named pipes, descendants, ambient environment, credential-file reachability, host registry values, parent-token access, and lifecycle failures.

• Complete independent maintainer/security review for the shipped W1 preview surface. ci(windows): gate packaged sandbox lifecycle evidence #3558's review findings were closed; test(windows): close packaged sandbox lifecycle evidence #3722 was approved at exact head with no P0-P3 findings.

Explicitly deferred hardening, not claimed by the current W1 preview:

• direct Credential Manager and DPAPI probes;
• inbound-listener and UDP enforcement, plus broader DNS/SMB channel coverage;
• no-Win32k mitigation;
• dedicated window-station and clipboard isolation;
• power-loss automatic recovery;
• the wider W2 general-command sandbox tier.

These deferred rows require their own scoped issues and threat-model decisions before implementation. They do not reopen the completed W1 preview evidence gate unless maintainers expand the advertised W1 contract.

Next execution plan

1. Finish Phase 3 signing (infra: obtain ASF code signing identities for Desktop artifacts #3414). Obtain the ASF Authenticode identity, provision release secrets/identity safely, sign the Windows release artifacts, and make signature verification a required release step. Acceptance: an exact-head Windows release run verifies the expected signer and fails closed for unsigned, mismatched, or tampered artifacts.
2. Make the Windows baseline authoritative (ci(windows): eliminate hidden failures in the non-blocking baseline #2624 plus repository administration). Refresh the full Node/current-main Windows baseline, eliminate hidden failures, keep only contractually POSIX-specific skips, and configure windows_recovery as a required check in the effective ruleset. Acceptance: the clean Windows runner has an explicit pass/fail/skip inventory and no non-blocking failure can be mistaken for support evidence.
3. Prepare the support-declaration cutover PR. After signing and required-gate work are complete, update the support matrix, installation/update documentation, and in-product capability wording together; rerun clean install, upgrade, rollback/recovery, and W1 sandbox release evidence. Only this PR should change Windows from preview to supported.
4. Split deferred sandbox hardening into independent issues. Prioritize direct credential probes and network-channel coverage first; keep Win32k/window-station/clipboard, power-loss recovery, and W2 as separately reviewable slices. Do not mix these with the support-declaration PR unless the advertised contract is expanded.
5. Continue Phase 5 computer-use separately. UI Automation/capture, consent/elevation, multi-monitor/scaling, secure desktop, and session-lock behavior remain a distinct product project and should not be implied by W1 filesystem sandbox completion.

The unrelated eval process-group timing failure observed while validating #3722 is tracked separately in #3770 and is not a Windows support blocker.

Phase 5: computer-use

• Define a Windows backend using UI Automation plus an appropriate capture API.
• Design consent, secure-desktop, elevation, multi-monitor, scaling, and session-lock behavior.
• Reuse the platform-neutral computer-use host event contract.
• Add Windows-specific integration and end-to-end evidence.

Support criteria

Windows should be advertised as supported only when:

• the supported CLI and desktop workflows pass on a clean Windows CI runner;
• no required feature silently falls back to an unenforced security boundary;
• crash recovery and process cleanup have release evidence;
• signed install and update artifacts are published;
• unsupported or deferred capabilities are explicit in-product and in documentation.

Alternatives or workarounds

Today, developers can run the CLI directly and launch the Electron desktop app in development mode on Windows. WSL2 can provide a Linux execution environment for some workflows. Neither workaround supplies a native Windows release, Windows sandbox enforcement, Windows computer-use, or release-level regression coverage.

This umbrella issue is intentionally phased. CI, storage lifecycle correctness, and distribution can proceed before the sandbox and computer-use projects, while the support criteria prevent partial availability from being mistaken for full platform support.

[liugddx]

Windows follow-up update (2026-08-07):

• test(storage): close project catalogs before cleanup #2339 is merged. Its Windows baseline improved from 648 pass / 38 fail / 38 skip to 664 pass / 22 fail / 38 skip, removing the 16 project-catalog cleanup failures.
• Rebased and retriggered CI after the GitHub Actions incident for test(storage): close agent run stores before cleanup #2341, fix(runtime): classify expired probe budget as timeout #2344, and test(computer-use): synchronize session cancellation #2345. Required checks are passing or still running; their non-blocking Windows baselines are in progress.
• Opened fix(storage): close usage stores after lease revocation #2365 for the remaining usage-store SQLite handles: close now releases local telemetry/model-call/pricing resources even after root identity failure or lease revocation, while ordinary operations remain lease-bound. This targets the final 3 usage-store cleanup failures from the measured baseline.

Next: verify the fresh Windows artifacts, merge the isolated fixes as their checks settle, then recalculate the remaining #2142 failure inventory.

[TomXPRIME]

@liugddx 你好，请问能顺便修复调用pwsh时的编码问题吗？在CJK环境下用UTF-8解码GBK输出会导致乱码

[liugddx]

@liugddx 你好，请问能顺便修复调用pwsh时的编码问题吗？在CJK环境下用UTF-8解码GBK输出会导致乱码

可以提issue关联过来，有空就来修~

[TomXPRIME]

#2366 好的，谢谢大佬，我已经提出issue啦。目前opencode的v2（尚在beta）阶段好像修复了这个issue

[liugddx]

Windows Phase 1 update (2026-08-07, second pass):

• test(storage): close agent run stores before cleanup #2341, fix(runtime): classify expired probe budget as timeout #2344, and test(computer-use): synchronize session cancellation #2345 are merged.
• Refreshed fix(storage): close usage stores after lease revocation #2365 with aa1fe4ac4 after reproducing the remaining usage-store failure. The usage-store target now reports 7 pass / 0 fail / 1 narrowly explained skip on Windows; new CI is pending.
• Opened fix(storage): keep portable path tests stable on Windows #2395 for two portable-path failures: Codex SQLite cwd filtering now preserves source-native and host-normalized path variants before LIMIT, and the sandbox-boundary fixture now uses the POSIX path domain required by the contract.
• On the combined local Windows branch (Node 22), storage moved from 677 pass / 18 fail / 44 skip to 678 pass / 14 fail / 45 skip. This is a development measurement, not the final Node 24 Actions baseline; the fresh PR artifacts will be authoritative.

The remaining local failures are now grouped into Windows symlink privilege coverage, Git fixture/process cleanup, Git worktree removal, root-authority file identity/locking semantics, session-bundle path/symlink behavior, and two Node/environment-sensitive import checks.

Next: settle #2365/#2395 CI, recalculate from their Windows artifacts, then take the Git process/worktree cleanup group without adding broad filesystem retries.

[liugddx]

Windows Phase 1 update (2026-08-07, post-rebase baseline):

• fix(storage): close usage stores after lease revocation #2365, test(headless): remove trim residue #2410, test(desktop): stop exporting trimmed helpers #2414, and fix(desktop): drop dead css-test-helpers after #2406 #2415 are merged.
• fix(storage): keep portable path tests stable on Windows #2395 has been rebased onto current main; all required checks and its non-blocking Windows baseline pass. The PR remains open pending merge.
• The authoritative Node 24 Windows storage run on fix(storage): keep portable path tests stable on Windows #2395 reports 691 pass / 10 fail / 39 skip. The previous run was 692 / 9 / 39; the additional failure is sqlite-recovery-concurrency, so that group is currently environment/timing-sensitive rather than a stable regression count.
• The 10 failures are grouped as Git workspace/ref (1), Git worktree retirement/removal (2), root-authority identity/locking/races (5), session-bundle path/atomic hydration (1), and SQLite recovery concurrency (1).
• The Windows skip inventory is stale and needs regeneration.

Next: take the three Git workspace/worktree failures as one narrowly scoped Windows cleanup group, without adding broad filesystem retries; update the skip inventory separately.