refactor(runtime-host): make operator control platform-neutral

[M4n5ter]

English

Summary

Make managed Runtime Host control describe a target-platform invocation instead of assuming every operator is a POSIX-executable path. New deployments use one exact { nodePath, modulePath, platform } command across Desktop, CLI, SSH, and WSL; Windows SSH uses an encoded PowerShell invocation independent of the account's default shell.

SSH preflight now reports the remote Node identity as a fact. Published npm onboarding derives only the operator platform from it, while development archive selection alone applies the finite Direct-peer prebuild policy; supported published targets such as macOS x64 are no longer rejected by an unrelated native-artifact whitelist.

Shipped path-based SSH/WSL profiles, interrupted SSH pairing journals, and Desktop managed bindings are upgraded automatically without changing their target identity or credential binding. Existing POSIX deployment operators become stable forwarders to the persisted exact package, so migrated WSL and SSH installations survive later updates and package pruning. The shipped WSL profile set --operator-path CLI remains a legacy POSIX alias for existing automation, while new callers use --operator-command. Native Windows also receives its correct application-data root. This slice deliberately adds no lifecycle provider; that is the stacked follow-up.

Re-adding an existing WSL Host now recognizes deployment identity independently from its control route. It upgrades the existing profile and binding atomically instead of creating a duplicate profile; a failed binding write restores the previous profile.

The stable operator also preserves child signal exits: it removes only its own forwarding handlers before reproducing the child's signal, so lifecycle callers cannot mistake a terminated exact package for a successful operation.

Refs #4646

Verification

• CLI, Runtime Host, and Desktop builds/typechecks
• affected operator, SSH, WSL, setup, profile, and Desktop management tests
• generated-operator integration coverage for real SIGTERM propagation
• Windows-native build and installed development-tarball validation on the stacked product

Review focus

The operator command is the only cross-platform invocation authority. Callers must not reconstruct shell commands or infer the target platform. Compatibility is limited to persisted shapes that shipped: reads work immediately, owning mutations rewrite current schemas, and unreleased intermediate representations remain unsupported.

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

中文

摘要

managed Runtime Host 控制面不再假设所有 operator 都是 POSIX 可执行路径，而是描述目标平台调用。新部署在 Desktop、CLI、SSH 与 WSL 中统一使用精确的 { nodePath, modulePath, platform } 命令；Windows SSH 使用编码后的 PowerShell 调用，不依赖账号默认 shell。

SSH preflight 现在只报告远端 Node identity 这一事实。发布版 npm onboarding 仅据此确定 operator platform，只有开发 archive 选择才应用有限的 Direct-peer prebuild 策略；macOS x64 等发布版可支持目标不再被无关的原生产物白名单拒绝。

已发布版本留下的 path-based SSH/WSL profile、未完成的 SSH pairing journal 与 Desktop managed binding 会自动升级，并保持原 target identity 与 credential binding。既有 POSIX deployment operator 会变为指向持久化 exact package 的稳定 forwarder，使迁移后的 WSL/SSH 安装在后续更新和 package pruning 后仍可工作。已发布的 WSL profile set --operator-path CLI 会保留为既有自动化使用的 legacy POSIX alias，新调用方使用 --operator-command。该切片同时使用 Windows 原生 application-data 目录；lifecycle provider 位于 stack 的后续 PR。

重新添加既有 WSL Host 时，会独立于 control route 识别 deployment identity，原子升级已有 profile 与 binding，而不是创建重复 profile；binding 写入失败则恢复原 profile。

稳定 operator 还会保留子进程的 signal exit：在复现子进程信号前只移除自身安装的 forwarding handler，避免 lifecycle 调用方把被终止的 exact package 误判为成功。

关联 #4646

验证

• CLI、Runtime Host 与 Desktop build/typecheck
• operator、SSH、WSL、setup、profile 与 Desktop management 相关测试
• generated operator 真实 SIGTERM 传播集成覆盖
• 在 stack 完整产品上完成 Windows 原生 build 与 development tarball 安装验证

审查重点

operator command 是唯一跨平台调用 authority。调用方不得重新拼 shell command，也不得重新猜测目标平台。兼容范围只覆盖真正发布过的持久化形态：读取立即可用，下一次 owning mutation 写回当前 schema；未发布的中间表示不兼容。

AI 使用

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

工具与范围：OpenAI Codex 在维护者指导下实现并验证本次重构。

检查清单

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

该 PR 是否改变行为？

• 是——已在摘要中说明
• 否

[Astro-Han]

Reviewed current head 2d33ec8f3830ac513a2c542685d3bfcbce45bbbf (OPEN, MERGEABLE, hosted checks green). One P2 below; no P0/P1/P3. As a refactor, merging is a human decision regardless.

P2 — adopting a schema-1 handoff can write a receipt the recovery path cannot honor

Under narrow conditions — a published schema-1 handoff whose managed authority is already active, with an old POSIX deployment that still only has <deploymentRoot>/operator — apps/desktop/src/main/runtime-host-local-remote-access.ts:199-236,467-482,854-888 directly adopts it and writes a schema-2 receipt pointing at <deploymentRoot>/operator.mjs, without triggering the CLI convergence in packages/cli/src/runtime-host-managed-deployment.ts:742-795. Peers and access layers then start that module straight from the receipt (apps/desktop/src/main/runtime-host-local-operator.ts:273-290,332-353), so the restored local runtime-host control can fail for lack of operator.mjs. Ordinary schema-1 managed receipts already migrate to the legacy POSIX operator (runtime-host-local-remote-access.ts:1163-1175); this finding does not cover those.

Suggested fix: perform a verifiable convergence before issuing the schema-2 receipt, or keep the legacy operator; plus a recovery regression test for schema-1 handoff plus active authority plus old operator.

What was checked on this head

Platform-diff convergence, cross-platform behavior preservation, permission/lifecycle/failure paths, and test coverage. All applicable hosted checks pass; git diff --check clean. What I could not judge: full local typecheck/build could not complete (missing tsc and shared dist artifacts in the checkout), and no real Windows/SSH/WSL/Electron end-to-end runs were done.

---

Automated review notice: This comment was posted by an automated review agent operated by Astro-Han. It is not an independent human review and does not replace one.

简体中文

本条结论全部来自 @Luna-Deep-Qronos 的审查。我自己没有读这份 diff；我核的是当前 head 有没有漂移、以及 exact-head 的 CI 状态。当前 head 是 2d33ec8，可合并，检查通过。P2 是特定条件下恢复后本地控制可能因缺文件失败，重构类合并由人类拍板。