roadmap(windows): make Windows a supported platform

## 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

- [x] Document supported Windows versions, architecture, Node version, shell prerequisites, and Git requirements.
- [x] Run the complete test plan on `windows-latest` and publish pass/fail/skip results.
- [x] Inventory every `process.platform === 'win32'` skip and classify it as POSIX-only, portable, or missing Windows implementation.
- [x] 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 #2438;
- session-bundle deterministic metadata and atomic hydration semantics: completed by #2449;
- managed Git head-ref long-path fixture: completed by #2435;
- Windows skip inventory refresh: completed by #2434.

- [x] Add a required or explicitly non-blocking `windows-latest` CI lane while the backlog is being burned down. Completed by #2173.
- [x] Enable Git for Windows long-path handling in managed workspace operations. Completed by #2156.
- [x] Close SQLite stores, owners, and leases deterministically before temporary-root cleanup; do not mask open-handle bugs with broad retry loops. Completed across #2339, #2341, #2344, #2345, and #2365.
- [x] Validate named-pipe endpoint lifecycle and two-client runtime-host flows on Windows. Completed by #2464.
- [x] Validate ConPTY, cancellation, `taskkill /T`, and descendant cleanup behavior. Completed by #2465.
- [x] Unskip portable tests and retain narrowly explained skips only for genuinely POSIX-specific contracts. Completed by #2470.

### Phase 2: crash and recovery guarantees

- [x] Run managed-workspace, SQLite, runtime continuation, and runtime-host failpoint/crash harnesses on Windows. Completed by #2475, #2488, #2492, #2509, and the dedicated Windows recovery lane in #2562.
- [x] Verify atomic publication/replacement semantics and document any weaker Windows durability guarantees. Recovery evidence completed by #2488; the Windows durability boundary is documented by #2553.
- [x] 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 #2465; the baseline retains a residual-process audit.
- [x] Define dedicated Windows 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 #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.

- [x] Produce a Windows installer and portable ZIP from CI. Completed by #2182.
- [x] Verify clean install, successful closed-app upgrade, process drain, real NSIS uninstall, and installation-directory removal. Completed by #2658.
- [x] Publish Windows preview installation and checksum-verification documentation without claiming full support. Completed by #2926.
- [ ] Add Authenticode signing and verify signatures in the release workflow. Tracked by #3414; blocked on obtaining the ASF signing identity and provisioning it to the release workflow.
- [x] Land and independently review Abort-path rollback with backup retention. Completed by #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.
- [x] 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.
- [x] Integrate and verify automatic updates. Completed by #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. #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:

- #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.
- #3586 merged as `1ecd9bd6d`: explicit post-dispatch `FilesystemWorkerClient` cancellation drains the packaged broker/AppContainer process tree and permits a clean recovery launch.
- #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.

- [x] Complete the comparative threat-model/RFC research. The initial #2940 proposal is retained only as history and is superseded by the updated RFC in #2961.
- [x] Merge the packaged AppContainer backend, Runtime/filesystem-worker integration, release resource, and updated RFC in #2961. Completed by #2961 (merged 2026-08-17, squash commit `d3a21f9`).
- [x] Align the RFC's implemented guarantees with the shipped slice. Completed by #3174: production-identity readiness and initial private-desktop placement are enforced.
- [x] Promote cancellation, parent-death, concurrency, process-drain, and residual ACL/state evidence to the packaged/per-release gate. Completed by #3558, #3586, and #3722.
- [x] Complete the automated adversarial matrix for the shipped W1 preview surface. #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.
- [x] Complete independent maintainer/security review for the shipped W1 preview surface. #3558's review findings were closed; #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 (#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 (#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;
- [x] crash recovery and process cleanup have release evidence;
- [ ] signed install and update artifacts are published;
- [x] 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.