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

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

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