Skip to content

feat(cli): reconcile externally replaced npm Runtime Hosts - #4069

Open
me2seeks wants to merge 4 commits into
apache:mainfrom
me2seeks:feat/cli-external-runtime-host-reconciliation
Open

feat(cli): reconcile externally replaced npm Runtime Hosts#4069
me2seeks wants to merge 4 commits into
apache:mainfrom
me2seeks:feat/cli-external-runtime-host-reconciliation

Conversation

@me2seeks

@me2seeks me2seeks commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Summary

  • reuse the installed-update target activator as the single Ready/durable-settlement guard
  • let the exact durable source package retire its own compatible ephemeral Runtime Host
  • reconcile an externally replaced npm-global installation through the existing owner handoff transaction
  • retain a bounded idle-only fallback for releases that predate the source retirement helper
  • explicitly scope external reconciliation to the same durable npm-global installation owner

The installed npm slot is already changed in this flow, so this PR does not run npm, add an update scheduler, or introduce another owner, journal, or lock. Cross-owner transfer, remote Hosts, and managed service Hosts remain under their respective owner/operator paths.

Safety invariants

  • stage and verify the exact installed registry target before authority mutation
  • open the exact durable selected source from the same owner local package store; do not reconstruct historical evidence from the registry
  • reject a different durable source owner before registry resolution, staging, or Host observation
  • fence retirement by State Root, confirmed Host epoch, lifecycle mode, and the inherited owner-authority lease
  • preserve active work by default and commit ownership only after exact target Ready evidence
  • make the activator read the durable owner record as the sole release-versus-retire verdict; coordinator success, failure, and disconnect are only settlement triggers
  • retain the launch barrier and authority lease while durable record reads are uncertain
  • revalidate the npm slot before owner commit and reject external downgrades before staging or retirement

Validation

  • npm run build --prefix packages/cli
  • CLI full suite: 617/617
  • focused Runtime Host update/reconciliation suite: 42/42
  • release file and artifact policy suite: 15/15
  • scoped Biome and git diff --check

Refs #3243
Refs #3231

中文说明

本 PR 处理同一 durable npm-global installation owner 已被用户通过 npm 外部替换、但旧 Runtime Host 仍在运行的情况。不同 owner 的转移不属于本切片,会在解析 registry、stage 或观察 Host 前 typed 拒绝。

新 CLI 不直接假装兼容旧 Host,而是从持久化部署中启动旧版本自己的 retirement helper;旧版本负责按自己的协议安全退休旧 Host,新版本再通过共享 activator 启动并验证精确目标。父 coordinator 的成功、失败或断线都不再决定 target 的关闭与保留;activator 统一读取 durable owner record 后裁决。读取不确定时保留 barrier 与 authority lease,读到 exact committed 才 release,否则才 retire。

不在本 PR 范围内:跨 owner transfer、远程 Host、systemd 等托管 Host、npx 临时运行语义、自动检查周期与 TUI 文案。

@me2seeks

Copy link
Copy Markdown
Contributor Author

Post-implementation dual audit — GO

First-principles correctness

  • Authority stays singular: the existing owner record, handoff transaction, writer fence, and inherited lease remain the only durable coordination mechanism.
  • User intent stays explicit: this path runs only after the local restart choice; it does not turn external npm mutation into automatic Host interruption.
  • Compatibility is owned by the source: the exact durable old package speaks to and retires its own Host, including a different protocol/compatibility epoch.
  • Process identity is fenced twice: the coordinator re-observes under the authority transaction, and the source helper requires the exact State Root and confirmed Host epoch.
  • A Host that changes after confirmation is not retired. Active work rolls the handoff back; failures after retirement begins retain the handoff for recovery; target ownership commits only after exact Ready evidence and a final npm-slot check.
  • Managed service and remote Hosts remain under their operators. Downgrades fail before staging or retirement.

Simplification / deletion proof

  • Reused the feat(cli): coordinate npm-global Runtime Host updates #3925 target activator and removed the weaker direct TUI launch path.
  • Deleted the proposed old-version registry reacquisition: a durable selected deployment must open and validate its exact local package store; missing evidence fails closed.
  • Added no scheduler, journal, lock, owner record, forwarding API, or parallel recovery state.
  • The three participating processes are irreducible at an epoch boundary: current coordinator owns the transaction, exact source helper owns old-wire compatibility, exact target activator owns Ready/commit guarding. Only the existing owner record is durable.

Validation at 6eeb7eb7ba789c02da1b48a47b2c495dd4cbadea: CLI full suite 614/614, focused lifecycle suite 35/35, release policy suite 15/15, CLI build, scoped Biome, and diff-check all pass. Hosted checks are currently queued, so this verdict does not pre-claim CI success.

中文审计结论

结论:GO。实现仍只有一份 owner/handoff/lease authority。旧版本通过其自身 helper 兼容不同 epoch,新版本通过共享 activator 等待精确 Ready 后才提交;用户确认后的 Host 若已经换了 epoch,不会被误关闭。活跃工作会回滚,退休开始后的故障保留 handoff 供恢复。实现还删除了重新联网下载旧版本的路径,直接验证持久化的精确旧包;没有新增 scheduler、journal、lock 或第二份恢复状态。远程与托管 Host 仍由各自 operator 更新。

@me2seeks
me2seeks force-pushed the feat/cli-external-runtime-host-reconciliation branch from fdc4364 to 4b3368e Compare August 28, 2026 09:50
@me2seeks

Copy link
Copy Markdown
Contributor Author

Maintainer findings independently confirmed and fixed at 4b3368e46.

  1. Ambiguous durable settlement: removed the parent committed / abort verdict. Every parent outcome now sends only one settlement trigger. The activator reads the durable owner record and is the sole release-versus-retire authority. An exact committed record releases the launch barrier; a readable non-committed record retires the guarded target; read failure retains the barrier and inherited authority lease and retries. Coordinator disconnect uses the same path. This closes both commit-before-ack retirement and committed-on-disconnect barrier leaks.
  2. Source owner contract: this slice is now explicitly same-owner npm-global replacement. A durable owner / handoff from that differs from the resolved npm-global installation returns typed source_owner_mismatch before registry resolution, staging, package-store lookup, or Host observation. Cross-owner transfer remains with its owner-specific adapter.

Regression coverage includes an injected authority read failure followed by exact committed ownership (release, never retire), readable uncommitted handoff retirement, uncertain coordinator commit settlement, and Desktop-to-CLI owner mismatch with no staging or Host observation.

Validation: CLI build; focused 42/42; full CLI 617/617; release policy 15/15; scoped Biome and diff-check.

中文修复说明

两条结论均确认属实并已修复。父进程不再发送 committed/abort 裁决,只触发结算;activator 统一读取 durable record 决定 release 或 retire,读取不确定时继续持有 barrier/lease。外部 npm reconciliation 明确只支持同一 durable npm-global owner;跨 owner 在任何 registry、stage、store 或 Host 操作前返回 typed 拒绝。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/XL Over 1000 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant