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-24)

Windows 11 x64 is 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. Preview installer/ZIP artifacts, checksum/install documentation, closed-app upgrade/uninstall, automatic update, and the Runtime Host update-handoff fix (#3382, closing #3340) are complete. #3265 is merged (commit 9de05e266) with exact-head CI, audit, scoped-registry rollback evidence, and Windows L3 green. Full support still requires signed artifacts, a clean/authoritative Windows baseline, the remaining sandbox security gates, and explicit handling of deferred capabilities such as computer-use.

The packaged AppContainer backend (#2961), production-identity readiness probe, and private-desktop placement/RFC alignment (#3174, including #3161) are on main. They complete the shipped-preview alignment milestone, not the Windows support declaration. The remaining Phase 4 lifecycle evidence promotion, adversarial matrix, and independent human security-review gates below are still open.

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-24): Windows x64 preview packaging, checksum verification, installation documentation, closed-app upgrade/uninstall, CI-verified automatic updates (#3240), safe Runtime Host update handoff (#3382), and Abort-path rollback with backup retention (#3265) are complete. Signing is still blocked on an Authenticode certificate decision, so the preview is not a signed release channel.

• 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.
• 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

Current status (2026-08-24): #2961 provides the Maka-owned packaged AppContainer backend. #3174 merged the production-identity readiness probe, per-launch private-desktop placement, and EN/zh RFC alignment (fully containing the earlier #3161 work). The supported claim remains limited to a Windows 11 x64 preview with packaged fail-closed enforcement and initial private-desktop placement; it does not claim escape-proof GUI/window-station isolation or make Windows generally supported.

Mechanism-level cancellation, parent-death, concurrency, Job drain, and ACL-ledger recovery evidence exists. #3558 promotes the existing lifecycle smokes into the shared packaged/per-release verifier; exact head f65dc9d15 has Core, dependency-audit, and Release Windows checks green; the PR remains open pending maintainer review and one review-thread resolution. #3586 merged on 2026-08-23 with explicit client-cancel evidence through FilesystemWorkerClient and the packaged AppContainer child. The lifecycle checkbox remains open until #3558 merges and Runtime-Host-mid-launch, sustained-soak, and unsettled-state recovery gaps are covered.

• 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; no-Win32k, dedicated window station/clipboard isolation, token boundary, in-child GUI proof, durable unsettled-identity quarantine, and active running-host recovery remain explicit later gates.
• Promote cancellation, parent-death, concurrency, process-drain, and residual ACL/state release evidence to a required packaged/per-release gate; add Runtime-Host-dies-mid-launch coverage, explicit client-cancel coverage, sustained concurrency soak, and the documented unsettled-state recovery cases. ci(windows): gate packaged sandbox lifecycle evidence #3558 covers packaged/per-release promotion and remains open pending maintainer review; test(windows): verify packaged sandbox client cancellation #3586 covers explicit client cancel and is merged. Runtime Host mid-launch, sustained soak, and unsettled-state recovery remain open.
• Complete the adversarial escape matrix across filesystem aliases/reparse points, network channels, IPC, descendants, environment, credentials, registry, and lifecycle failures.
• Complete independent human security review and resolve every high/critical finding before advertising restricted profiles as supported.

Windows sandbox support remains preview-only until the remaining lifecycle, adversarial, documentation-alignment, and independent-review gates are complete.

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.