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

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

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

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.

@liugddx

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

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

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

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

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.

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.

Follow-up implementation: #2424 fixes the two deterministic Windows worktree retirement failures by running the final git worktree remove from the stable Git common directory rather than from inside the directory being removed. The affected tests pass in three consecutive local Windows runs (6/6).

The managed head-ref conflict test passes on current main locally; the next Node 24 baseline will determine whether that prior failure remains after recent main changes. A separate temp-root cleanup EBUSY was observed and is intentionally not hidden with broad retries in #2424.

Windows Phase 1 update after #2395 and #2424 merged:

The combined main Node 24 Windows storage baseline is now 699 pass / 7 fail / 41 skip.
Both deterministic Git worktree retirement failures fixed by fix(storage): remove Windows worktrees outside their cwd #2424 are gone.
Opened docs(windows): refresh test skip inventory #2434 to refresh the stale skip inventory (68 -> 70 declarations; both additions are pet-pack portable candidates).
Opened test(storage): enable long paths for bare Git fixtures #2435 for the final Git workspace failure. The product runtime already enables core.longpaths=true; the conflict fixture's direct bare-Git helper did not, so Actions failed while creating a deeply nested ref before exercising the CAS behavior. The target passes locally with a CI-depth TEMP root after aligning the helper.

Once #2435 lands, the remaining stable groups are root-authority identity/locking (5) and session-bundle path/atomic hydration (1).

Windows Phase 2 update (2026-08-09):

test(windows): run managed workspace crash gates #2509 merged and completes the managed-workspace real-process crash evidence.
docs(windows): define crash durability boundary #2553 is open with green checks and documents the Windows durability boundary: file-content and SQLite WAL/FULL guarantees are distinguished from POSIX-equivalent parent-directory durability during sudden power loss.
Opened ci(windows): require crash recovery evidence #2562 to make the already-landed recovery evidence release-blocking through a dedicated required windows_recovery job.
The new clean Windows Node 24 job passed end to end in about three minutes: install, full test build, SQLite crash recovery, Runtime resume/continuation recovery, Runtime Host owner-death recovery, and managed-workspace crash convergence.
The Windows installer/ZIP packaging and verification job also passes on ci(windows): require crash recovery evidence #2562.
Runtime's two real-process crash harnesses retain the 60-second POSIX budget and use a 120-second Windows budget; a contract test pins that platform-specific boundary.

Current PR-level noise is unrelated to the recovery changes: Storybook repeatedly reports the existing Daily Review 480px overflow and Lucide icon story failure, while one E2E rerun missed the quote companion selection overlay. Standard workspace tests, typecheck, Runtime Host tests, Windows baseline, Windows recovery, and Windows packaging pass.

Next: merge #2553 and #2562 after maintainer review, then mark the Phase 2 durability/release-evidence items complete and move to the remaining process-tree evidence/distribution work.

Windows CI efficiency update (2026-08-09)

Opened #2599 to reduce the ordinary Windows baseline critical path without weakening the evidence owned by each affected surface.

Measured baseline from #2523: 6m31s total. The serialized Storage suite took 3m22s, managed-workspace crash recovery took 46s, and Windows smoke spent another 26s while rebuilding artifacts already produced by build:test.

#2599 now:

reuses the existing repository impact planner for Windows scheduling;
skips the Windows runner for documentation-only changes;
keeps build and real CLI/Electron startup smoke for Desktop/UI changes;
selects the Runtime PTY gate only for Runtime impact;
selects the full Storage and managed-workspace crash gates only for Storage impact;
reuses the existing test build for smoke instead of rebuilding;
fails safe to the complete Windows suite for missing Git history, global changes, or unknown production paths.

Expected result: Desktop/UI pull requests avoid roughly 4 minutes of unrelated Storage/Crash work while retaining Windows startup evidence. Runtime and Storage changes keep their respective platform evidence. The dedicated release-blocking recovery gate remains tracked by #2562; #2599 does not replace it.

Verification: 12 tests pass, 1 Windows-only test is skipped locally; workflow YAML parsing, Biome, and diff checks pass.

中文进展

已提交 #2599，用于缩短日常 Windows baseline 的关键路径，同时不削弱各影响面负责的证据。

从 #2523 测得：总耗时 6 分 31 秒，其中串行 Storage 测试 3 分 22 秒，managed-workspace crash recovery 46 秒；Windows smoke 还用了约 26 秒重复构建 build:test 已经生成的产物。

#2599 的调整：

Windows 调度复用仓库现有的影响面计算；
纯文档改动不再占用 Windows runner；
Desktop/UI 改动仍保留构建和真实 CLI/Electron 启动 smoke；
Runtime 受影响时才运行 Windows PTY gate；
Storage 受影响时才运行完整 Storage 与 managed-workspace crash gate；
smoke 复用已有测试构建，不再重复构建；
Git 历史缺失、全局配置或未知生产路径变更时，安全回退为完整 Windows 套件。

预期 Desktop/UI PR 可减少约 4 分钟无关的 Storage/Crash 工作，同时保留 Windows 启动证据。Runtime 与 Storage 变更仍保留各自的 Windows 平台证据。#2562 的 release-blocking recovery gate 仍独立推进，#2599 不会替代它。

本地验证：12 项通过、1 项仅 Windows 运行而跳过；workflow YAML、Biome 与 diff 检查均通过。

Windows Phase 2 completion update (2026-08-10):

test(windows): run managed workspace crash gates #2509 and docs(windows): define crash durability boundary #2553 are merged, completing managed-workspace crash evidence and the documented Windows durability boundary.
ci(windows): require crash recovery evidence #2562 is merged. Its dedicated windows_recovery workflow passed on the merge commit in 3m41s, covering SQLite crash recovery, Runtime continuation recovery, Runtime Host owner-death recovery, and managed-workspace crash convergence.
The merge commit Windows baseline also passed in 2m44s and retains the residual-process audit; process-tree behavior was previously completed by test(runtime): validate Windows process lifecycle #2465.
Phase 2 engineering work is now complete. One repository-administration follow-up remains: configure windows_recovery as a required check in the effective GitHub ruleset.

Next: audit the existing Windows package output and start Phase 3 with the smallest complete distribution slice: installer production plus clean-run verification.

中文进展

Windows Phase 2 已完成：#2509、#2553、#2562 均已合并；合并提交上的 Windows recovery（3分41秒）和 baseline（2分44秒）均通过。恢复流水线覆盖 SQLite、Runtime continuation、Runtime Host owner-death 与 managed workspace 崩溃恢复，进程树证据由 #2465 和 baseline 残留进程审计覆盖。

剩余一项仓库治理配置：需要管理员在实际生效的 GitHub ruleset 中把 windows_recovery 设为 required check。下一步进入 Phase 3，先审计现有 Windows 打包产物，再完成安装器生成与干净环境验证闭环。

Phase 3 has started with #2650.

The installer-production checkbox is now marked complete based on #2182 and the existing Windows packaging workflow. #2650 adds the missing artifact-level lifecycle evidence: install the final NSIS .exe into an isolated directory, verify the installed app (resources, version, ConPTY, renderer), then run the shipped uninstaller and require complete removal. Upgrade/rollback remains explicitly out of scope for this PR.

中文进展

Phase 3 已由 #2650 启动。基于 #2182 和现有 Windows 打包工作流，“CI 生成安装器”已经勾选完成。#2650 补充最终 NSIS .exe 的真实生命周期证据：隔离安装、从安装目录验证资源/版本/ConPTY/桌面渲染器、运行自带卸载器并确认完整移除。跨版本升级和失败回滚仍明确留给后续任务。

Windows Phase 3 lifecycle update (2026-08-11):

test(windows): exercise installer lifecycle #2650 merged and completes clean NSIS install, installed-app verification, Runtime Host drain, and uninstall-directory removal evidence.
Opened test(windows): verify installer upgrades #2658 for version transition evidence. It selects the newest stable release below the candidate, verifies the published SHA-256, installs that release, proves a malformed candidate cannot change the installed version, then upgrades to and fully verifies the current candidate before uninstalling.
The failure contract is deliberately narrow: deterministic pre-install failure isolation, not arbitrary power-loss recovery during NSIS replacement.

中文进展

#2650 已合并，完成干净安装、真实安装目录验证、Runtime Host 退出等待和 NSIS 完整卸载证据。新 PR #2658 补跨版本证据：选择最近稳定旧版本、校验发布 SHA-256、安装旧版本、验证损坏候选不会改变旧安装、升级并完整验证当前候选，最后卸载。失败边界明确为安装前失败隔离，不宣称覆盖 NSIS 替换文件过程中的任意断电。

Windows Phase 3 upgrade update (2026-08-12):

test(windows): verify installer upgrades #2658 merged. The release workflow now pins the reviewed v0.1.9 NSIS artifact by exact tag, asset name, and repository-owned SHA-256.
On the merge-ready Windows run, the verifier completed the real closed-app transition: v0.1.9 install and full packaged-app smoke -> installed-process drain -> current candidate upgrade in the same install/profile paths and full smoke -> process drain -> real NSIS uninstall and directory removal.
The evidence boundary remains explicit: this proves a successful closed-app upgrade, not persisted business-state migration, running-app upgrade, automatic update, or rollback after a mid-install failure. Therefore the combined install/upgrade/rollback/failure checkbox remains open.

Next: design the smallest deterministic NSIS failure/rollback experiment. It must enter the real installer replacement path and then prove the previous installation tree is byte-identical and still launches; a loader-rejected or pre-install invalid executable is not sufficient evidence.

中文进展

#2658 已合并。发布流水线现在按精确 tag、资产名和仓库固定 SHA-256 锁定 v0.1.9 NSIS 安装包。Windows 实测完成了真实的关闭状态升级闭环：安装并完整验证 v0.1.9 -> 等待安装目录内进程退出 -> 在相同安装目录和 profile 路径覆盖升级当前候选并完整验证 -> 再次等待进程退出 -> 运行真实 NSIS 卸载器并确认目录移除。

证据边界保持明确：这证明成功的关闭状态升级，不证明业务状态迁移、运行中升级、自动更新或安装中途失败后的 rollback。因此 install/upgrade/rollback/failure 组合项暂不勾选。

下一步设计最小、确定性的 NSIS 失败/rollback 实验：失败必须真正进入安装器替换路径，随后验证旧安装目录树逐文件哈希完全一致且旧版本仍可启动；仅让 Windows loader 拒绝无效 exe 不构成 rollback 证据。

Phase 3 follow-up: opened #2926 for Windows preview publication and installation documentation. It documents checksum verification, the expected unsigned SmartScreen warning, setup/uninstall steps, and the exact upgrade evidence boundary without advertising Windows as fully supported.

Rollback audit: electron-builder inserts customInstall only after application files, registry data, and shortcuts have already been replaced. Forcing an error there would create a partial install; NSIS/electron-builder does not restore the previous tree. Therefore a synthetic failpoint alone cannot honestly complete rollback evidence. A future rollback slice first needs a transactional backup/restore design, then a deterministic mid-install failure and byte-identical old-tree plus old-app smoke proof.

中文进展

已提交 #2926，补充 Windows 预览版发布与安装文档：校验和、未签名 SmartScreen 提示、配置/卸载步骤，以及准确的升级证据边界，同时不提前宣称 Windows 已正式支持。

Rollback 审计确认：electron-builder 的 customInstall 钩子发生在应用文件、注册表和快捷方式已经替换之后；此处强制失败只会制造半安装状态，NSIS/electron-builder 不会恢复旧安装树。因此不能用一个合成 failpoint 冒充 rollback 证明。后续必须先设计事务式备份/恢复，再加入确定性的安装中途失败，并验证旧目录逐文件哈希一致且旧版仍能完整启动。

Roadmap checklist sync (2026-08-21):

Recorded fix(desktop): drain untracked Runtime Host before update #3382 merged / windows: auto-update silently fails when a Runtime Host process survives the app quit (installer cannot clear it) #3340 closed and the successful Runtime Host update-handoff evidence.
Recorded feat(win): Abort-path installer rollback with backup retention #3265 exact head 68520adc as CI/audit/Windows L3 green but still pending independent human review; kept it unchecked.
Split the installer boundary honestly: Abort-path rollback/backup retention is the current PR, while hookless Quit/hard-kill/power-loss automatic recovery remains an explicit formal-support decision rather than being called transactional.
Checked the Phase 4 RFC/shipped-slice alignment item as completed by feat(windows-sandbox): place sandboxed children on a private desktop #3174 (including production-identity readiness and private-desktop placement).
Reworded the remaining Phase 4 lifecycle task as promotion to a required packaged/per-release gate plus Runtime-Host-mid-launch, explicit cancel, soak, and unsettled-state recovery evidence.
Kept Authenticode signing, the windows_recovery ruleset requirement, the adversarial matrix, independent human security review, Windows baseline cleanup, and Windows computer-use open.

Related tracker updates:

ci(windows): track remaining Release Windows check product failures #3377 received a current-status correction because this account cannot edit its body.
runtime-host: intermittent 'stopped responding during startup' after a Windows upgrade over an existing profile #3279 received the latest clean-run non-occurrence plus a concrete stress/capture plan; it remains open.

Windows remains preview-only.

中文：已同步 #2142 正文，勾选 #3174 完成的 Phase 4 对齐，记录 #3382/#3340 与 #3265 当前状态，并把 Abort/Quit/硬杀/断电边界拆开表述；签名、required ruleset、安全证据/人审、baseline 与 computer-use 仍保持开放。

Roadmap sync (2026-08-23):

feat(win): Abort-path installer rollback with backup retention #3265 merged as 9de05e266; Phase 3 Abort-path rollback/backup-retention item is now checked. The formal-support decision for hookless Quit, hard kill, and power loss remains open.
ci(windows): gate packaged sandbox lifecycle evidence #3558 exact head 229d09c72 is mergeable and Core/Release Windows green. It promotes the existing cancellation/parent-death/concurrency/Job-drain/ACL-recovery smokes into the shared packaged and formal-release verifier. It still requires independent human review.
test(windows): verify packaged sandbox client cancellation #3586 exact head bbbb6b4f1 is mergeable and Core/Release Windows green. It adds explicit post-dispatch client cancellation evidence (aborted, launch, dispatched:true), broker/AppContainer process-tree exit, a successful recovery launch, and no matching recovery ledger. The packaged stage passed three times in one run: initial package, pinned upgrade, and automatic update. It still requires independent human review.
The Phase 4 lifecycle checkbox remains open. Remaining technical slices are Runtime Host death mid-launch, sustained concurrency soak, and documented unsettled-state recovery/quarantine; the adversarial matrix and independent human security review remain separate gates.

Windows remains preview-only.

Related context: sandbox approval pre-dispatch

Discussion #3629 is the design context for the Phase 4 permission-escalation flow tracked here.

The proposal is to let Runtime preflight the original tool invocation before dispatch:

allowed: dispatch immediately;
approval_required: keep the original invocation pending, ask the user, revalidate the current boundary, then dispatch it for the first time;
denied: return a typed denial;
unsupported: return a typed capability error.

For Windows/AppContainer, user approval must not silently turn an unenforceable capability into unsandboxed execution. Unsupported capabilities should remain explicit and fail closed. A bypass boundary should dispatch directly without creating an approval request. Bash may retain required_boundary because Runtime cannot safely infer the resources used by an arbitrary shell command; Runtime should own the approval state machine around that declaration.

This is design context only; it does not claim that the Phase 4 sandbox-security gates are complete. The preview-only support boundary and the remaining lifecycle, adversarial, and independent-review gates remain unchanged.

Phase 3 boundary decision and Phase 4 continuation

The Phase 3 formal-support boundary is now recorded for the Windows 11 x64 preview:

verified Abort-path failures recover automatically;
hookless Quit uses retained backup evidence and exact-identity rerun recovery;
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.

This closes the boundary-decision item only. It does not declare Windows fully supported.

Phase 4 remains the active track. #3558 is at exact head f65dc9d15 with Core, dependency-audit, and Release Windows checks green; it remains open pending maintainer review and one review-thread resolution. #3586 has merged the explicit packaged client-cancellation evidence.

The remaining Phase 4 gates are Runtime Host death during launch, sustained concurrency soak, unsettled-state recovery/quarantine, the adversarial escape matrix, and independent human security review.

Phase 4 automated evidence update

#3722 now has exact-head packaged Windows L3 green at 6970405e99a7e0aaba28c1f5eb30227aeb57b320:

Runtime Host parent-death cleanup;
64-launch packaged concurrency soak;
quarantined ACL-ledger non-reuse;
packaged filesystem/network/IPC/environment/registry/parent-token/descendant matrix;
pinned upgrade/uninstall;
automatic update;
deterministic rollback.

The W0 native broker protocol lane is also green. The ordinary test lane is independently red in the pre-existing packages/eval/harbor/test_relay_lifecycle.py test (late_write remained present); #3722 does not modify packages/eval. The Phase 4 lifecycle checkbox remains open until #3722 is merged and the required independent human security review is complete. UDP/DNS/SMB, inbound listener enforcement, Authenticode, no-Win32k/window-station isolation, power-loss automatic recovery, and direct Credential Manager/DPAPI probes remain explicitly deferred.

The Computer Use portion of this roadmap now has a dedicated implementation issue: #3785.

#3785 reviews the current maka-agent/maka-cu Windows prototype and proposes the concrete Phase 5 work: reuse the platform-neutral maka.cu/2 host contract, bind actions to process/window generations and opaque snapshot tokens, use a target-window capture API, make UIA/Win32 fallbacks capability-driven and verifiable, define DPI/session/UIPI/security behavior, and add fixture plus Windows E2E evidence.

It is intentionally scoped as a child of this umbrella issue rather than a second Windows-support roadmap. The acceptance criteria in #3785 are meant to be the Computer Use-specific gates for Phase 5 here.

Roadmap sync (2026-08-25)

The issue body is now synchronized after #3558, #3586, and #3722 merged.

The shipped Windows 11 x64 W1 filesystem-worker AppContainer surface has completed its Phase 4 automated lifecycle/adversarial evidence and independent maintainer/security review gates.
ci(windows): gate packaged sandbox lifecycle evidence #3558 owns the shared packaged/formal-release lifecycle verifier and its trigger/source-closure authority; test(windows): verify packaged sandbox client cancellation #3586 owns explicit client cancellation; test(windows): close packaged sandbox lifecycle evidence #3722 owns Runtime Host parent death, validated owner binding, Job drain, the 64-launch soak, quarantined-state non-reuse, and the scoped adversarial matrix.
Windows remains preview-only. Phase 3 now has one implementation blocker: Authenticode identity/signature verification in infra: obtain ASF code signing identities for Desktop artifacts #3414.
The next execution order is: signing (infra: obtain ASF code signing identities for Desktop artifacts #3414) -> authoritative Windows baseline and required windows_recovery gate (ci(windows): eliminate hidden failures in the non-blocking baseline #2624 plus repository administration) -> one support-declaration cutover PR.
Direct Credential Manager/DPAPI probes, broader network channels, no-Win32k, dedicated window-station/clipboard isolation, power-loss automatic recovery, W2 general-command sandboxing, and Windows computer-use remain explicit separate work. They are not claimed by the completed W1 preview surface.
The eval descendant-cleanup timing issue test(eval): harden relay descendant cleanup against process-group timing #3770 remains separate and is not a Windows support blocker.

Support should not be declared until the remaining clean-run, fail-closed, signing, and required-gate criteria in the body are satisfied.

Windows plan item 2 progress: #3796 merged the current-main bootstrap repairs; #3789 is now rebased and exact-head green for both required \ est\ and automatic \windows_recovery. The recovery run executed every native crash/owner-death group, not just workflow setup. #3789 also declares \windows_recovery\ in the ASF-managed required contexts; the roadmap administration checkbox remains open until #3789 merges and ASF infrastructure applies the updated protection. #2624 still tracks PTY/Git cleanup, symlink-capability classification, and the required three clean scheduled baseline runs.

Windows baseline progress update (2026-08-26)

The post-#3789 full baseline was started on byte-identical apache/main@32a1db0eb in the maintainer fork because this account cannot dispatch the Apache workflow (GitHub HTTP 403, Actions-admin permission required).

The first run exposed one deterministic root-authority fixture failure in both focused and full Storage. That was fixed separately in #3872, which adds the exact root race to windows_recovery with strict 1 test / 1 pass / 0 skip evidence. #3872's hosted test and windows_recovery are green.

Three subsequent full-baseline runs on the fixed exact head are clean:

Each run reports focused Storage 88 pass / 0 fail / 12 skip, full Storage 940 pass / 0 fail / 38 skip, successful Runtime PTY and PowerShell UTF-8 gates, clean CLI/Electron smoke, and an empty residual-process audit. These are fork diagnostics on the Apache main tree; they are not a replacement for Apache-owned scheduled/admin-triggered evidence.

Remaining Phase 1 administration work:

trigger or authorize three equivalent full-storage runs on apache/main;
apply and verify windows_recovery as an effective required check in the GitHub ruleset.

After those organization-owned checks are clean, the Windows baseline item in #2624 can be closed. Authenticode #3414 remains the separate Phase 3 blocker before the roadmap can change Windows from Preview to Supported.

#3872 has merged as 235a12d. On byte-identical �pache/main@235a12d, three full fork baseline runs are clean: 950/0/38 full Storage, 88/0/12 focused Storage, and empty residual-process evidence in each. The technical baseline work is complete; remaining Phase 1 actions are ASF-owned three-run confirmation and effective windows_recovery ruleset enforcement. Phase 3's remaining product blocker is Authenticode #3414.

docs(architecture): audit CLI and distribution group against implemen…

Status refresh, 2026-10-09. This roadmap is still current; Windows stays a preview target.

Phase 3 signing: infra: obtain ASF code signing identities for Desktop artifacts #3414 closed as not planned for 0.2.0 when the Apple and Windows signing requests were withdrawn to focus on the source release. The Authenticode item, and the "signed install and update artifacts are published" exit criterion, are deferred, not done. The support-declaration cutover (step 3 in the plan) stays blocked until signed convenience artifacts return to a release plan.
Baseline: ci(windows): eliminate hidden failures in the non-blocking baseline #2624, eliminating hidden failures in the non-blocking baseline, is still open, and so is making windows_recovery a required check in the effective ruleset.
Phase 5, computer use: feat(windows): harden and productionize the maka-cu Computer Use executor #3785 and its implementation PR feat(computer-use): add guarded Windows maka.cu/2 integration #4668 are in progress.
Since the last update: the Windows pre-commit hook is fixed (bug(ci): pre-commit hook cannot spawn biome.cmd on Windows (EINVAL) #5668 via fix(ci): run Biome native binary on Windows #5677). It had blocked every commit on Windows with Node's .cmd spawn EINVAL.

No phase checkboxes change.

Navigation Menu

Repository navigation

roadmap(windows): make Windows a supported platform #2142

Problem

Desired outcome

Current support status (2026-08-25)

Phase 0: establish the baseline

Phase 1: continuous Windows correctness

Phase 2: crash and recovery guarantees

Phase 3: distribution

Phase 4: sandbox security (shipped W1 preview surface)

Next execution plan

Phase 5: computer-use

Support criteria

Alternatives or workarounds

Windows CI efficiency update (2026-08-09)

10 remaining items

Related context: sandbox approval pre-dispatch

Phase 3 boundary decision and Phase 4 continuation

Phase 4 automated evidence update

Roadmap sync (2026-08-25)

Windows baseline progress update (2026-08-26)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

roadmap(windows): make Windows a supported platform #2142

Description

Problem

Desired outcome

Current support status (2026-08-25)

Phase 0: establish the baseline

Phase 1: continuous Windows correctness

Phase 2: crash and recovery guarantees

Phase 3: distribution

Phase 4: sandbox security (shipped W1 preview surface)

Next execution plan

Phase 5: computer-use

Support criteria

Alternatives or workarounds

Activity

liugddx commented on Aug 7, 2026

TomXPRIME commented on Aug 7, 2026

liugddx commented on Aug 7, 2026

TomXPRIME commented on Aug 7, 2026

liugddx commented on Aug 7, 2026

liugddx commented on Aug 7, 2026

liugddx commented on Aug 7, 2026

liugddx commented on Aug 7, 2026

liugddx commented on Aug 9, 2026

liugddx commented on Aug 9, 2026

Windows CI efficiency update (2026-08-09)

liugddx commented on Aug 10, 2026

liugddx commented on Aug 10, 2026

liugddx commented on Aug 11, 2026

liugddx commented on Aug 12, 2026

liugddx commented on Aug 12, 2026

10 remaining items

liugddx commented on Aug 21, 2026

liugddx commented on Aug 23, 2026

liugddx commented on Aug 24, 2026

Related context: sandbox approval pre-dispatch

liugddx commented on Aug 24, 2026

Phase 3 boundary decision and Phase 4 continuation

liugddx commented on Aug 24, 2026

Phase 4 automated evidence update

liugddx commented on Aug 25, 2026

liugddx commented on Aug 25, 2026

Roadmap sync (2026-08-25)

liugddx commented on Aug 25, 2026

liugddx commented on Aug 26, 2026

Windows baseline progress update (2026-08-26)

liugddx commented on Aug 26, 2026

liugddx commented on Oct 8, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions