feat(cli): reconcile local Runtime Host generations

[me2seeks]

Current status

This Draft is paused as implementation and qualification evidence while #3709 and the #3228 reconciliation gates stabilize. It is not the target owner architecture and should not be marked Ready in its current form. The retained value is its generation/epoch diagnostics, Restart/Wait/Cancel UX, exact-epoch fencing, released-Host takeover adapter, and real PTY evidence. After the gates close, the implementation should be split or rewritten so replacement policy no longer lives in ordinary connectOrSpawn election.

简体中文

本 Draft 暂停实现，用作 #3709 与 #3228 reconciliation gate 稳定前的实现和 qualification 证据。它不是目标 owner 架构，当前形态不应转为 Ready。需要保留的是 generation/epoch 诊断、Restart/Wait/Cancel UX、exact-epoch fencing、已发布 Host takeover adapter 与真实 PTY 证据。Gate 闭合后应拆分或重写实现，使 replacement policy 不再位于普通 connectOrSpawn election 中。

Convergence disposition

The branch has now been audited against the owner/transfer rules in #3709. When work resumes, it should be split or rewritten according to this inventory; the current Draft must not be merged as one lifecycle implementation.

Retain as evidence

• real PTY Restart / Wait / Cancel scenarios across released compatibility epochs;
• exact observed-HostEpoch fencing and stale-takeover rejection;
• same-epoch compatibility evidence showing that build/deployment skew does not require replacement;
• remote-profile and service-mode isolation;
• bounded Host activity/residency diagnostics and explicit interruption warning;
• invocation and cache-disappearance scenarios, rewritten against the selected npx contract.

Migrate behind the owner/reconciler seam

• TUI conflict wording and decision parsing become a thin presentation adapter over typed connect | owner_transfer_required | wait | cancel | operator_required outcomes;
• the handshake takeover path becomes a bounded released-Host capability adapter with an explicit removal condition;
• package/provenance resolution becomes an input adapter that returns verified DeploymentIdentity; it does not decide authority;
• candidate launch keeps exact deployment identity, but it is invoked by the owner transaction rather than ordinary connection election;
• _npx detection remains a negative provenance guard shared with managed setup, never positive owner proof.

Delete or rewrite

• replacement-policy fields and the extra exact-generation probe carried through ordinary connectOrSpawn;
• installationScope === 'persistent' as replacement authority;
• package version or a per-process development UUID as verified deployment identity;
• the TUI-owned retry/replacement loop as a lifecycle state machine;
• any last-launch-wins behavior or implication that a successful connection, package path, PID, version, or compatible epoch transfers ownership;
• the branch-local architecture drafts in their current form once their durable decisions and qualification evidence are captured by architecture(runtime-host): converge local Host lifecycle through owner-scoped reconciliation #3709; they should not become a second target-architecture authority.

Simplification result

• P0: none.
• P1 — remove lifecycle authority from ordinary connection election. localGenerationRequest, candidateGeneration, and the TUI-owned retry loop currently form a parallel replacement path. Migrating the released-Host takeover mechanism behind one owner transaction lets these connection-level policy representations and the Surface state machine disappear while preserving compatibility admission and exact-epoch fencing.
• P2 — remove proxy identities and proxy authority. installationScope === 'persistent' and version/development-UUID generation are maintained only to approximate facts now owned by the durable owner record and verified DeploymentIdentity. The shared _npx detector remains because managed setup and invocation policy still consume its negative provenance fact.
• P2 — remove duplicate target-architecture documents from the eventual implementation PR. architecture(runtime-host): converge local Host lifecycle through owner-scoped reconciliation #3709 is now the target architecture and decision authority. The PR should retain links, tests, and implementation-specific documentation, not another full lifecycle design whose Current/Planned status can drift.
• Decision gate — legacy adapter removal. The handshake takeover path remains until the minimum supported released Host set exposes the stable owner-side lifecycle capability; the decisive evidence is the released-version support/qualification matrix.
• Decision gate — rollback qualification. Previous-artifact retry cannot be simplified into unconditional rollback until fix(storage): retire completed legacy migration metadata #3227 proves the relevant storage transitions safe.

Audit coverage

Slice	Status	Disposition
installation/provenance context	Reviewed	retain resolution seam and shared _npx guard; replace authority and identity inference
ordinary local connection/election	Reviewed	remove replacement policy; preserve compatibility admission
TUI conflict adapter	Reviewed	retain presentation and decision vocabulary; migrate lifecycle ownership
Host handshake takeover	Reviewed	retain only as bounded legacy adapter
remote/service isolation	Reviewed	retain unchanged operator boundary
unit/integration/PTY qualification	Reviewed	migrate invariant and released-artifact evidence, not branch structure
branch architecture documents	Reviewed	consolidate target authority in #3709; rewrite or remove duplicated Current claims
storage downgrade/recovery	Partial	retain fail-closed boundary; exact qualification remains owned by #3227

简体中文

收敛处置清单

该分支已经按 #3709 的 owner/transfer 规则完成审计。恢复工作后，应依据以下清单拆分或重写；当前 Draft 不能作为一整套 lifecycle implementation 合并。

作为证据保留

• 跨已发布 compatibility epoch 的真实 PTY Restart / Wait / Cancel 场景；
• 绑定 observed HostEpoch 的精确 fencing 与 stale takeover rejection；
• 证明 same-epoch build/deployment skew 不要求 replacement 的兼容性证据；
• remote profile 与 service-mode 隔离；
• 有界 Host activity/residency 诊断和明确 interruption warning；
• invocation 与 cache disappearance 场景，但要按已选 npx contract 重写。

迁移到 owner/reconciler seam 后面

• TUI conflict 文案与 decision parsing 变成 typed connect | owner_transfer_required | wait | cancel | operator_required outcome 的薄 presentation adapter；
• handshake takeover 变成有明确删除条件的 bounded released-Host capability adapter；
• package/provenance resolution 变成返回 verified DeploymentIdentity 的 input adapter，不再决定 authority；
• candidate launch 保留 exact deployment identity，但由 owner transaction 调用，不再由普通 connection election 调用；
• _npx detection 保留为与 managed setup 共享的负向 provenance guard，永远不是正向 owner proof。

删除或重写

• 普通 connectOrSpawn 中携带的 replacement-policy 字段与额外 exact-generation probe；
• 把 installationScope === 'persistent' 当作 replacement authority；
• 把 package version 或 process-scoped development UUID 当作 verified deployment identity；
• 把 TUI-owned retry/replacement loop 当作 lifecycle state machine；
• 任何 last-launch-wins 行为，以及“成功连接、package path、PID、version 或 compatible epoch 会转移 ownership”的暗示；
• 当前形态的 branch-local architecture draft：其中长期有效的决定和 qualification 证据进入 architecture(runtime-host): converge local Host lifecycle through owner-scoped reconciliation #3709 后，不应再形成第二个 target-architecture authority。

简化审计结果

• P0： 无。
• P1——从普通 connection election 删除 lifecycle authority。 localGenerationRequest、candidateGeneration 与 TUI-owned retry loop 当前形成一条平行 replacement path。把 released-Host takeover mechanism 迁移到唯一 owner transaction 后，可以删除这些 connection-level policy representation 与 Surface state machine，同时保留 compatibility admission 和 exact-epoch fencing。
• P2——删除代理 identity 与代理 authority。 installationScope === 'persistent' 和 version/development-UUID generation 只是近似 durable owner record 与 verified DeploymentIdentity 应拥有的事实。共享 _npx detector 仍保留，因为 managed setup 与 invocation policy 真实消费它提供的负向 provenance fact。
• P2——从最终 implementation PR 删除重复 target-architecture document。 architecture(runtime-host): converge local Host lifecycle through owner-scoped reconciliation #3709 已是目标架构与决策 authority。PR 应保留链接、测试和 implementation-specific 文档，而不是再维护一份 Current/Planned 状态可能漂移的完整 lifecycle design。
• Decision gate——legacy adapter 删除时机。 在最低支持的 released Host 集合提供稳定 owner-side lifecycle capability 前，handshake takeover path 仍要保留；决定性证据是 released-version support/qualification matrix。
• Decision gate——rollback qualification。 在 fix(storage): retire completed legacy migration metadata #3227 证明相关 storage transition 安全前，previous-artifact retry 不能简化成无条件 rollback。

审计覆盖

Slice	状态	处置
installation/provenance context	Reviewed	保留 resolution seam 与共享 _npx guard；替换 authority/identity inference
普通 local connection/election	Reviewed	删除 replacement policy；保留 compatibility admission
TUI conflict adapter	Reviewed	保留 presentation/decision vocabulary；迁移 lifecycle ownership
Host handshake takeover	Reviewed	仅作为 bounded legacy adapter 保留
remote/service isolation	Reviewed	保持 operator boundary 不变
unit/integration/PTY qualification	Reviewed	迁移 invariant 与 released-artifact evidence，不迁移 branch structure
branch architecture documents	Reviewed	target authority 收敛到 #3709；重写或删除重复的 Current claim
storage downgrade/recovery	Partial	保留 fail-closed boundary；精确 qualification 仍由 #3227 负责

Summary

Teach the local CLI/TUI to identify the installation that supplied its Runtime Host candidate and negotiate that candidate generation explicitly.

Compatible same-epoch Clients continue using the active Host even when builds differ. For a local cross-epoch conflict, TUI presents Restart, Wait, or Cancel using authoritative Host activity; Restart is fenced to the observed Host epoch. Remote profiles never receive local replacement authority, and transient npx launches cannot request takeover.

This is the first bounded slice of the installation lifecycle design. Artifact staging/switching, a public update command, same-epoch replacement, managed remote updates, and durable npx ownership remain out of scope.

Refs #3231
Refs #3243
Refs #3244
Refs #3245
Refs #3709

Verification

• Biome check passed for the changed code and tests.
• @maka/core, @maka/storage, @maka/mcp, @maka/runtime, @maka/runtime-host, and maka-agent builds passed.
• Runtime Host and CLI typechecks passed.
• Focused CLI/context, service guard, and Host candidate-generation tests passed (19/19).
• Real PTY epoch 24 → 26 checks covered Restart, Wait, and Cancel while a Scheduled Task retained the old Host.
• git diff --check passed.

Not run: full repository test suite or Desktop UI tests.

Draft scope

• Resolve installation scope and artifact generation once per CLI launch
• Admit compatible same-epoch Clients without replacing the Host
• Fence explicit local takeover to the observed Host epoch
• Keep remote and transient npx callers outside local replacement authority
• Document Current, Planned, and Exploratory lifecycle boundaries
• Review product wording and protocol ownership with maintainers
• Add release-package and platform qualification before marking ready

AI use

Select exactly one:

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

Tool(s) and scope: Codex assisted with architecture analysis, implementation, documentation, tests, and local review. The human contributor will review the Draft before it is submitted for merge.

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