discussion(runtime-host): define version skew and operator-led remote Host upgrades

[me2seeks]

Question

How should Maka let a newer Desktop, TUI, or CLI keep using a shared remote Runtime Host without making Host idleness a precondition, while preserving one Runtime Host authority for one State Root?

This discussion follows #3203. That issue is intentionally narrow: preserve the safe incompatibility facts already returned by the handshake. It does not choose a deployment policy.

Current facts

Current

• A Runtime Host is the long-lived process that owns one State Root and its Runtime work. One process owns that root's writes, and one Hosted Execution authority admits and stops top-level Session work.
• The Host Kernel owns the State Root's exclusive writer lease. Composition and its Module set are fixed before Ready.
• A remote profile is Client-owned connection configuration, not Host state or lifecycle authority.
• The current handshake rejects a compatibilityEpoch mismatch before a Domain command is admitted. The current protocolMin/protocolMax values do not yet provide a supported skew window.
• Existing coverage proves that a remote Client reconnects to canonical state after a service restart. It does not claim zero-downtime upgrade of incompatible Runtime semantics.
• Managed Linux Hosts now support an explicitly authorized exact-package maintenance transaction: stage, exact-Host retirement, service cutover, replacement readiness/version verification, and truthful incomplete-update recovery (feat(runtime-host): add managed Host retirement #3557, feat(runtime-host): add safe managed Host updates #3591). This supplies the replacement mechanism but does not define a supported Client–Host skew window.

Relevant anchors:

• docs/architecture/runtime-host-architecture.md — one State Root writer, one Hosted Execution authority, fixed Composition
• packages/runtime-host/src/protocol/index.ts — Client/Host handshake and compatibility epoch
• packages/runtime-host/src/server/host-kernel.ts — handshake admission and lifecycle
• packages/runtime-host/src/__tests__/authenticated-websocket.test.ts — remote service restart and canonical-state recovery

Constraints

Any direction must preserve all of the following:

1. One State Root has at most one writer owner.
2. One Session has at most one root Hosted Execution or pending root admission.
3. Desktop, TUI, CLI, and WebSocket transport remain Clients; none gains remote service lifecycle authority from an access credential.
4. An incompatibility never admits a Domain command, replays a command, or silently downgrades transport.
5. An AI agent may diagnose or draft an upgrade plan, but cannot silently deploy, replace, or restart a remote Host.

Direction to evaluate

Exploratory

1. Make ordinary release skew a negotiated contract, not an exact product-version test

Keep a product release identifier for diagnostics, artifact selection, and support. Do not use it as the connection gate.

Instead, define a bounded, explicit Client–Host compatibility contract:

• a Host advertises supported protocol/contract revisions and safe capabilities;
• a Client selects only a mutually supported revision and hides unsupported capabilities;
• an epoch mismatch remains unsafe unless the Host intentionally ships and advertises a compatible decoder/adapter for that older contract;
• no Client infers that the Host is "older" or that it may update the Host merely from a mismatch.

This is analogous to an explicit version-skew policy, not a claim that arbitrary builds are interoperable. Kubernetes, for example, publishes a bounded client/control-plane skew policy rather than requiring every kubectl binary to equal the server version.

2. Keep remote Host deployment operator-led by default

The default remote profile remains operator_managed in behavior, whether or not that name becomes a persisted field:

• the Host operator selects the exact release artifact and authorizes service start, retirement, replacement, and any safe rollback;
• Desktop or CLI may execute that explicit transaction over the SSH management plane after operator confirmation, as delivered by feat(runtime-host): add safe managed Host updates #3591;
• ordinary Runtime Host Client credentials remain separate from deployment authority, and no connection or compatibility failure triggers a silent update.

VS Code and Zed automatically arrange exact local-client-matched remote binaries. That is useful installation UX for client-managed editor backends, but it is not a safe default for Maka's shared, durable Runtime Host.

3. Handle genuinely incompatible Host upgrades as one-Host recovery, not parallel Runtime ownership

When a new Host build cannot support the active contract, there is no safe promise of an uninterrupted in-place semantic upgrade under the current architecture. The operator must use an explicit maintenance path:

1. stage and verify the signed artifact without mutating the active Host;
2. announce a pending upgrade and stop admitting only the work that the maintenance policy forbids;
3. drain or explicitly interrupt work according to existing durable/result-unknown rules;
4. close the sole Host, start the replacement against the same State Root, and recover canonical state;
5. reconnect Clients under a new Host Epoch and expose any unresolved external effect honestly.

The key usability property is that normal Client updates do not require this path: compatible Clients keep using the active Host. A breaking Host update is an operator maintenance event, not an automatic Client action.

Explicit non-direction

The following is not proposed for the current Runtime Host architecture:

one State Root
 ├─ Runtime Host / execution revision A
 └─ Runtime Host / execution revision B

If each branch owns Composition, Session lifecycle, or durable writes, it creates a second Runtime authority and violates the existing one-Host contract. Session-pinned multi-worker revisions may be worth a separate future architecture exploration only after a stable supervisor/worker boundary exists; it is not implied here.

Design questions

1. Which compatibility tuple should be advertised: protocol range alone, or a versioned contract plus capability set?
2. What bounded skew window is supportable, and which operation/capability additions can be safely feature-gated?
3. Should a Host advertise release channel/build identity and a signed update manifest reference solely for diagnostics? What fields are safe to disclose?
4. What are the exact draining, maintenance, restart, and recovery UX states for remote Clients?
5. Which evidence is required before allowing a new compatibility window: two-version protocol tests, restart recovery, revocation, no-command-replay, and external-effect uncertainty tests?

References

• VS Code requires its remote server to match the Client exactly and automatically installs or updates that server: https://code.visualstudio.com/api/advanced-topics/remote-extensions
• Zed checks the remote binary against the local Zed version and installs the matching binary: https://zed.dev/docs/remote-development
• Kubernetes documents bounded component version skew: https://kubernetes.io/releases/version-skew-policy/
• Temporal documents pinned and draining deployment versions for durable workflows: https://docs.temporal.io/worker-versioning

简体中文

问题

在保持一个 State Root 只有一个 Runtime Host authority 的前提下，Maka 应如何让较新的 Desktop、TUI 或 CLI 继续使用共享 remote Runtime Host，而不把“Host 必须空闲”变成用户可用性的前提？

本讨论承接 #3203。#3203 只负责保留握手已返回的安全不兼容事实，不决定部署策略。

当前事实

Current

• Runtime Host 是拥有一个 State Root 及其 Runtime work 的长期运行进程。一个进程拥有该 root 的写入权，一个 Hosted Execution authority 准入并停止顶层 Session work。
• Host Kernel 拥有 State Root 的 exclusive writer lease；Composition 及其 Module set 在 Ready 前固定。
• remote profile 是 Client-owned connection configuration，不是 Host state，也不拥有 Host lifecycle authority。
• 当前握手会在任何 Domain command 准入前拒绝 compatibilityEpoch mismatch；当前 protocolMin/protocolMax 尚未形成受支持的 skew window。
• 现有测试证明 remote Client 可在 service restart 后重连并读取 canonical state；它不宣称 incompatible Runtime semantics 可以 zero-downtime 升级。
• Managed Linux Host 现在支持经过明确授权的精确 package 维护事务：stage、精确 Host retirement、service cutover、replacement readiness/version 验证，以及如实报告 incomplete update 的恢复结果（feat(runtime-host): add managed Host retirement #3557、feat(runtime-host): add safe managed Host updates #3591）。这提供了 replacement mechanism，但没有定义受支持的 Client–Host skew window。

相关锚点：

• docs/architecture/runtime-host-architecture.md — one State Root writer、one Hosted Execution authority、fixed Composition
• packages/runtime-host/src/protocol/index.ts — Client/Host handshake 与 compatibility epoch
• packages/runtime-host/src/server/host-kernel.ts — handshake admission 与 lifecycle
• packages/runtime-host/src/__tests__/authenticated-websocket.test.ts — remote service restart 与 canonical-state recovery

约束

任何方向都必须保持：

1. 一个 State Root 至多有一个 writer owner。
2. 一个 Session 至多有一个 root Hosted Execution 或 pending root admission。
3. Desktop、TUI、CLI 与 WebSocket transport 均是 Client；access credential 不会赋予其 remote service lifecycle authority。
4. incompatibility 不会准入 Domain command、重放 command 或静默降级 transport。
5. AI agent 可以诊断或起草升级计划，但不能静默部署、替换或重启 remote Host。

待评估方向

Exploratory

1. 将普通 release skew 设计为协商契约，而非精确 product-version 检查

product release identity 用于诊断、artifact selection 与支持，不作为 connection gate。Host 广告受支持的 protocol/contract revisions 与 safe capabilities；Client 只选择双方支持的 revision，并隐藏不支持的 capability。epoch mismatch 仍不安全，除非 Host 明确提供并广告旧 contract 的 compatible decoder/adapter。任何 Client 都不会从 mismatch 推断 Host “旧了”，或获得更新 Host 的权力。

2. 默认保持 remote Host deployment 由 operator 管理

默认 remote profile 在行为上仍为 operator_managed：operator 选择精确 release artifact，并授权 service start、retirement、replacement 以及有证据支持的安全 rollback；Desktop 或 CLI 可以在 operator 明确确认后，通过 SSH management plane 执行 #3591 已交付的显式事务；普通 Runtime Host Client credential 仍与 deployment authority 分离，连接或兼容失败也不会触发静默更新。

3. 真正不兼容的 Host 升级使用 one-Host recovery，而不是 parallel Runtime ownership

若新 Host build 无法支持 active contract，当前架构不能安全承诺不中断的 in-place semantic upgrade。operator 应走显式 maintenance path：先 stage/verify artifact，不修改 active Host；宣布 pending upgrade；按已有 durable/result-unknown 规则 drain 或明确 interrupt work；关闭唯一 Host；以同一 State Root 启动 replacement 并恢复 canonical state；Client 在新 Host Epoch 下重连，并如实显示 unresolved external effect。

正常 Client update 不需走此路径：兼容 Client 继续使用 active Host。breaking Host update 是 operator maintenance event，不是自动 Client action。

明确不采纳的方向

下面的结构不属于当前 Runtime Host 架构：

one State Root
 ├─ Runtime Host / execution revision A
 └─ Runtime Host / execution revision B

若两个分支各自拥有 Composition、Session lifecycle 或 durable write，就会产生第二个 Runtime authority，违反 one-Host contract。Session-pinned multi-worker revision 只能在未来已有稳定 supervisor/worker boundary 后另行探索，本讨论不暗示其已可实施。

设计问题

1. 应广告 protocol range，还是 versioned contract 加 capability set？
2. 可支持的 bounded skew window 是什么；哪些 operation/capability 新增可安全 feature-gate？
3. Host 是否应只为诊断广告 release channel/build identity 与 signed update manifest reference；哪些字段可安全公开？
4. remote Client 的 draining、maintenance、restart 与 recovery UX state 是什么？
5. 放开新的 compatibility window 前，需要哪些证据：two-version protocol test、restart recovery、revocation、no-command-replay 与 external-effect uncertainty test？

参考

• VS Code：https://code.visualstudio.com/api/advanced-topics/remote-extensions
• Zed：https://zed.dev/docs/remote-development
• Kubernetes：https://kubernetes.io/releases/version-skew-policy/
• Temporal：https://docs.temporal.io/worker-versioning

[me2seeks]

Additional evidence strengthens the need for a bounded version-skew contract:

• fix(cli): diagnose residency-blocked local Runtime Host version conflicts #3207 shows that durable residency can keep a local ephemeral Host alive after every Surface disconnects. Active recurring Scheduled Tasks are another concrete case, so waiting for idle exit may never make progress.
• The Desktop in-app updater can ask its currently compatible local Host to drain. Once a newly installed Client is already incompatible, however, the handshake rejects Domain commands before that Client can request the same preparation.
• A remote service Host does not idle-exit and is installed and restarted separately by its operator. Remote Client credentials do not grant deployment authority.
• chore(runtime-host): ClientSurface is a required handshake field with zero readers #3216 demonstrates the smaller wire-evolution case: even removing an unused required handshake field needs a staged rollout that preserves interoperability with supported older peers.

This does not change the one-Host authority boundary or imply automatic replacement of a shared remote Host. It suggests two separate deliverables:

1. discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204 defines the bounded Client–Host compatibility contract and rollout rules.
2. A follow-up issue defines the complete local and remote upgrade UX: diagnostics, drain, restart, recovery, verification, and rollback.

One remaining question is what safe operator-control path is available after the ordinary Domain protocol is already incompatible, especially when durable residency prevents an ephemeral Host from exiting naturally.

简体中文

补充证据进一步说明需要明确的版本兼容窗口：

• fix(cli): diagnose residency-blocked local Runtime Host version conflicts #3207 证明 durable residency 会让本地 Host 在所有 Surface 退出后继续运行；长期定时任务也会产生同样情况，因此单纯等待 Host 空闲可能永远没有结果。
• Desktop 的应用内更新可以让当前兼容的本地 Host drain；但新版 Client 已经不兼容时，会在 Domain command 前被拒绝，无法再请求升级准备。
• remote service Host 不会因 Client 退出而关闭，安装和重启仍由 operator 管理。
• chore(runtime-host): ClientSurface is a required handshake field with zero readers #3216 也说明，即使删除一个未使用的必填握手字段，也必须分阶段发布，保证受支持的新旧版本可以互通。

这不改变 one-Host authority，也不代表 Client 可以自动替换共享 Host。建议 #3204 继续定义兼容契约和发布规则，另开 Issue 讨论完整的本地与远程升级体验。

仍需回答：当普通 Domain protocol 已经不兼容，同时 durable residency 又阻止旧 Host 自动退出时，应保留什么安全的 operator-control path？

[me2seeks]

One additional compatibility case seems important for a shared remote Host:

Host N
├─ Desktop N
├─ TUI N-1
└─ Desktop N+3

If Desktop N+3 cannot use Host N, upgrading the shared Host to N+3 may make Desktop N or TUI N-1 incompatible. A newer Surface therefore should not translate host_too_old directly into permission to update the Host.

Compatibility likely needs to be negotiated through supported contract revisions and capabilities rather than product-version distance. If a common base contract exists, the newer Surface should connect with unsupported features disabled. Only when no safe contract intersection exists should the connection be rejected, with an operator-directed update recommendation.

Before replacing a shared Host, upgrade assessment should also report which connected Client contracts the target Host would stop supporting. Offline Clients cannot be discovered, so this additionally requires a published minimum supported Client-contract policy.

In short: a Surface may report that a Host update is required, but an ordinary Surface should neither decide nor perform the update of a shared remote Host.