[Tracking] Runtime Host remote access and production hardening

[M4n5ter]

English

Goal

Complete the product integration and production hardening of Runtime Host as the single long-lived authority for one State Root and its Runtime work.

Local IPC and authenticated WebSocket Clients use the same Host state, operation routing, execution authority, recovery, and shutdown lifecycle. Desktop may connect to multiple independent Hosts as a Client-side composition; CLI and TUI continue to use one selected Host per process.

Stable architecture belongs in the Runtime Host architecture guide. This issue tracks remaining product and operational work rather than duplicating protocol or TypeScript designs.

Stable constraints

• One State Root has at most one writer Host.
• Local IPC and WebSocket are transport adapters for the same Kernel, Composition, Domain Modules, and canonical Stores.
• Root ID identifies the durable Host State Root. A profile identifies one immutable way to connect to it.
• Host-owned identifiers are scoped to one State Root. A Client that aggregates Hosts must retain Host identity on every resource reference.
• A remote target connects only; it never joins local discovery, election, candidate spawning, or fallback.
• Runtime Host is the only authority that resolves a workspace target to a Host path. Remote Clients select Host Projects and never reinterpret Client-local paths as Host paths.
• Reconnect restores canonical observation. It never blindly replays commands whose outcome may be unknown.
• TLS, SSH, and explicitly acknowledged plaintext are distinct connection methods. No method silently downgrades to another.
• Multi-Host Desktop remains a Client-side composition. It does not create a federated Host, cross-Host durable database, or second execution authority.

Delivered foundation

• Local standalone service, common transport/listener boundaries, and explicit ephemeral/service lifecycle (#2583)
• Authenticated WebSocket/WSS access, exact grants, root pinning, Origin policy, and native remote connector (#2591)
• Host-owned Project Catalog and canonical workspace authority through the closed project/host-path target model (#2603, #2642)
• Stable Client identity, capability registration/rebind, reconnect, catch-up, and no generic command replay (#2608, #2618)
• Trusted unattended capability-provider service with path-free offers by default and explicit Host-cwd access (#2625)
• Durable Host ownership boundaries and current architecture documentation (#2613, #2683)
• Desktop stream recovery and safe local Host upgrade handoff (#2630, #2633, #2654)
• Shared, Client-owned Host profiles for Desktop, CLI, and TUI, with exact-target credential binding, pinned root identity, zero-configuration Local startup, and no automatic transport fallback (#2834)
• In-process Desktop target switching and Host-owned remote Project selection, without treating remote paths as Client-local paths (#2834)
• Same-target reconnect preserves Client-owned drafts, attachments, quotes, and selection while stale candidate results are fenced and Host projections are refreshed (#2901)
• Desktop Host identity and target-generation fencing across IPC, events, observations, diagnostics, and Client-local resources (#2935)
• Guided Direct TLS onboarding, machine-readable service readiness, Host-local Project management, least-privilege Client access presets, and shared Desktop/CLI/TUI remote Profiles (#2911)
• System SSH tunneling and explicitly acknowledged plaintext transport for Desktop, TUI, and CLI (#2925)

The current Desktop can onboard remote Hosts over Direct TLS, system SSH, or explicitly acknowledged plaintext without restarting, and can keep Local and enabled remote Hosts connected concurrently. Existing Sessions remain bound to their owning Host, new-task composition can select or register a Project on any ready Host, and Host-owned Settings can target an explicit Host without changing the default Host. Remote registration uses constrained Host-published directory roots and does not expose file contents or a general remote filesystem browser. Windows Local IPC now establishes and verifies a current-user/SYSTEM trust boundary before granting Local Owner authority. The production-hardening closure is complete.

Remaining work

1. Remote onboarding and connection methods

• Add guided direct-TLS onboarding with endpoint validation, root verification, credential replacement, and actionable unavailable/incompatible states (#2911).
• Add a system-SSH tunnel connection method. Desktop provides a bounded interactive terminal for host-key, password, passphrase, or MFA prompts; TUI may interact before taking over the terminal; non-interactive CLI fails promptly with actionable guidance (#2925).
• Add explicit plaintext support only when both Host and Client opt in and the Client stores a durable insecure-transport acknowledgement. Never add automatic downgrade or certificate-verification bypass (#2925).
• Add machine-readable service readiness output and versioned least-privilege Client access presets so an operator can prepare a Host without reading internal protocol details (#2911).
• Keep credentials in the platform credential store or environment input; never place them in profile documents, command-line arguments, logs, or onboarding output (#2911).

2. Multi-Host Desktop

• Replace the single active-target owner with independent per-Host connection entries. Changing the default Host for new work does not disconnect another Host or move an existing Session (#3097).
• Carry verified Host identity through Session, Project, event, observation, diagnostics, notification, and Client-local resource references so equal raw IDs from different Hosts cannot collide (#2935).
• Aggregate Session summaries from enabled Hosts, show Host identity and per-Host readiness, retain bounded in-memory presentation during reconnect, and route every existing Session action back to its owning Host (#3097).
• Let new-task composition select a Project from any enabled Host without changing the default Host (#3122).
• Keep Host-scoped settings under an explicit Host selector instead of merging unrelated Host domains (#3131).
• Let Desktop register a Project on a remote Host through a constrained Host-side directory picker without exposing a general remote filesystem browser (#3145).
• Preserve one selected profile per CLI/TUI process; Desktop multi-Host presentation remains Desktop-only (#3097).

3. Windows Local IPC trust boundary

• Verify the effective Windows named-pipe access boundary and enforce a current-user-equivalent ACL where platform defaults are insufficient (#3179, #3182).
• Grant unrestricted local-owner authority only after that boundary is established (#3179, #3182).
• Add one focused Windows integration test for unauthorized admission, including replacement pipe instances and foreign-user read, write, and duplex access (#3182).

4. Production hardening

• Cover representative cross-listener journeys: two Clients observing and controlling one Session, reconnect/catch-up, root mismatch, and indeterminate command outcomes (closure audit: #3186).
• Verify bounded behavior for slow consumers, queue exhaustion, malformed or oversized frames, and large streamed payloads (closure audit: #3186).
• Verify credential revocation fences existing and future operations without leaking credential material (closure audit: #3186).
• Verify graceful drain, forced shutdown, service restart, and capability-provider loss/rebind, including Automation waiting and recovery (closure audit: #3186).
• Keep Domain behavior tests shared. Run transport conformance once per adapter and add end-to-end cases only for transport- or lifecycle-specific risk (closure audit: #3186).

Definition of done

• Desktop can keep Local and remote Hosts connected concurrently, show their Sessions with explicit Host identity, and route every action to the owning Host.
• CLI and TUI can select one of the same saved profiles and observe or control the same canonical Host state.
• Direct TLS, system-SSH tunneling, and explicitly acknowledged plaintext have clear, non-downgrading onboarding and failure behavior.
• Remote Client configuration safely preserves Host identity and credentials without exposing secrets or silently changing roots.
• Remote workspace selection is Host-scoped and cannot confuse a Client path with a Host path.
• Windows Local IPC has an explicit same-user trust boundary before receiving local-owner authority.
• Restart, disconnect, revocation, backpressure, and shutdown converge without duplicate commands, orphaned writers, or unbounded queues.
• All listeners share one protocol, one dispatcher, one execution authority, and one canonical state model.

Non-goals

• Replacing Local IPC with WebSocket
• Automatic Local IPC-to-WebSocket fallback or transport downgrade
• A federated Host, cross-Host durable database, or cross-Host Session migration
• Browser authentication in the native-Client milestone
• Multi-tenant Session or Project isolation
• Shared-filesystem path mapping without a concrete deployment requirement
• A second bulk data plane without measured need
• A second Runtime, dispatcher, writer, or recovery model

简体中文

目标

完成 Runtime Host 的产品接入与生产强化，使其成为一个 State Root 及其 Runtime 工作的唯一长生命周期 authority。

Local IPC 与经过认证的 WebSocket Client 使用同一套 Host 状态、operation routing、execution authority、恢复和关闭生命周期。Desktop 可以通过 Client 侧组合同时连接多个独立 Host；CLI 与 TUI 仍然在每个进程中使用一个选定 Host。

稳定架构由 Runtime Host 中文架构文档 维护。本 issue 跟踪剩余产品与运维工作，不重复容易漂移的 protocol 或 TypeScript 设计。

稳定约束

• 一个 State Root 最多只能有一个写入 Host。
• Local IPC 与 WebSocket 只是同一 Kernel、Composition、Domain Module 和 canonical Store 的 transport adapter。
• Root ID 标识持久的 Host State Root；profile 标识连接该 Host 的一种不可变方式。
• Host-owned identifier 只在一个 State Root 内唯一。聚合多个 Host 的 Client 必须在每个资源引用中保留 Host identity。
• 远程 target 只负责连接，不能参与本地 discovery、election、candidate spawn 或 fallback。
• Runtime Host 是唯一把 workspace target 解析为 Host path 的 authority。远程 Client 选择 Host Project，不能把 Client 本地路径解释为 Host 路径。
• 重连恢复 canonical observation，不能盲目重放结果可能未知的 command。
• TLS、SSH 与显式确认风险的 plaintext 是不同连接方式，任何方式都不能静默降级为另一种。
• Multi-Host Desktop 只是 Client 侧组合，不会引入 federated Host、跨 Host durable database 或第二套 execution authority。

已完成基础

• 本地独立服务、统一 transport/listener 边界和显式 ephemeral/service lifecycle（#2583）
• 经过认证的 WebSocket/WSS、精确 grant、root pinning、Origin policy 与原生远程 connector（#2591）
• Host-owned Project Catalog，以及通过封闭 project/host-path target 模型建立的 canonical workspace authority（#2603、#2642）
• 稳定 Client identity、capability registration/rebind、重连、catch-up，以及禁止通用 command replay（#2608、#2618）
• 可信 unattended capability-provider service，默认使用 path-free offer，并显式声明 Host cwd access（#2625）
• Durable Host ownership boundary 与当前架构文档（#2613、#2683）
• Desktop stream recovery与安全的本地 Host 升级接管（#2630、#2633、#2654）
• Desktop、CLI 与 TUI 共享的 Client-owned Host profile，包含精确 target credential binding、固定 root identity、零配置 Local 启动，且没有自动 transport fallback（#2834）
• Desktop 进程内 target 切换和 Host-owned 远程 Project 选择，且不会把远程路径当作 Client 本地路径（#2834）
• 同 target 重连时保留 Client-owned draft、attachment、quote 与 selection，同时隔离旧 candidate 结果并刷新 Host projection（#2901）
• Desktop IPC、event、observation、diagnostics 与 Client-local resource 的 Host identity 和 target-generation 隔离（#2935）
• 引导式 Direct TLS onboarding、机器可读的 service readiness、Host-local Project 管理、最小权限 Client access preset，以及 Desktop/CLI/TUI 共享的远程 Profile（#2911）
• Desktop、TUI 与 CLI 的 system SSH tunnel 和显式确认风险的 plaintext transport（#2925）

当前 Desktop 可以在无需重启的情况下，通过 Direct TLS、system SSH 或显式确认风险的 plaintext 完成远程 Host onboarding，并同时保持 Local 与已启用 remote Host 的连接。已有 Session 始终绑定所属 Host；新任务组合可以在任意 ready Host 选择或注册 Project；Host-owned Settings 也可以显式选择目标 Host，且不改变默认 Host。远程注册只使用 Host 发布的受限目录 root，不会暴露文件内容或通用 remote filesystem browser。Windows Local IPC 现在会在授予 Local Owner authority 前建立并验证 current-user/SYSTEM 信任边界。基于实际证据的生产强化收口现已完成。

剩余工作

1. 远程 onboarding 与连接方式

• 增加引导式 Direct TLS onboarding，包括 endpoint 校验、root 验证、credential replacement，以及可操作的 unavailable/incompatible 状态（#2911）。
• 增加 system SSH tunnel 连接方式。Desktop 提供有界的交互式终端处理 host key、password、passphrase 或 MFA；TUI 可以在接管终端前交互；非交互 CLI 应快速失败并给出可操作指引（#2925）。
• 只有 Host 与 Client 都显式选择并由 Client 持久确认 insecure transport 风险时才允许 plaintext。不得增加自动降级或跳过证书验证（#2925）。
• 增加机器可读的 service readiness 输出和带版本的最小权限 Client access preset，让 Host operator 无需阅读内部 protocol 即可完成准备（#2911）。
• Credential 只进入平台 credential store 或环境输入，不得进入 profile 文档、命令行参数、日志或 onboarding 输出（#2911）。

2. Multi-Host Desktop

• 用彼此独立的 per-Host connection entry 替换单 active-target owner。改变新任务的默认 Host 不会断开其他 Host，也不会移动已有 Session（#3097）。
• 在 Session、Project、event、observation、diagnostics、notification 和 Client-local resource 引用中携带经过验证的 Host identity，避免不同 Host 的相同 raw ID 发生冲突（#2935）。
• 聚合已启用 Host 的 Session 摘要，显示 Host identity 与 per-Host readiness；重连期间保留有界的内存展示；每个已有 Session action 路由回所属 Host（#3097）。
• 新任务可以从任意已启用 Host 选择 Project，且不改变默认 Host（#3122）。
• Host-scoped Settings 使用显式 Host selector，不合并彼此无关的 Host domain（#3131）。
• Desktop 可以通过受限的 Host-side 目录选择器在 remote Host 注册 Project，但不开放通用 remote filesystem browser（#3145）。
• CLI/TUI 每个进程仍只选择一个 profile；Desktop multi-Host 展示保持为 Desktop 专属（#3097）。

3. Windows Local IPC 信任边界

• 验证 Windows named pipe 的实际访问边界；平台默认行为不足时，强制设置等价于 current-user 的 ACL（#3179、#3182）。
• 只有建立该边界后，才授予不受限的 local-owner authority（#3179、#3182）。
• 增加一个聚焦 unauthorized admission 的 Windows integration test，覆盖 replacement pipe instance，以及外部用户的只读、只写和双向访问（#3182）。

4. 生产强化

• 覆盖有代表性的跨 listener journey：两个 Client 观察和控制同一 Session、重连/catch-up、root mismatch，以及结果不确定的 command（收口审计：#3186）。
• 验证 slow consumer、queue exhaustion、malformed/oversized frame 和大型流式 payload 的有界行为（收口审计：#3186）。
• 验证 credential revoke 能阻断现有与后续 operation，且不会泄露 credential material（收口审计：#3186）。
• 验证 graceful drain、forced shutdown、service restart 和 capability-provider loss/rebind，包括 Automation waiting 与恢复（收口审计：#3186）。
• Domain 行为测试保持共享；每个 adapter 只运行一次 transport conformance，仅针对 transport 或 lifecycle 特有风险增加端到端用例（收口审计：#3186）。

完成标准

• Desktop 可以同时保持 Local 与远程 Host 连接，使用明确 Host identity 展示它们的 Session，并把每个 action 路由到所属 Host。
• CLI 与 TUI 可以选择同一套已保存 profile 中的一个，并观察或控制同一份 canonical Host state。
• Direct TLS、system SSH tunneling 与显式确认风险的 plaintext 都有清晰且不会降级的 onboarding 与失败行为。
• 远程 Client 配置能安全保存 Host identity 与 credential，不泄露 secret，也不会静默切换 root。
• 远程 workspace 选择以 Host 为范围，不会混淆 Client path 与 Host path。
• Windows Local IPC 在获得 local-owner authority 前具有显式的 same-user 信任边界。
• restart、disconnect、revocation、backpressure 和 shutdown 能够收敛，不产生重复 command、orphaned writer 或无界队列。
• 所有 listener 共享一个 protocol、一个 dispatcher、一个 execution authority 和一个 canonical state model。

非目标

• 用 WebSocket 替代 Local IPC
• Local IPC 到 WebSocket 的自动 fallback 或 transport downgrade
• Federated Host、跨 Host durable database 或跨 Host Session migration
• 在原生 Client milestone 中实现浏览器认证
• 多租户 Session 或 Project 隔离
• 在没有具体部署需求时设计 shared-filesystem path mapping
• 在没有测量依据时增加第二条 bulk data plane
• 增加第二套 Runtime、dispatcher、writer 或 recovery model

[M4n5ter]

English

Remote onboarding PR 2 is now available as draft #2925.

It adds system SSH tunneling for Desktop, TUI, and non-interactive CLI, plus plaintext WebSocket support that requires explicit opt-in from both the Host and Client. The implementation keeps the SSH process and Runtime Host connection under the existing single reconnect lifecycle and does not add transport downgrade or certificate-verification bypass.

Real verification covers Desktop and TUI against a LAN Runtime Host, including remote Project/Skill loading, Turn execution, cancellation, reconnect, and SSH process cleanup. The tracking checkboxes remain open until the PR is merged.

简体中文

远程 onboarding PR 2 已作为 Draft PR #2925 提交。

它为 Desktop、TUI 和非交互 CLI 增加 system SSH tunnel，并增加必须由 Host 与 Client 双方显式确认的 plaintext WebSocket。SSH process 与 Runtime Host connection 仍由现有单一 reconnect lifecycle 统一管理，没有增加 transport downgrade 或跳过证书验证。

真实验证已覆盖 Desktop 与 TUI 连接局域网 Runtime Host，包括远端 Project/Skill 加载、Turn 执行、取消、重连和 SSH process cleanup。跟踪项会在 PR 合并后再标记为完成。