Repository navigation
feat(cli): add safe manual updates for managed Runtime Hosts #3579
Description
English
Problem
Maka can install and manage a persistent remote Runtime Host, and #3557 adds the explicit retirement contract required to release its State Root writer. It still cannot safely replace that managed service with the exact package shipped or selected by an operator.
Re-running setup is not an update contract: it does not give the operator a complete stage, retirement, service cutover, replacement verification, and truthful recovery result.
Scope
- add one machine-readable CLI transaction for an exact-package update;
- validate and stage the target package beside the active deployment;
- report the current and target release identities before changing the service;
- consume the exact-Host retirement contract from [Tracking] Runtime Host maintenance and single-writer retirement #3231;
- switch the service and verify that the replacement is ready against the expected State Root and is running the target version;
- never restart the previous package after a target may have opened the State Root, because rollback safety is then unknown;
- expose the same operation through the Desktop per-Host management surface over SSH.
Boundaries
- Runtime Host owns retirement and the State Root writer; it does not install its own package or switch its service.
- The CLI service-management plane owns artifact staging and deployment recovery.
- Desktop installs the exact CLI package selected for that Desktop build; channel policy and automatic reconciliation remain follow-up work in [Tracking] Managed remote Runtime Host onboarding and lifecycle #3228.
- Preflight compatibility policy across independently versioned Clients and Hosts remains in discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204. This transaction proves success by replacement readiness instead of inventing an incomplete compatibility claim.
Done when
- a Linux managed Host can be manually aligned with an exact package from Desktop or the machine-readable CLI contract;
- active work is never interrupted without explicit operator authority;
- success proves that the replacement service is ready against the expected State Root and is running the selected version;
- interruption or failure gives a safe recovery action without claiming an unsafe rollback.
简体中文
问题
Maka 已能安装和管理持久 remote Runtime Host，#3557 也增加了释放 State Root writer 所需的显式 retirement contract，但 onboarding 后仍不能把 managed service 安全替换为 operator 指定或 Desktop 随附的精确 package。
重新执行 setup 不是更新契约：它没有完整定义 stage、退场、service cutover、replacement 验证与真实的失败恢复结果。
范围
- 增加一套面向精确 package 更新的 machine-readable CLI transaction；
- 在 active deployment 旁验证并 stage 目标 package；
- 修改 service 前报告当前与目标 release identity；
- 消费 [Tracking] Runtime Host maintenance and single-writer retirement #3231 的 exact-Host retirement contract；
- 切换 service，并验证 replacement 已针对预期 State Root ready 且实际运行目标版本；
- 目标 package 一旦可能打开过 State Root，就绝不自动重启旧 package，因为此时无法证明 rollback 安全；
- 通过 SSH 在 Desktop 的 per-Host 管理界面提供同一操作。
边界
- Runtime Host 只拥有 retirement 与 State Root writer，不安装自己的 package，也不切换 service；
- CLI service-management plane 拥有 artifact staging 与 deployment recovery；
- Desktop 安装其构建版本所选择的精确 CLI package；channel policy 与 automatic reconciliation 仍属于 [Tracking] Managed remote Runtime Host onboarding and lifecycle #3228 的后续工作；
- 独立版本 Client 与 Host 之间的 preflight compatibility policy 仍由 discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204 跟踪。本事务以 replacement readiness 证明成功，不虚构不完整的 compatibility 结论。
完成标准
- Linux managed Host 可以从 Desktop 或 machine-readable CLI contract 手动对齐到精确 package；
- 未经 operator 明确授权绝不中断 active work；
- 成功结果能证明 replacement service 已针对预期 State Root ready，且实际运行所选版本；
- 中断或失败时给出安全恢复动作，不虚假声称完成了不安全的 rollback。
Activity