Repository navigation
feat(cli): coordinate local Runtime Host handoff across npm upgrades #3243
Description
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:
- an update initiated by the still-compatible old CLI;
- startup after the user already ran an external global npm install;
- a compatible active Host whose release differs from the installed CLI;
- 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
npxcache 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.
简体中文
问题
当前“更新已安装 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 连接起来。
必须区分：
- 仍与 Host 兼容的旧 CLI 主动发起更新；
- 用户已经在外部执行全局 npm 安装后再启动新 CLI；
- active Host 与已安装 CLI release 不同，但仍兼容；
- 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）
- 直接把
npxcache 视为持久 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。
AI assistance disclosure
This issue was investigated and drafted with Codex using current source, live npm registry metadata, and isolated Runtime Host experiments.
Activity
me2seeks commentedon Aug 19, 2026
I’m working on this.
我正在推进这项工作。
me2seeks commentedon Aug 25, 2026
Implementation handoff after the local-owner foundations
The prerequisites for this issue are now concrete:
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
npxlifecycle 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:
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 commentedon Aug 26, 2026
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
npxcallers 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
me2seeks commentedon Aug 26, 2026
Ready PR #3925 implements the explicit installed-update slice that remained after #3920.
It adds
maka update --target <next|latest|version>, stages and revalidates the exact official archive before authority mutation, retires the current Host with the current package, activates and verifies the replacement with the target package (including epoch changes), switches the npm-global installation, and commits the durable owner only after exact verification. The existing authority lease is inherited by activation/package-switch children so coordinator failure cannot open a concurrent-owner window.Active work is refused by default and requires explicit
--allow-interrupt-active-tasks. Directnpx, development installs, downgrades, remote Hosts, and operator-managed services fail closed. The issue remains open after this PR because external npm mutation reconciliation and released persisted-root qualification are still outstanding success criteria.简体中文
Ready PR #3925 实现 #3920 之后剩余的显式 installed-update 主线：新增
maka update --target <next|latest|version>；在 authority mutation 前固化并复核官方精确 archive；用当前包让旧 Host 退场，用目标包跨 epoch 激活并验证 replacement；切换 npm-global 安装；最后才提交 durable owner。激活与 package switch 子进程继承现有 authority lease，避免 coordinator 异常退出时出现并发 owner 窗口。默认拒绝中断 active work，必须显式使用
--allow-interrupt-active-tasks。directnpx、开发安装、降级、remote Host 与 operator-managed service 均 fail closed。即使该 PR 合并，本 issue 仍需保持开启，因为“外部 npm 已先替换安装”的 reconciliation 与 released persisted-root 验证仍未完成。Generated-by: Codex
me2seeks commentedon Aug 28, 2026
Post-#3925 remaining slices
PR #3925 has merged and satisfies the explicit installed-update path. This issue remains open for two independently reviewable slices:
npx, remote Hosts, and operator-managed services.The first slice must not introduce another journal, lock, owner record, or startup-owned automatic mutation. Compatible build skew continues by default; replacement or interruption remains an explicit user decision.
简体中文
PR #3925 已合并并完成显式 installed-update 路径。本 Issue 仍保留两个可独立审查的切片：
npx、remote Host 和 operator-managed service 保持 fail closed。第一切片不得增加第二份 journal、lock、owner record，也不得在普通启动时自动修改 Host。兼容 build skew 默认继续使用；替换或中断必须由用户明确决定。
Generated-by: Codex
me2seeks commentedon Aug 28, 2026
External npm mutation reconciliation — pre-implementation design review
Proposed vertical slice
Keep the existing durable owner record and local-process handoff as the only authority and recovery journal.
When a user has already changed the npm-global slot and explicitly chooses replacement:
No npm package switch occurs: the user already performed that mutation.
The source helper is a narrow, versioned, native-free process interface shipped before the first release containing the durable installed-update owner path. If trustworthy source evidence/helper is unavailable, the existing bounded idle-only legacy takeover may still apply; active work never falls back to PID termination or inferred authority.
Simplification audit
Actionable simplification: P1 — one shared target activation/commit-guard module. This removes duplicate launch ownership and prevents a target from surviving coordinator death before durable owner commit.
No material decision gate remains. No second journal, lock, owner record, scheduler, desired-state daemon, or startup-time automatic mutation is justified.
First-principles / Occam result
Three short-lived roles are irreducible across an epoch change:
They exchange only bounded process results and inherit the same authority lease. Durable truth remains the existing owner record; crash retry re-observes the Host, writer, installed slot, and exact staged deployments.
Required tests include compatible use-existing with no mutation, same-owner external replacement, same/cross-epoch source retirement, active-work refusal and explicit interruption, missing/tampered source helper, service/remote/npx exclusion, npm slot changing again during reconciliation, coordinator/source-helper/activator death, target-already-present retry, and at-most-one writer.
Pre-implementation verdict: GO.
简体中文
实现前双重审查结论：GO。
方案只复用现有 durable owner record、CAS handoff、authority lease 与 State Root writer fence。用户已在外部改变 npm-global slot 后，只有在明确选择替换时才执行：先固化当前 installed release 对应的精确 target；把 durable selected deployment 作为唯一旧 release 证据；在同一 owner transaction 内，由 verified old package 的小型 native-free helper 负责跨 epoch 退休旧 Host；确认 writer 释放后，复用 #3925 的 target activator/commit guard 启动和验证 target；最后重新确认 npm-global slot 未再次变化并提交 owner。不会再次执行 npm install。
Simplify audit 的唯一 P1 是：抽出并共享 #3925 的 target activation/commit guard，删除 TUI Restart 当前较弱的直接 target launch。Managed remote/service authority 与本地 npm owner 不合并；legacy idle takeover 暂时保留给缺少可信 helper 的已发布旧 Host，但 active work 绝不退化为 PID 强杀。
不新增第二份 journal、lock、owner record、scheduler 或启动时自动 mutation。目前无需新的产品决策。
Generated-by: Codex
me2seeks commentedon Aug 28, 2026
Mainline implementation is now Ready for review in #4069.
It covers the externally replaced npm-global case after #3925: exact durable source-package retirement across compatibility epochs, shared guarded target activation, active-work preservation, crash-recoverable handoff, final npm-slot fencing, and the pre-helper idle-only fallback. The pre- and post-implementation dual audits are recorded in this issue and on the PR.
Still outside this slice: remote/operator-managed updates, npx temporary semantics, scheduler policy, presentation copy, and persisted State Root qualification.
中文进度
主线实现已进入 #4069 并转为 Ready。该切片处理 npm 全局安装已被用户外部替换、旧 Host 仍运行的情况；不同 epoch 由精确旧包 helper 负责退休，目标由共享 activator 守护到 Ready 后提交。远程 Host、npx、调度周期、文案和持久化 State Root qualification 不在本 PR。
me2seeks commentedon Aug 28, 2026
Released persisted-State-Root qualification — evidence gate
Source and release inspection establishes the current evidence boundary:
maka-agent-0.1.0-beta.1.tgz, release digestsha256:9daa78ced074d00a32fad4d179cb0aa37d6c431bf4b53e188446c14cf29a6ae2, compatibility epoch 24;mainis compatibility epoch 59, but it is not a published CLI artifact;Qualification matrix
The next evidence slice should consume immutable release tarballs and digests, create one golden State Root only through the source artifact, clone it per scenario, and run each artifact through its own package closure. It should report separately:
Dual-audit verdict
This remains part of #3243; no duplicate issue is required.
中文说明
当前唯一公开 CLI 包是 epoch 24 的
0.1.0-beta.1，它早于 durable owner 与旧包 retirement helper；当前 main 已到 epoch 59，但还不是发布物，也没有两份同 epoch 的已发布 CLI。因此现在只能如实验证：旧版本存在 durable residency 时必须阻断、idle 的历史 State Root 可由精确 release candidate 打开、失败不虚假声称 rollback。等包含 #4069 的版本发布后，才能补“两份真实发布物之间”的 active-work 与跨 epoch 完整验证；同 epoch 也必须等真实发布物对出现。不会用源码 build 冒充 release，也不会为了测试新增 production protocol、第二套 journal 或二进制 root fixture。me2seeks commentedon Aug 31, 2026
Released persisted-State-Root qualification — refreshed implementation plan
Registry evidence has changed since the previous gate: immutable public nightlies now provide both a cross-epoch pair (
dev.3, epoch 74 →dev.4, epoch 76) and a same-epoch pair (dev.4→dev.5, epoch 76). The implementation can therefore deliver a repeatable published-artifact matrix now, while keeping the final #4069 external-reconciliation claim gated on a later artifact that actually contains merged #4069.Vertical slice
Add a Linux release-qualification harness that:
The harness runs inside an isolated OS-account home using Bubblewrap so durable local authority and State Root control data cannot touch the developer or CI runner account state.
Pre-implementation dual audit
Evidence limits
中文说明
registry 现在已有真实 nightly：
dev.3epoch 74 →dev.4epoch 76 可验证跨 epoch，dev.4→dev.5epoch 76 可验证同 epoch。实现采用外部黑盒 qualification harness：用精确 SHA-256 固定 tarball，由 source 发布包自身创建 Session、消息和 Scheduled Task，先自读，再从未改动 golden root 恢复场景；验证并发 target 无法获得 writer，随后让 target 发布包自己的 Runtime Host 启动到 Ready，并由 target closure 读取完全相同的持久事实。实现前双重审查为 GO。不会新增 production protocol、migration API、owner、journal、lock、scheduler 或 rollback 声明。Linux 首先使用 Bubblewrap 隔离 OS-account home；其他平台以及“包含已合并 #4069 的真实发布物”仍是后续证据 gate。
Generated-by: Codex
me2seeks commentedon Aug 31, 2026
Released persisted-State-Root qualification is Ready
PR #4313 implements the reviewed evidence slice.
It pins exact public tarballs and digests, creates Session/message/ScheduledTask facts through the source artifact, proves source self-reopen and the real writer fence, starts the target artifact's Runtime Host to Ready, and compares the complete durable facts. CI covers a public cross-epoch pair, a public same-epoch pair, and the latest public nightly to the current immutable release candidate.
Pre- and post-implementation correctness/lifecycle and architecture/ownership audits are GO. The change adds no production protocol, owner, journal, lock, scheduler, migration API, or rollback authority. Local full build, release policy 140/140, Node 24 policy/unit 12/12, and all three real artifact scenarios passed.
This does not claim downgrade, external npm-reconciliation transaction E2E, or non-Linux qualification. #3243 should remain open until #4313 merges and hosted evidence is reviewed.
中文进度
#4313 已 Ready：用真实发布 tarball 由 source 创建 Session、消息和 Scheduled Task，验证 source 自读、单 writer fence、target Host Ready 以及完整持久事实不变。公开同 epoch、跨 epoch，以及最新 nightly 到当前 immutable candidate 三组本地均通过。实现前后双重审查为 GO；没有新增 production authority、journal、lock、protocol 或 rollback 声明。#3243 在 PR 合并和 hosted evidence 复核前继续保持开启。
Generated-by: Codex