Skip to content

feat(runtime-host): support native Windows managed deployments - #4658

Open
M4n5ter wants to merge 5 commits into
refactor/runtime-host-operator-commandfrom
feat/runtime-host-windows-task
Open

feat(runtime-host): support native Windows managed deployments#4658
M4n5ter wants to merge 5 commits into
refactor/runtime-host-operator-commandfrom
feat/runtime-host-windows-task

Conversation

@M4n5ter

@M4n5ter M4n5ter commented Sep 3, 2026

Copy link
Copy Markdown
Member
English

Summary

Add a canonical per-user Windows managed Runtime Host lifecycle with supervised / session availability. The persisted provider projects two owned Task Scheduler tasks: one for Host activation at user logon/on demand, and one for scheduled one-shot reconciliation through the stable operator.

Task Scheduler's COM API is handled by typed functions in the existing Runtime Host native addon, with exact semantic verification, ownership markers, locale-independent status, and no private protocol, shell, password, elevation, pidfile, or second lifecycle state machine. Because ExecAction expands %NAME%, a single exact-package task runner carries desired argv as Base64URL tokens and decodes it before spawn(..., shell: false); executable or runner paths containing % fail closed.

Persisted provider resolution now takes only the canonical deployment config and derives Root ID, provider identity, task runner, and native addon from it. This removes contradictory inputs and selects executable artifacts from the managed exact package rather than the ambient controller, keeping update verification and later package pruning inside the same authority boundary. Pre-install capability discovery remains separate because no deployment exists yet.

Windows Task Scheduler does not reliably classify a normal ExecAction's nonzero process exit as a restartable task failure. An internal exact-package Node supervisor therefore restarts only unexpected Host exits. An outer kill-on-close Job fences the entire scheduled-task tree on retirement, while each managed Host owns a nested generation Job so its detached descendants are reclaimed before a replacement starts. The native status projection maps Task Scheduler's wrapper PID to the unique Node Host child, preserving the existing supervisor PID == State Root owner PID transaction fence.

Closes #4646

Verification

  • CLI build, Rust format/check, and Biome
  • actionlint and workflow-policy checks; runtime-host-windows-* changes always select installed-package validation
  • native Windows seam on a standard user account: literal %PATH%, hostile Unicode/shell-metacharacter argv, double activation to one Host, exact Host PID status, forced crash with detached-descendant cleanup before a fresh PID, running definition replacement with old-tree fencing, retirement cleanup, and owned-task uninstall
  • immutable Windows development tarball installed from an empty offline npm cache; the full installed-product smoke passed after disabling the ambient controller runner and using a distinct managed exact package
  • loaded-addon probe: an old package locked by the active operator is retired atomically and physically reclaimed after that operator exits

Availability and migration

This provider promises availability only while the Windows user is signed in. It does not use SCM, S4U, stored credentials, or claim machine availability. PR 1 automatically upgrades shipped managed Host and WSL state; no Windows provider state has shipped, so unreleased Windows development artifacts do not add another migration format.

AI use

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool(s) and scope: OpenAI Codex implemented and verified the Windows provider under maintainer direction.

Checklist

  • Tests cover the change and fail without it
  • Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

  • Yes — described under Summary above
  • No
中文

摘要

增加 canonical 的 per-user Windows managed Runtime Host lifecycle,availability 为 supervised / session。持久化 provider 投影两个自有 Task Scheduler task:一个负责用户登录/按需 Host activation,另一个通过稳定 operator 触发定时 one-shot reconciliation。

现有 Runtime Host native addon 通过 typed function 直接调用 Task Scheduler COM API,使用精确语义验证、ownership marker 和与 locale 无关的状态读取;不增加私有协议,也不使用 shell、密码、提权、pidfile 或第二套 lifecycle 状态机。由于 ExecAction 会展开 %NAME%,统一的 exact-package task runner 将 desired argv 作为 Base64URL token 传输,解码后通过 spawn(..., shell: false) 执行;executable 或 runner 路径含 % 时 fail closed。

持久化 provider 现在只从 canonical deployment config 解析,并从中派生 Root ID、provider identity、task runner 与 native addon。这样消除了可矛盾输入,且可执行 artifact 来自 managed exact package,而不是当前 ambient controller,使 update 验证与后续 package pruning 始终处于同一 authority 边界。安装前尚无 deployment,因此 capability discovery 保持独立。

Windows Task Scheduler 不会可靠地把普通 ExecAction 的非零进程退出认定为可重启 task failure。因此,一个 exact-package 内部 Node supervisor 只负责重启异常退出。外层 kill-on-close Job 在 retirement 时 fence 整个 scheduled-task process tree;每个 managed Host 再拥有一个嵌套的 generation Job,使其 detached descendants 在 replacement 启动前被完整回收。native status 将 Task Scheduler 的 wrapper PID 投影到唯一 Node Host 子进程,继续满足既有的 supervisor PID == State Root owner PID 事务 fence。

关闭 #4646

验证

  • CLI build、Rust format/check 与 Biome
  • actionlint 与 workflow-policy 检查;runtime-host-windows-* 变更始终触发 installed-package validation
  • 普通用户 Windows 原生 seam:字面量 %PATH%、恶意 Unicode/shell 元字符 argv、双 activation 单 Host、强制崩溃后先清理 detached descendant 再产生新 PID、运行中替换 definition 并 fence 旧进程树、retirement 清理与 owned-task uninstall
  • immutable Windows development tarball 从空离线 npm cache 安装;禁用 ambient controller runner 并使用独立 managed exact package 后,完整 installed-product smoke 通过
  • loaded-addon 探针:active operator 锁定旧 package 时先原子 retire,operator 退出后完成物理回收

可用性与迁移

该 provider 只承诺 Windows 用户登录期间可用,不使用 SCM、S4U 或保存的凭据,也不宣称 machine availability。PR 1 会自动升级已发布的 managed Host 与 WSL 状态;Windows provider 状态从未发布,因此不为开发期 Windows artifact 增加另一套迁移格式。

AI 使用

  • 没有生成式工具作出实质贡献
  • 生成式工具作出实质贡献

工具与范围:OpenAI Codex 在维护者指导下实现并验证 Windows provider。

检查清单

  • 测试覆盖该变更,且没有变更时会失败
  • lint、format、typecheck 与受影响测试已在本地通过

该 PR 是否改变行为?

  • 是——已在摘要中说明

@github-actions github-actions Bot added the effort/XL Under 2500 readable lines label Sep 3, 2026
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch from 518e566 to fd3ebfc Compare September 3, 2026 12:40
@M4n5ter M4n5ter self-assigned this Sep 3, 2026
@M4n5ter M4n5ter changed the title feat(runtime-host): add Windows Task Scheduler lifecycle feat(runtime-host): support native Windows managed deployments Sep 3, 2026
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch from fd3ebfc to 03d14c3 Compare September 3, 2026 12:44
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch 5 times, most recently from 0c6b211 to 8eb7a30 Compare September 3, 2026 13:52
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch from 8eb7a30 to 9ce29a9 Compare September 3, 2026 14:27
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch from 9ce29a9 to cd1cfb2 Compare September 3, 2026 14:41
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch from cd1cfb2 to c600e60 Compare September 3, 2026 15:37
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch from c600e60 to b22360a Compare September 3, 2026 15:59
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch from b22360a to 60f4343 Compare September 3, 2026 16:12
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch 3 times, most recently from ad3d2fe to fd2653f Compare September 3, 2026 16:59
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch from fd2653f to df39617 Compare September 3, 2026 17:16
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch 2 times, most recently from 9def741 to b649461 Compare September 3, 2026 17:40
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch from b649461 to 34318c6 Compare September 3, 2026 17:55
@M4n5ter
M4n5ter force-pushed the feat/runtime-host-windows-task branch from 1fbc284 to 5f07e96 Compare September 3, 2026 18:54
@M4n5ter
M4n5ter marked this pull request as ready for review September 3, 2026 19:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/XL Under 2500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(runtime-host): support native Windows managed deployments

1 participant