feat(cli): coordinate local Runtime Host handoff across npm upgrades

[me2seeks]

English

Problem

Updating the installed CLI and replacing the local Runtime Host are currently two unrelated actions.

The released documentation tells users to run npm install --global maka-agent@next, but npm does not know whether an older Runtime Host still owns the State Root. Durable Goals or Scheduled Tasks may keep that Host resident after every TUI exits. The new CLI may then reuse an older Host build when the compatibility epoch is unchanged, or be rejected before Domain admission when the epoch changed.

The CLI currently does not send a Host generation, does not expose an update command, and cannot reconcile an externally replaced global installation with the active local Host.

Desired outcome

Provide one installation-owner flow that coordinates a persistent CLI release change with the small Host retirement contract tracked by #3231.

The flow must distinguish:

1. an update initiated by the still-compatible old CLI;
2. startup after the user already ran an external global npm install;
3. a compatible active Host whose release differs from the installed CLI;
4. an incompatible active Host that ordinary Domain operations cannot control.

Scope

• Define a stable installed-release identity suitable for diagnostics and exact artifact selection; do not use product-version distance as the compatibility gate (discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204)
• Expose the active local Host release/build identity and installation ownership without conflating them with hostEpoch
• Add an explicit installed-CLI update entry point, initially bounded to supported npm global installations
• Resolve and verify an exact release before retiring the active Host
• Use [Tracking] Runtime Host maintenance and single-writer retirement #3231 to assess activity, request retirement, preserve durable intent, and release the sole writer
• Perform package switching and replacement verification in the installation-management plane, not in Runtime Host Domain authority
• On startup after an external npm install, reconcile the installed release with the active local Host and offer truthful use-existing / restart / wait / cancel actions
• Make retries and concurrent update attempts converge on one installation transition
• Cover update failure before retirement, failure after writer release, unsupported downgrade, and unresolved external effects
• Test released-version transitions with real persisted State Roots, including compatibility epoch changes and same-epoch build changes

Stable constraints

• A normal compatible Client may continue using an active Host; build difference alone is not protocol incompatibility.
• Only the local installation owner may replace its local Host.
• An ordinary remote Runtime Host credential never gains deployment or service authority.
• The active Host never overwrites its own executable.
• Package switching must not create two active writers for one State Root.
• Rollback is claimed only when storage and external-effect evidence prove it safe.

Non-goals

• Managed remote Host deployment or update policy ([Tracking] Managed remote Runtime Host onboarding and lifecycle #3228)
• TUI presentation and slash-command design (tracked separately)
• Defining the compatibility window (discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204)
• Making npx cache entries persistent installation owners (tracked separately)
• A Runtime Host-owned universal deployment state machine

Success criteria

• An old compatible CLI can stage an exact release, obtain explicit maintenance authorization, retire its Host, switch the installation, and verify the replacement.
• A new CLI started after an external npm install can identify the active Host release and recover without asking users to find and kill an unexplained process.
• Compatible release skew never forces replacement solely because version strings differ.
• An incompatible local Host produces actionable owner choices rather than an unbounded wait.
• Failed or concurrent updates leave one truthful installation state and at most one State Root writer.

Part of #3231. Compatibility policy remains in #3204.

简体中文

问题

当前“更新已安装 CLI”和“替换本地 Runtime Host”是两件互不协调的事。

发布文档要求用户执行 npm install --global maka-agent@next，但 npm 不知道旧 Runtime Host 是否仍拥有 State Root。durable Goal 或 Scheduled Task 可以在所有 TUI 退出后继续让旧 Host 常驻。此后启动新 CLI：compatibility epoch 相同时可能继续复用旧 Host build；epoch 改变时则会在 Domain 准入前被拒绝。

当前 CLI 不发送 Host generation，没有 update 命令，也不能协调“全局 npm 安装已经被外部替换”与“旧本地 Host 仍在运行”这两个事实。

期望结果

提供一条 installation-owner 流程，把持久 CLI release 变更与 #3231 跟踪的小型 Host retirement contract 连接起来。

必须区分：

1. 仍与 Host 兼容的旧 CLI 主动发起更新；
2. 用户已经在外部执行全局 npm 安装后再启动新 CLI；
3. active Host 与已安装 CLI release 不同，但仍兼容；
4. active Host 已不兼容，普通 Domain operation 无法控制。

范围

• 定义用于诊断和精确 artifact selection 的稳定 installed-release identity；不以产品版本距离作为兼容 gate（discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204）
• 展示 active local Host 的 release/build identity 与 installation ownership，并与 hostEpoch 区分
• 增加显式的 installed-CLI update 入口，第一阶段只支持明确范围内的 npm global installation
• 在 current Host 退场前解析并验证精确 release
• 复用 [Tracking] Runtime Host maintenance and single-writer retirement #3231 完成 activity assessment、明确 retirement、durable intent 保存和唯一 writer 释放
• Package 切换与 replacement 验证属于 installation-management plane，不属于 Runtime Host Domain authority
• 用户先执行外部 npm install 时，新 CLI 启动后应协调 installed release 与 active Host，并提供真实的继续使用、重启、等待和取消操作
• 并发更新与重试必须收敛到一个 installation transition
• 覆盖 retirement 前失败、writer 释放后失败、不支持的 downgrade 与 unresolved external effect
• 使用真实持久 State Root 测试已发布版本转换，包括 compatibility epoch 变化和同 epoch build 变化

稳定约束

• 普通兼容 Client 可以继续使用 active Host；build 不同本身不等于协议不兼容。
• 只有本地 installation owner 可以替换其本地 Host。
• 普通 remote Runtime Host credential 不获得 deployment 或 service authority。
• Active Host 不覆盖自己的 executable。
• Package 切换不能为一个 State Root 创建两个 active writer。
• 只有 storage 与 external-effect 证据证明安全时才宣称支持 rollback。

非目标

• Managed remote Host 部署或更新策略（[Tracking] Managed remote Runtime Host onboarding and lifecycle #3228）
• TUI 展示和 slash-command 设计（另行跟踪）
• 定义兼容窗口（discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204）
• 直接把 npx cache 视为持久 installation owner（另行讨论）
• Runtime Host 拥有的通用 deployment 状态机

完成标准

• 旧的兼容 CLI 可以 stage 精确 release、获得明确维护授权、让 Host 退场、切换安装并验证 replacement。
• 用户先执行外部 npm install 后，新 CLI 可以识别 active Host release 并恢复，不再要求用户自行寻找和结束未知进程。
• 兼容 release skew 不会仅因版本字符串不同而强制替换。
• 不兼容的本地 Host 会提供可操作的 owner 选择，而不是无限等待。
• 更新失败或并发执行时仍只有一个真实 installation state，并且一个 State Root 至多一个 writer。

属于 #3231；兼容策略仍由 #3204 负责。

AI assistance disclosure

This issue was investigated and drafted with Codex using current source, live npm registry metadata, and isolated Runtime Host experiments.

[me2seeks]

I’m working on this.

我正在推进这项工作。

[me2seeks]

Implementation handoff after the local-owner foundations

The prerequisites for this issue are now concrete:

• refactor(runtime-host): share verified deployment identity #3766 merged the verified npm deployment identity.
• feat(runtime-host): add durable local deployment ownership #3767 merged the durable machine-account-local owner record and transition authority.
• feat(runtime-host): coordinate local owner transfer #3769 merged the serialized local-process owner-transfer transaction.

No new tracking issue is needed for the next vertical slice: this issue already owns installed CLI/npm reconciliation and handoff. #3709 remains the architecture umbrella, while #3244 and #3245 separately own direct npx lifecycle and TUI presentation.

Merged PR #3813 deepens that transaction into one local deployment handoff for both owner-preserving replacement and cross-owner transfer, and removes the uncoordinated direct selection path. This closes the missing same-owner transaction prerequisite without adding a second journal, lock, or recovery machine.

Merged PR #3816 independently resolves the stable npm-global CLI owner and a truthful mutable installed-release observation. Real isolated npm evidence showed that global installs do not retain dist.integrity, so exact deployment identity must come from separately verified immutable staging rather than the mutable installed package.

The foundations are now merged. The remaining implementation here should resolve the source-specific facts that neither foundation invents:

1. derive a stable persistent CLI installation owner and a truthful mutable installed-release observation;
2. resolve and immutably stage the exact verified target before any authority mutation;
3. observe whether the durable owner is absent, the same CLI installation, or another installation;
4. bind retirement/activation/Ready evidence to the exact staged process and package closure;
5. return typed outcomes for later Restart / Wait / Cancel presentation without moving policy into connectOrSpawn.

The first slice should not absorb direct npx, TUI UX, Desktop deployment evidence, managed remote mutation, or a second deployment journal/lock.

简体中文

#3766 已交付 verified npm deployment identity，#3767 已交付 durable local owner authority，#3769 已合并 serialized local-process owner-transfer transaction。

下一条垂直主线已经由本 issue（#3243）负责，因此不需要再创建重复 issue。Merged PR #3813 已把同 owner replacement 与跨 owner transfer 收敛为一条 local deployment handoff，并删除不受协调的直接 selection 路径；它不会增加第二份 journal、lock 或 recovery machine。Merged PR #3816 已独立解析稳定的 npm-global CLI owner 与真实但可变的 installed-release observation。隔离 npm 取证证明 global install 不保留 dist.integrity，因此 exact deployment identity 必须来自另行验证的 immutable staging，不能从本地可变 package 猜测。The foundations are now merged. 后续继续实现 exact target staging、空 owner / 同 owner / 跨 owner 的区分、绑定 exact staged process/package closure 的 retirement/activation/Ready 证据，以及供 Restart / Wait / Cancel 展示消费的 typed outcome。

首个切片不吸收 direct npx、TUI UX、Desktop identity、remote mutation，也不增加第二份 journal 或 lock。

Generated-by: Codex

[me2seeks]

Ready PR #3920 now connects the merged owner/handoff and npm-global installation facts to one shipped local TUI Restart slice.

It reuses the verified registry acquisition path and extracts the existing managed-service package store as the shared integrity-keyed implementation. On explicit user Restart, the installed npm-global owner stages the exact current registry release before mutation, then either establishes the first owner after exact Ready or uses the existing durable handoff. The bounded released-Host adapter targets only the observed local ephemeral Host and succeeds only when legacy takeover reports true idle.

This does not close #3243. Active or durable work is not interrupted by this legacy adapter; service, remote, unknown-lifecycle, and direct npx callers remain outside local mutation authority. Explicit npm package switching and the newer active-work retirement/recovery path remain follow-up slices.

简体中文

Ready PR #3920 已把此前合并的 owner/handoff 与 npm-global installation facts 接入一条真实 TUI Restart 路径。用户明确选择 Restart 后，流程先用 registry 证据固化精确目标，再在 exact Ready 后建立 initial claim，或复用已有 durable handoff；legacy adapter 只针对观测到的本地 ephemeral Host，并且只在旧 Host 确认 true idle 时替换。

该 PR 不关闭 #3243：active/durable work 不会被 legacy adapter 强制中断；service、remote、unknown lifecycle 与 direct npx 仍无本地 mutation authority。显式 npm package switch 与新的 active-work retirement/recovery 仍是后续切片。

Generated-by: Codex