Repository navigation
[Tracking] Runtime Host maintenance and single-writer retirement #3231
Description
English
Goal
Track the explicit maintenance and single-writer retirement contract shared by local and managed Runtime Hosts.
When an installation owner or remote operator authorizes a full quit or replacement, the current Host must stop admitting work, preserve durable intent, settle or explicitly interrupt execution, release the sole State Root writer, and report a truthful result. Package deployment, service switching, and replacement verification remain outside the Runtime Host Domain authority.
Current behavior
Current
- One Runtime Host owns one State Root's writer lease and durable-work authority.
- Surface disconnection does not imply Host retirement. Durable Goals or Scheduled Tasks may intentionally keep the Host resident.
- Desktop already has a compatible local update handoff through
host.upgrade.prepare, but ordinary Desktop quit does not guarantee retirement when durable residency remains. - After a
compatibilityEpochmismatch, the new Client is rejected before Domain admission. The current UI can wait or cancel, but waiting cannot converge while recurring residency remains. - Managed remote Hosts are operator-owned services. An ordinary Runtime Host Client credential does not authorize package installation, service replacement, or restart.
- Managed Host retirement now binds the exact Host, service generation, and State Root writer before stopping the service (feat(runtime-host): add managed Host retirement #3557, fix(runtime-host): bind managed retirement to one service generation #3600, fix(runtime-host): fence State Root before service retirement #3602). The exact-package replacement transaction consumes that result and verifies the replacement without claiming an unsafe rollback (feat(runtime-host): add safe managed Host updates #3591).
The Windows epoch 24 to epoch 25 reproduction and screenshot are recorded in this comment.
Lifecycle intents
The product and protocol must distinguish three intents:
- Disconnect Surface — release Client-owned resources; Host-owned durable work may continue.
- Quit/stop Maka — explicit maintenance authorization; retire the owned local Host without immediately starting a replacement.
- Update/replace Host — stage the candidate first, retire the current Host, then let the installation owner start and verify the replacement.
Closing one TUI or Desktop Surface must never stop a shared managed remote Host. Updating a managed remote Host is a separate, explicit operator action.
Ownership boundaries
- discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204 owns Client–Host compatibility, version skew, contract revision, and capability negotiation.
- This issue owns the small Host retirement contract and semantic recovery expectations.
- [Tracking] Managed remote Runtime Host onboarding and lifecycle #3228 owns managed remote deployment and product orchestration over the SSH/service-management plane; it consumes the retirement result defined here.
- feat(cli): manage Linux Runtime Host services #3205 and feat(cli): set up managed remote Runtime Hosts #3230 provide managed service and idempotent setup foundations. They do not define updates.
- fix(cli): diagnose residency-blocked local Runtime Host version conflicts #3207 / fix(cli): explain residency-blocked host conflicts #3208 own actionable local conflict diagnostics and wait/cancel behavior, not retirement authority.
- chore(runtime-host): ClientSurface is a required handshake field with zero readers #3216 is a concrete tolerant wire-evolution input to discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204.
- fix(storage): retire completed legacy migration metadata #3227 is active storage-transition evidence. It does not by itself prove that every upgrade or rollback is safe.
- feat(desktop): add managed remote Runtime Host onboarding over SSH #3233 owns Desktop managed-remote onboarding, not Host replacement.
- feat(cli): coordinate local Runtime Host handoff across npm upgrades #3243 owns installed CLI/npm update coordination and local installation handoff.
- discussion(cli): define durable Runtime Host ownership for npx launches #3244 decides whether and how a transient
npxinvocation may own durable local Host execution. - feat(tui): add explicit local Runtime Host lifecycle and upgrade-conflict actions #3245 owns TUI lifecycle presentation and user actions; it remains an adapter over this retirement contract.
Current delivery coordination
Delivered
- bug(desktop): explicit Quit Maka leaves the local Runtime Host holding the State Root writer #3703 was the urgent explicit-Desktop-Quit bug. PR fix(desktop): retire the owned local Host on full quit #3706 has merged its exact authenticated retirement path for the Desktop-owned local ephemeral Host.
- PRs feat(runtime-host): apply verified managed updates #3687 and feat(runtime-host): add managed update reconciliation #3720 have merged the verified exact-package update transaction, managed update policy, and bounded one-shot reconciliation for [Tracking] Managed remote Runtime Host onboarding and lifecycle #3228. They do not establish a durable local owner.
- PR feat(runtime-host): schedule managed update reconciliation #3747 has merged periodic managed-update scheduling by reusing the one-shot reconciliation entry point.
- PR refactor(runtime-host): share verified deployment identity #3766 has merged the shared verified npm exact-deployment identity.
- PR feat(runtime-host): add durable local deployment ownership #3767 has merged the durable local owner record and explicit transfer authority; it deliberately adds no Host retirement, successor launch, or Surface/operator adapter.
- PR feat(runtime-host): coordinate local owner transfer #3769 has merged the serialized local-process owner-transfer transaction: stage the exact target, persist intent, retire/re-observe the Host, observe writer release, activate and verify Ready, then commit.
In-flight
- architecture(runtime-host): converge local Host lifecycle through owner-scoped reconciliation #3709 owns the target architecture and convergence sequence. Draft PR feat(cli): reconcile local Runtime Host generations #3254 remains paused as generation/epoch UX and released-Host takeover evidence rather than the target owner architecture.
- Merged PR refactor(runtime-host): unify local deployment handoffs #3813 deepens the merged transaction into one local deployment handoff for both owner-preserving replacement and cross-owner transfer, while removing the uncoordinated direct selection path.
- Merged PR feat(cli): resolve persistent Runtime Host installation facts #3816 resolves the stable npm-global CLI owner and a truthful mutable installed-release observation without inventing verified local artifact identity; it is merge-order independent from refactor(runtime-host): unify local deployment handoffs #3813.
- Ready PR feat(cli): reconcile exact local Runtime Host restarts #3920 connects those foundations to a shipped TUI Restart path: exact registry staging, initial claim or existing-owner handoff, exact legacy takeover/Ready verification, and fail-closed service/remote/npx/active-work boundaries.
Planned
After the owner foundations and local-process transaction, implementation proceeds in authority order: source-specific owner adapters and reconciliation, transient npx lifecycle, then TUI/Desktop presentation and bounded released-Host compatibility adapters.
Retirement contract
Delivered for managed replacement; remaining lifecycle adapters are still planned
A retirement request should be narrow, explicitly authorized, fenced to the exact Host identity/epoch, and idempotent. Runtime Host owns only:
- reporting authoritative activity, residency, and recovery facts;
- fencing new admission;
- persisting recoverable Domain intent;
- settling or interrupting current execution with an explicit maintenance reason;
- preserving unresolved external effects as
result_unknown; - releasing Domain resources and the sole writer lease;
- reporting structured progress and completion.
The installation-management plane owns artifact resolution and staging, service/application switching, replacement startup and verification, deployment recovery, and rollback only where storage/effect evidence proves rollback safe.
This does not require a permanent cross-version Domain bypass. The normal local update path asks the still-compatible current Host to retire before installing the incompatible replacement. Managed remote replacement uses its operator SSH/service plane.
Recovery expectations
Retirement promises semantic recovery, not byte-exact continuation:
| State | Expected behavior after retirement |
|---|---|
| Scheduled Task schedule | Remains durable and resumes scheduling when a Host runs again |
| Pending scheduled fire | Reconciles under its existing delivery guarantee |
| Goal / Automation durable intent | Recovers under its durable contract |
| Pending Interaction or in-flight Turn | Resumes only from a supported durable checkpoint; otherwise becomes explicitly interrupted/cancelled |
| External tool effect | Remains result_unknown when its result cannot be proven |
| Client capabilities and presentation state | Re-published or restored by the reconnecting Surface; not Host recovery state |
Delivery tracker
- Compatible local Desktop update handoff exists
- Managed Linux service lifecycle (feat(cli): manage Linux Runtime Host services #3205)
- Idempotent managed remote setup (feat(cli): set up managed remote Runtime Hosts #3230)
- Define retirement request/result, authorization, exact-Host fencing, and idempotency for managed replacement (feat(runtime-host): add managed Host retirement #3557, fix(runtime-host): bind managed retirement to one service generation #3600, fix(runtime-host): fence State Root before service retirement #3602)
- Define the recovery matrix for Scheduled Tasks, Goals, Automations, Interactions, Turns, and external effects
- Distinguish Desktop window close from explicit Quit Maka (bug(desktop): explicit Quit Maka leaves the local Runtime Host holding the State Root writer #3703; delivered by PR fix(desktop): retire the owned local Host on full quit #3706)
- Share the verified npm exact-deployment identity for local owner work (refactor(runtime-host): share verified deployment identity #3766)
- Establish one durable local owner record and explicit transfer authority (feat(runtime-host): add durable local deployment ownership #3767)
- Coordinate local-process retirement, writer release, target Ready verification, and crash recovery under the owner transaction (feat(runtime-host): coordinate local owner transfer #3769)
- Converge local Desktop/CLI/TUI lifecycle through the owner-scoped architecture and gates in architecture(runtime-host): converge local Host lifecycle through owner-scoped reconciliation #3709
- Complete local Desktop staged update/restart behavior for active durable residency
- Coordinate installed CLI/npm update and local installation handoff (feat(cli): coordinate local Runtime Host handoff across npm upgrades #3243)
- Decide durable Runtime Host ownership for transient
npxlaunches (discussion(cli): define durable Runtime Host ownership for npx launches #3244) - Keep TUI
/exitas Surface disconnect; add explicit stop/restart UX and precise epoch-conflict operator guidance (feat(tui): add explicit local Runtime Host lifecycle and upgrade-conflict actions #3245) - Make managed remote version switching in [Tracking] Managed remote Runtime Host onboarding and lifecycle #3228 consume this retirement contract (feat(runtime-host): add safe managed Host updates #3591)
- Define storage preflight and truthful rollback classification using fix(storage): retire completed legacy migration metadata #3227 as evidence
- Qualify released-version transitions with real persisted State Roots, including epoch 24 to 25
Unchecked items are planned tracking slices, not claims about current behavior.
Definition of done
- Surface disconnect, full quit, and update have distinct, truthful semantics.
- Explicit maintenance can retire a resident owned Host without waiting forever for recurring durable residency.
- No path admits an incompatible Domain command or starts two writers for one State Root.
- Durable intent and unresolved external-effect uncertainty survive retirement according to documented contracts.
- Managed remote replacement requires explicit operator authority and does not reuse an ordinary Client credential as deployment authority.
- Released-version tests cover supported skew and real storage transitions.
Non-goals
- A universal Runtime Host-owned package/deployment state machine
- Two active Runtime Host revisions writing one State Root
- Silent remote Host updates
- Treating every product-version difference as incompatibility
- Promising rollback across irreversible storage migrations
- Byte-exact continuation of arbitrary in-flight execution
简体中文
目标
跟踪本地与 managed Runtime Host 共享的“明确维护授权 + 单写者安全退场”契约。
当本地 installation owner 或 remote operator 明确授权完全退出或替换时,当前 Host 必须停止准入新工作、保存 durable intent、收敛或明确中断执行、释放唯一 State Root writer,并报告真实结果。Package 部署、service 切换和 replacement 验证不属于 Runtime Host Domain authority。
当前行为
Current
- 一个 Runtime Host 拥有一个 State Root 的 writer lease 与 durable-work authority。
- Surface 断开不等于 Host 退场;durable Goal 或 Scheduled Task 可以有意让 Host 保持运行。
- Desktop 已有兼容版本下的本地
host.upgrade.preparehandoff,但普通 Quit 在存在 durable residency 时不能保证 Host 退出。 compatibilityEpoch不同时,新 Client 会在 Domain 准入前被拒绝。当前 UI 可以等待或取消,但 recurring residency 一直存在时,等待不会自然完成。- Managed remote Host 是 operator 管理的 service;普通 Runtime Host Client credential 不授权安装 package、替换 service 或重启。
- Managed Host retirement 现在会在停止 service 前绑定精确 Host、service generation 与 State Root writer(feat(runtime-host): add managed Host retirement #3557、fix(runtime-host): bind managed retirement to one service generation #3600、fix(runtime-host): fence State Root before service retirement #3602);精确 package replacement transaction 会消费该结果并验证 replacement,且不会虚假声称完成不安全的 rollback(feat(runtime-host): add safe managed Host updates #3591)。
Windows epoch 24 到 epoch 25 的真实复现与截图见这条评论。
三种生命周期意图
产品和协议必须区分:
- 断开 Surface:释放 Client-owned resource;Host-owned durable work 可以继续。
- 退出/停止 Maka:明确维护授权;让所拥有的本地 Host 退场,但不立即启动 replacement。
- 更新/替换 Host:先 stage candidate,再让当前 Host 退场,最后由 installation owner 启动并验证 replacement。
关闭一个 TUI 或 Desktop Surface 绝不能停止共享的 managed remote Host。更新 managed remote Host 必须是独立、明确的 operator action。
职责边界
- discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204:Client–Host compatibility、version skew、contract revision 与 capability negotiation。
- 本 Issue:小型 Host retirement contract 与语义恢复预期。
- [Tracking] Managed remote Runtime Host onboarding and lifecycle #3228:通过 SSH/service-management plane 完成 managed remote 部署与产品编排,并消费本 Issue 的 retirement result。
- feat(cli): manage Linux Runtime Host services #3205 与 feat(cli): set up managed remote Runtime Hosts #3230:managed service 和幂等 setup 基础,不定义更新。
- fix(cli): diagnose residency-blocked local Runtime Host version conflicts #3207 / fix(cli): explain residency-blocked host conflicts #3208:本地冲突诊断与 wait/cancel 行为,不拥有 retirement authority。
- chore(runtime-host): ClientSurface is a required handshake field with zero readers #3216:提供给 discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204 的 tolerant wire-evolution 实例。
- fix(storage): retire completed legacy migration metadata #3227:仍在进行的 storage-transition 证据,不代表所有升级或回退已经安全。
- feat(desktop): add managed remote Runtime Host onboarding over SSH #3233:Desktop managed-remote onboarding,不负责 Host replacement。
- feat(cli): coordinate local Runtime Host handoff across npm upgrades #3243:installed CLI/npm 更新协调与本地 installation handoff。
- discussion(cli): define durable Runtime Host ownership for npx launches #3244:决定临时
npxinvocation 是否以及如何拥有 durable local Host execution。 - feat(tui): add explicit local Runtime Host lifecycle and upgrade-conflict actions #3245:TUI lifecycle 展示与用户操作;它只是本 retirement contract 的 adapter。
当前交付协调
Delivered
- bug(desktop): explicit Quit Maka leaves the local Runtime Host holding the State Root writer #3703 是紧急的 Desktop 明确退出缺陷。PR fix(desktop): retire the owned local Host on full quit #3706 已合并,为 Desktop-owned local ephemeral Host 交付了绑定精确认证身份的 retirement 路径。
- PR feat(runtime-host): apply verified managed updates #3687 与 feat(runtime-host): add managed update reconciliation #3720 已为 [Tracking] Managed remote Runtime Host onboarding and lifecycle #3228 合并 verified exact-package update transaction、managed update policy 与 bounded one-shot reconciliation;它们不建立 durable local owner。
- PR feat(runtime-host): schedule managed update reconciliation #3747 已通过复用 one-shot reconciliation entry point 合并周期性 managed-update scheduling。
- PR refactor(runtime-host): share verified deployment identity #3766 已合并共享的 verified npm exact-deployment identity。
- PR feat(runtime-host): add durable local deployment ownership #3767 已合并 durable local owner record 与显式 transfer authority;它有意不包含 Host retirement、successor launch 或 Surface/operator adapter。
- PR feat(runtime-host): coordinate local owner transfer #3769 已合并串行化的 local-process owner-transfer transaction:stage 精确 target、持久化 intent、retire/重新观察 Host、观察 writer 释放、启动并验证 Ready,最后 commit。
In-flight
- architecture(runtime-host): converge local Host lifecycle through owner-scoped reconciliation #3709 负责目标架构与收敛顺序。Draft PR feat(cli): reconcile local Runtime Host generations #3254 继续暂停,只保留 generation/epoch UX 与已发布 Host takeover 证据,不视为目标 owner 架构。
- Merged PR refactor(runtime-host): unify local deployment handoffs #3813 把已合并事务深化为一条同时支持 owner-preserving replacement 与跨 owner transfer 的 local deployment handoff,并删除不受协调的直接 selection 路径。
- Merged PR feat(cli): resolve persistent Runtime Host installation facts #3816 解析稳定的 npm-global CLI owner 与真实但可变的 installed-release observation,不虚构已验证的本地 artifact identity;它与 refactor(runtime-host): unify local deployment handoffs #3813 的 merge 顺序独立。
- Ready PR feat(cli): reconcile exact local Runtime Host restarts #3920 已把这些基础接入实际 TUI Restart 路径:精确 registry staging、initial claim 或 existing-owner handoff、exact legacy takeover/Ready 验证,以及对 service、remote、npx 与 active work 的 fail-closed 边界。
Planned
Owner 基础与 local-process transaction 之后,继续按 authority 顺序实现 source-specific owner adapter 与 reconciliation、临时 npx lifecycle,最后才是 TUI/Desktop presentation 与有界的 released-Host compatibility adapter。
Retirement contract
Managed replacement 已交付;其余 lifecycle adapter 仍在规划中
Retirement request 应保持窄小、得到明确授权、绑定精确 Host identity/epoch,并且幂等。Runtime Host 只负责:
- 报告权威的 activity、residency 与 recovery facts;
- fence 新 admission;
- 持久化可恢复的 Domain intent;
- 以明确 maintenance reason 收敛或中断当前 execution;
- 将无法确认的外部 effect 保留为
result_unknown; - 释放 Domain resource 与唯一 writer lease;
- 报告结构化进度与完成结果。
Installation-management plane 负责 artifact 解析与 staging、service/application 切换、replacement 启动与验证、deployment recovery,以及仅在 storage/effect 证据证明安全时执行 rollback。
这不要求建立永久的跨版本 Domain bypass。正常本地更新应由仍然兼容的当前 Client 先请求当前 Host 退场,再安装不兼容的 replacement;managed remote replacement 使用 operator 的 SSH/service plane。
恢复预期
Retirement 承诺的是语义恢复,不是逐字节续跑:
| 状态 | 退场后的预期行为 |
|---|---|
| Scheduled Task schedule | 保持 durable,并在 Host 再次运行后恢复调度 |
| Pending scheduled fire | 按现有 delivery guarantee reconciliation |
| Goal / Automation durable intent | 按其 durable contract 恢复 |
| Pending Interaction 或 in-flight Turn | 仅从受支持的 durable checkpoint 恢复,否则明确 interrupted/cancelled |
| 外部 tool effect | 结果无法证明时保持 result_unknown |
| Client capability 与 presentation state | 由重连 Surface 重新发布或恢复,不属于 Host recovery state |
交付追踪
- 已有兼容版本下的本地 Desktop update handoff
- Managed Linux service lifecycle(feat(cli): manage Linux Runtime Host services #3205)
- 幂等 managed remote setup(feat(cli): set up managed remote Runtime Hosts #3230)
- 为 managed replacement 定义 retirement request/result、授权、精确 Host fencing 与幂等性(feat(runtime-host): add managed Host retirement #3557、fix(runtime-host): bind managed retirement to one service generation #3600、fix(runtime-host): fence State Root before service retirement #3602)
- 定义 Scheduled Task、Goal、Automation、Interaction、Turn 与外部 effect 的恢复矩阵
- 区分 Desktop 关闭窗口与明确的退出 Maka(bug(desktop): explicit Quit Maka leaves the local Runtime Host holding the State Root writer #3703;已由 PR fix(desktop): retire the owned local Host on full quit #3706 交付)
- 为 local owner 工作共享 verified npm exact-deployment identity(refactor(runtime-host): share verified deployment identity #3766)
- 建立一份 durable local owner record 与显式 transfer authority(feat(runtime-host): add durable local deployment ownership #3767)
- 在 owner transaction 下协调 local-process retirement、writer 释放、target Ready 验证与 crash recovery(feat(runtime-host): coordinate local owner transfer #3769)
- 按 architecture(runtime-host): converge local Host lifecycle through owner-scoped reconciliation #3709 的 owner-scoped 架构与 gate 收敛本地 Desktop/CLI/TUI lifecycle
- 补全 active durable residency 下的本地 Desktop staged update/restart
- 协调 installed CLI/npm 更新与本地 installation handoff(feat(cli): coordinate local Runtime Host handoff across npm upgrades #3243)
- 决定临时
npxlaunch 的 durable Runtime Host ownership(discussion(cli): define durable Runtime Host ownership for npx launches #3244) - 保持 TUI
/exit为 Surface disconnect;增加显式 stop/restart UX 与精确 epoch-conflict operator 指引(feat(tui): add explicit local Runtime Host lifecycle and upgrade-conflict actions #3245) - 让 [Tracking] Managed remote Runtime Host onboarding and lifecycle #3228 的 managed remote 版本切换消费本 retirement contract(feat(runtime-host): add safe managed Host updates #3591)
- 结合 fix(storage): retire completed legacy migration metadata #3227 定义 storage preflight 与如实 rollback classification
- 使用真实持久 State Root 验证已发布版本转换,包括 epoch 24 到 25
未勾选项目是 Planned tracking slice,不代表当前实现已经存在。
完成定义
- Surface 断开、完全退出和更新具有不同且真实的语义。
- 显式维护无需永远等待 recurring durable residency,即可让所拥有的 resident Host 安全退场。
- 任何路径都不准入不兼容 Domain command,也不会让两个 writer 同时写一个 State Root。
- Durable intent 与未解决 external-effect uncertainty 按文档契约跨 retirement 保留。
- Managed remote replacement 需要明确 operator authority,不把普通 Client credential 当作 deployment authority。
- 已发布版本测试覆盖支持的 skew 与真实 storage transition。
非目标
- Runtime Host 拥有的通用 package/deployment 状态机
- 两个 active Runtime Host revision 同时写一个 State Root
- 静默更新 remote Host
- 把所有产品版本差异都视为不兼容
- 承诺跨不可逆 storage migration 回退
- 任意 in-flight execution 的逐字节续跑
AI assistance disclosure
This tracking issue was investigated and restructured with Codex. Current behavior and the scopes and live states of the linked Issues and PRs were rechecked before conversion.
Activity
me2seeks commentedon Aug 19, 2026
#3227 provides a concrete released-State-Root example that should be included in the upgrade assessment model.
In that case, the application schemas can converge successfully while obsolete migration metadata still causes strict target-schema validation to block Host startup. This means successful Client–Host protocol negotiation does not establish that a candidate Host can safely open an existing State Root.
Upgrade assessment should therefore distinguish at least:
Released-version qualification should replay candidate startup against copies of real historical State Roots, including completed, interrupted, malformed, and unfamiliar migration metadata. If the candidate would perform an irreversible migration, the operator must see that rollback becomes unsupported before cutover.
#3227 is still under review, so it should currently be referenced as concrete evidence and an active migration case, not as proof that the storage-transition problem is fully solved.
M4n5ter commentedon Aug 19, 2026
English
I think the safety constraints in this issue are correct, but the current framing is too upgrade-state-machine-first. It risks combining compatibility, Runtime retirement, software deployment, and product UX into one large authority before the minimum contract is clear.
A better framing is:
The Runtime Host should not upgrade itself, and it should not become the owner of the complete deployment transaction.
What should remain invariant
The following constraints are important and should remain:
result_unknown;These constraints define the safety boundary. They do not require one universal durable upgrade state machine.
Three distinct lifecycle intents
The design should distinguish three user intents.
1. Surface disconnect
Closing a window, losing a connection, or disconnecting one Client does not authorize Maka to stop durable Host-owned work.
Goals, Automations, Scheduled Tasks, pending Interactions, and other Host-owned work may continue.
2. Explicit “Quit Maka” / “Stop Maka now”
An explicit full-quit action should authorize Maka to stop all activity owned by the local Host and terminate that Host.
Unlike an update, no replacement Host starts immediately. Durable Goal, Automation, and Scheduled Task state remains stored and can recover the next time Maka starts, but no background work runs while Maka is fully stopped.
This should affect only the local Host owned by that Desktop installation. Quitting Desktop must not stop a managed remote Host.
As implemented today, Electron quit cleanup closes the Desktop Runtime Host manager and its Client lifecycles, but it does not explicitly prepare and stop the local Host. An ephemeral Host may therefore remain alive when durable residency exists. The current Quit behavior is closer to a Surface shutdown than a guaranteed “Stop Maka now.”
We should decide whether the existing Quit Maka action should adopt the stronger full-stop meaning, or whether the product needs two explicit actions such as Close Window and Quit Maka. The important requirement is that the user-facing wording and the Host behavior agree.
3. Explicit update
Clicking Update should itself authorize Maka to enter maintenance, stop all current activity owned by the local Host, and replace that Host.
The user should not have to approve every Goal or Scheduled Task separately. Clicking Update is the maintenance authorization.
The distinction is therefore:
Maintenance authorization permits current execution to stop; it does not permit durable intent to be lost.
Recovery must be defined by semantic state
“Resume after restart” should not imply byte-for-byte continuation of every in-flight Turn. Recovery should be defined for each authoritative state:
result_unknownwhen the outcome cannot be provenBefore releasing the State Root writer, the Host should:
Separate Runtime retirement from deployment
There are three separate responsibilities:
The Runtime Host should own only the retirement portion:
The installation owner should own:
The OS service manager should continue to own process and service lifecycle.
This boundary prevents the Host from becoming another package manager or deployment authority.
Avoid a permanent cross-version maintenance protocol
A local update is initiated while the old Desktop and its current Host are still compatible. The normal sequence should therefore be:
We should not first install an incompatible Client and then create a second protocol that allows it to bypass the normal compatibility boundary and control the old Host.
If an interrupted update leaves an old orphan Host behind, recovery belongs to the local installation owner/updater. It can validate the process identity, State Root, and writer lease before taking action.
Managed remote replacement should likewise use its SSH/service-management plane. An ordinary Runtime Host credential should not become deployment authority.
Local and managed replacement should share only the small contract
Local Desktop updates and managed remote updates have different owners and failure boundaries.
The useful shared abstraction is a small retirement/cutover contract, not one universal deployment state machine.
Be cautious with a universal durable upgrade journal
Managed remote deployment may need durable recovery when Desktop disconnects, SSH ends, or service startup fails. That does not mean the Runtime Host Domain store should own the deployment transaction.
If a deployment record is required, it should belong to the installation-management plane and contain only facts such as:
A local application updater may already have equivalent installation state and should not be forced into the same representation merely for architectural symmetry.
How the current work can support this direction
The managed onboarding work already establishes useful foundations:
That work should not absorb the full replacement lifecycle. It only needs to preserve the right boundaries:
A future manual update can then be built as a deployment transaction around the small Host retirement contract. Automatic channel reconciliation should come only after the manual cutover and recovery semantics have been proven.
Suggested focus
I suggest narrowing this issue to:
This preserves the important safety invariants, gives explicit quit and explicit update clear semantics, and avoids prematurely introducing a large universal upgrade state machine.
简体中文
我认为这个 issue 中的安全约束是正确的,但当前视角过于以“升级状态机”为中心,容易在最小契约尚未明确前,就把兼容性、Runtime 退场、软件部署和产品 UX 合并成一个过大的 authority。
更合适的问题是:
Runtime Host 不应更新自己,也不应拥有完整的 deployment transaction。
应保留的不变量
以下约束是正确且必要的:
result_unknown;这些约束定义了安全边界,但并不要求建立一套通用的 durable upgrade state machine。
三种不同的生命周期意图
设计应区分三种用户意图。
1. Surface 断开
关闭窗口、连接中断或某个 Client 断开,不代表用户授权 Maka 停止 durable Host-owned work。
Goal、Automation、Scheduled Task、pending Interaction 和其他 Host-owned work 可以继续运行。
2. 主动“退出 Maka”/“立即停止 Maka”
明确的完整退出操作应授权 Maka 停止本地 Host 拥有的所有活动,并终止该 Host。
它与更新的区别是不会立即启动 replacement Host。Goal、Automation 和 Scheduled Task 的 durable state 仍然保留,并可在下次启动 Maka 时恢复,但 Maka 完全停止期间不会继续执行后台工作。
该行为只应影响 Desktop 安装所拥有的本地 Host。退出 Desktop 不能停止 managed remote Host。
从当前实现看,Electron 的退出清理会关闭 Desktop Runtime Host manager 及其 Client lifecycle,但不会明确 prepare 并停止本地 Host。当 durable residency 存在时,ephemeral Host 仍可能继续运行。因此,当前 Quit 行为更接近 Surface shutdown,而不是保证“立即停止 Maka”。
我们需要决定现有的退出 Maka是否应采用更强的完整停止语义,或者产品是否需要两个明确动作,例如关闭窗口与退出 Maka。关键要求是用户看到的名称必须与 Host 的真实行为一致。
3. 主动更新
用户点击更新本身就应授权 Maka 进入维护状态、停止本地 Host 拥有的所有当前活动,并替换该 Host。
无需为每个 Goal 或 Scheduled Task 分别请求确认。点击更新本身就是 maintenance authorization。
因此三者的区别是:
维护授权允许停止当前 execution,但不允许丢失 durable intent。
Recovery 应以语义状态定义
“重启后续上”不应被理解为每个 in-flight Turn 都能从原位置逐字节继续。应为每种 authority state 明确恢复语义:
result_unknown在释放 State Root writer 前,Host 应当:
将 Runtime 退场与软件部署分开
这里实际存在三个独立职责:
Runtime Host 只应拥有 retirement 部分:
installation owner 应拥有:
操作系统 service manager 继续拥有进程和 service lifecycle。
这个边界可以避免 Runtime Host 逐渐成为另一个 package manager 或 deployment authority。
避免建立永久的跨版本 maintenance protocol
本地更新是在旧 Desktop 与当前 Host 仍然兼容时发起的,因此正常顺序应为:
不应先安装一个已经不兼容的新 Client,再建立第二套协议,让它绕过正常 compatibility boundary 去控制旧 Host。
如果更新中断并留下旧的 orphan Host,恢复职责属于本地 installation owner/updater。它可以在操作前校验进程身份、State Root 和 writer lease。
managed remote replacement 同样应通过 SSH/service-management plane 完成。普通 Runtime Host credential 不应变成 deployment authority。
本地与 managed replacement 只需共享小型契约
本地 Desktop 更新与 managed remote 更新具有不同的 owner 和失败边界。
真正值得共享的是一个小型 retirement/cutover contract,而不是一套通用 deployment state machine。
谨慎引入通用 durable upgrade journal
managed remote deployment 可能需要在 Desktop 断线、SSH 结束或 service 启动失败后恢复,但这不代表 Runtime Host Domain store 应拥有 deployment transaction。
如果确实需要 deployment record,它应属于 installation-management plane,并且只保存必要事实,例如:
本地应用 updater 可能已经拥有等价的安装状态,不应仅为了架构形式统一而被迫使用同一 representation。
当前工作如何支持这个方向
当前 managed onboarding 工作已经建立了有价值的基础:
这项工作不应顺带吸收完整的 replacement lifecycle,只需保持正确边界:
未来的手动更新可以围绕这个小型 Host retirement contract 构建 deployment transaction。自动 channel reconciliation 应在手动 cutover 和 recovery 语义得到验证之后再引入。
建议的聚焦方向
我建议将这个 issue 收窄为:
这样既保留重要的安全约束,也为主动退出和主动更新提供清晰语义,并避免过早引入一套庞大的通用升级状态机。
me2seeks commentedon Aug 19, 2026
English
Agreed. I think this issue should be narrowed from a universal upgrade lifecycle to explicit maintenance authorization and single-writer Runtime Host retirement.
Reproduction evidence
This was a real Windows Desktop test against the same isolated Client Profile and State Root:
807fea450a,RUNTIME_HOST_COMPATIBILITY_EPOCH = 24;0ef1c55b5e,RUNTIME_HOST_COMPATIBILITY_EPOCH = 25;The epoch 25 Desktop detected the incompatible Host and reported its activity correctly, but because a cross-epoch conflict is not restartable through the current Client path, the UI offered only Wait and Cancel Startup. This is not locale- or platform-specific. Waiting cannot complete naturally while recurring durable residency remains.
This confirms two current gaps:
I suggest #3231 own only:
Compatibility remains with #3204, storage-transition assessment uses #3227 as evidence, and local/managed deployment remains with the installation owner and #3228.
The permanent cross-version maintenance protocol and universal deployment journal/state machine should be removed or kept explicitly exploratory unless a smaller retirement contract proves insufficient.
简体中文
同意收紧。#3231 的核心不应是一套通用升级状态机,而应是“明确维护授权下,唯一 Runtime Host 如何安全退场并释放 State Root writer”。
复现证据
这是在 Windows Desktop 上,针对同一个隔离 Client Profile 和 State Root 进行的真实测试:
807fea450a,RUNTIME_HOST_COMPATIBILITY_EPOCH = 24;0ef1c55b5e,RUNTIME_HOST_COMPATIBILITY_EPOCH = 25;epoch 25 Desktop 能正确识别不兼容 Host 并显示其活动,但当前 Client 路径不能直接重启跨 epoch 冲突,因此界面只有等待和取消启动。这与语言和操作系统无关。recurring durable residency 一直存在时,“等待”不会自然结束。
这确认了两个当前缺口:
因此 #3231 建议只负责:
兼容窗口仍由 #3204 负责;#3227 作为 storage transition 的实际证据;本地和 remote 的 artifact/service 部署继续由 installation owner 与 #3228 负责。
永久跨版本 maintenance protocol、通用 deployment journal 和完整升级状态机应删除,或继续明确标记为 Exploratory。
[-]discussion(runtime-host): define safe local and managed remote Host upgrade orchestration[/-][+]discussion(runtime-host): define explicit maintenance and single-writer Host retirement[/+][-]discussion(runtime-host): define explicit maintenance and single-writer Host retirement[/-][+][Tracking] Runtime Host maintenance and single-writer retirement[/+]me2seeks commentedon Aug 19, 2026
I'd like to take the TUI slice tracked here.
Proposed scope:
/exitas disconnect this Surface, so closing one TUI does not stop Host-owned durable work or a shared managed remote Host;The TUI slice will not deploy or silently update a remote Host, will not use an ordinary Runtime Host credential as service authority, and will consume the small retirement contract defined by this tracker.
我来负责这里的 TUI 切片。范围是:保留
/exit的“只断开当前 Surface”语义;为本地 installation owner 增加明确的 Host stop/restart 路径;epoch 冲突时展示精确 Host 信息并引导用户执行正确的本地或 remote operator 操作;在 #3208 的诊断与 wait/cancel 基础上继续实现并补测试。TUI 不负责部署或静默更新 remote Host,也不会把普通 Runtime Host credential 当成 service authority。Astro-Han commentedon Aug 24, 2026
Repro on macOS (local Host, not managed): quitting Desktop via window close left an orphan Runtime Host that blocked the next launch.
Evidence (2026-08-24,
main@3f5c4bb):PID 8473 PPID 1 ELAPSED 16:34Electron .../execution-candidate-main.js --root .../workspaces/default --generation 1b49784f-9488-406c-914f-d0823d044195 --expected-root-id 50d6e2d9...SingletonLock -> Yuhan-MacBook-Pro-M5-Pro.local-79390(PID gone),SingletonSocket -> /var/folders/.../SingletonSocketstill presentruntime.sqlite 715M/runtime.sqlite-wal 15Mnot reclaimed, writer lease still heldRuntime Host election / acquire State Root writeruntilkill 8473, then launches normallyThis matches the "ordinary Desktop quit does not guarantee retirement when durable residency remains" gap noted in the tracking description. #3348 fixes the update-handoff residue, but the normal quit path still leaves the same single-writer block. Happy to provide
ps/lsof/.maka-host-composition.jsonif needed.M4n5ter commentedon Aug 24, 2026
English
Split the urgent local Desktop startup blocker into #3703.
Current
mainstill maps explicit Desktop quit to Client/lifecycle cleanup only; it does not retire the exact Desktop-owned ephemeral Host. Durable residency can therefore leave the sole State Root writer alive, and a later Desktop generation/epoch can wait forever until the process is terminated manually. #3348 closed after removing its unsafe PID-based sweep, so it delivered no functional fix for this path.#3703 narrows the required fix to authenticated exact-Host retirement on full Quit Maka, with managed remote/local service Hosts excluded and window-close semantics tested separately. This should be treated as a high-priority startup-availability bug ahead of the broader remaining recovery matrix.
简体中文
已将紧急的本地 Desktop 启动阻塞拆分为 #3703。
当前
main的明确 Desktop 退出仍然只关闭 Client/lifecycle,不会让 Desktop 自己拥有的精确 ephemeral Host 退场。Durable residency 因此可能让唯一的 State Root writer 一直存活,后续 Desktop generation/epoch 只能无限等待,直到用户手工终止该进程。#3348 最终移除了不安全的 PID sweep,因此没有为这条路径交付功能修复。#3703 将修复范围收紧为 full Quit Maka 对精确、已认证 Host 的安全退场,明确排除 managed remote/local service Host,并要求单独测试 window-close 语义。它应作为高优先级启动可用性 bug,优先于更广泛的剩余 recovery matrix 推进。
me2seeks commentedon Aug 26, 2026
Mainline update
PR #3920 has merged. Ready PR #3925 now carries the next owner-scoped mainline slice: explicit npm-global CLI update, current-Host retirement, target-epoch activation, npm package switching, and owner commit in one existing deployment transaction.
The #3243 tracker item remains unchecked until #3925 merges. This slice deliberately keeps remote/service updates operator-owned and direct
npxownership in #3244; it does not create a second journal, lock, or scheduler.简体中文
PR #3920 已合并。Ready PR #3925 正在推进下一段 owner-scoped 主线:在现有单一 deployment transaction 中完成显式 npm-global CLI 更新、当前 Host 退场、目标 epoch 激活、npm package 切换与 owner commit。
#3243 的追踪项在 #3925 合并前保持未勾选。本切片继续让 remote/service 更新由 operator 主动执行,把 direct
npxownership 留在 #3244;不新增第二套 journal、lock 或 scheduler。Generated-by: Codex
me2seeks commentedon Aug 28, 2026
Mainline update after #3925
PR #3925 has merged. The explicit npm-global installation-owner update path is now delivered: exact artifact staging, current-Host retirement, target activation and exact Ready verification, npm package switching, and durable owner commit all share the existing deployment authority transaction.
The #3243 tracker item remains open. The next owner-scoped slice is startup reconciliation after the user has already changed the npm-global installation externally; released persisted-State-Root qualification follows as a separate evidence slice. Direct
npxremains in #3244, while managed remote and service updates remain operator-owned.简体中文
PR #3925 已合并,显式 npm-global installation-owner 更新链路已经交付:精确 artifact staging、当前 Host 退场、目标激活与 exact Ready 验证、npm package 切换、durable owner commit 共同复用现有 deployment authority transaction。
#3243 仍保持开启。下一条 owner-scoped 主线是:用户已在外部改变 npm-global 安装后,CLI 启动时进行安全 reconciliation;随后再以独立证据切片验证真实 released package 与持久 State Root。Direct
npx仍归 #3244,managed remote/service 更新仍由 operator 主动执行。Generated-by: Codex
me2seeks commentedon Aug 28, 2026
Tracking update: #4069 is the next Ready mainline slice after merged #3925. It reconciles externally replaced npm-global CLI installations without adding a second authority or taking ownership away from remote/managed operators. The remaining mainline item after this review is persisted State Root qualification; scheduler and presentation work stay separate.