[Tracking] Runtime Host maintenance and single-writer retirement

[me2seeks]

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 compatibilityEpoch mismatch, 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:

1. Disconnect Surface — release Client-owned resources; Host-owned durable work may continue.
2. Quit/stop Maka — explicit maintenance authorization; retire the owned local Host without immediately starting a replacement.
3. 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 npx invocation 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.

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
• 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 npx launches (discussion(cli): define durable Runtime Host ownership for npx launches #3244)
• Keep TUI /exit as 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.prepare handoff，但普通 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 的真实复现与截图见这条评论。

三种生命周期意图

产品和协议必须区分：

1. 断开 Surface：释放 Client-owned resource；Host-owned durable work 可以继续。
2. 退出/停止 Maka：明确维护授权；让所拥有的本地 Host 退场，但不立即启动 replacement。
3. 更新/替换 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：决定临时 npx invocation 是否以及如何拥有 durable local Host execution。
• feat(tui): add explicit local Runtime Host lifecycle and upgrade-conflict actions #3245：TUI lifecycle 展示与用户操作；它只是本 retirement contract 的 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
• 补全 active durable residency 下的本地 Desktop staged update/restart
• 协调 installed CLI/npm 更新与本地 installation handoff（feat(cli): coordinate local Runtime Host handoff across npm upgrades #3243）
• 决定临时 npx launch 的 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.

[me2seeks]

#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:

• wire/contract compatibility;
• capability compatibility;
• storage transition: compatible, migration required, or blocked;
• rollback classification after migration.

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]

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:

Once an installation owner has explicit maintenance authorization, how can the current Runtime Host retire, release the sole State Root writer, and let a replacement Host recover durable work safely?

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:

• one State Root has at most one writer;
• an incompatible Client cannot admit Domain commands merely to perform an upgrade;
• an ordinary remote credential does not grant service or deployment authority;
• the active Host never overwrites itself;
• a replacement artifact is staged before cutover;
• unresolved external effects remain result_unknown;
• rollback is not promised after an irreversible storage transition.

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.

Surface disconnect:
  release Client-owned resources
  keep the Host alive while durable residency remains

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.

Explicit quit:
  stop new admission
  persist durable intent
  settle or interrupt current execution
  release the writer
  stop the 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.

Explicit update:
  stage the new release
  stop new admission
  persist durable intent
  settle or interrupt current execution
  release the writer
  install and start the replacement
  recover durable work

The user should not have to approve every Goal or Scheduled Task separately. Clicking Update is the maintenance authorization.

The distinction is therefore:

Surface disconnect:
  durable residency may keep the Host alive

Explicit quit:
  maintenance intent overrides residency
  persist recoverable work, then stop the Host

Explicit update:
  maintenance intent overrides residency
  persist recoverable work, replace the Host, then recover

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:

State	Expected behavior after retirement
Scheduled Task schedule	Remains durable and continues when a Host is running again
Pending scheduled fire	Reconciles under its existing delivery guarantees
Active or waiting Goal	Recovers its durable continuation intent
Automation	Recovers schedules, pending fires, and prerequisite waiting
Pending Interaction	Continues only if its execution remains recoverable; otherwise becomes explicitly cancelled or interrupted
In-flight Turn	Resumes from a supported durable checkpoint, or becomes explicitly interrupted
External tool effect	Preserves result_unknown when the outcome cannot be proven
Client capability	Is ephemeral and must be republished after reconnect
Drafts, open dialogs, selected tabs	Remain Client presentation state, not Host recovery state

Before releasing the State Root writer, the Host should:

• stop admitting new work;
• persist recoverable Domain intent;
• settle or interrupt active executions with an explicit maintenance reason;
• preserve unresolved effect uncertainty;
• close Domain resources;
• release the writer lease.

Separate Runtime retirement from deployment

There are three separate responsibilities:

1. Compatibility decides whether a Client can use the current Host contract.
2. Runtime retirement decides whether the current Host has fenced new work, preserved authoritative state, and released the writer.
3. Deployment stages, switches, starts, verifies, repairs, or rolls back an installed artifact.

The Runtime Host should own only the retirement portion:

• current activity and recovery facts;
• the admission fence;
• orderly settlement or interruption;
• release of the sole State Root writer.

The installation owner should own:

• resolving and staging an exact release;
• switching the service or application artifact;
• starting and verifying the replacement;
• deployment recovery and rollback where rollback remains valid.

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:

stage new release
      ↓
ask the current compatible Host to retire
      ↓
release the writer
      ↓
install and start the replacement

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.

• A Desktop update authorizes stopping only the local Host owned by that Desktop installation.
• Updating a shared managed Host is a separate operator action because it may affect other Desktop, TUI, or CLI Clients.
• Once remote maintenance has been explicitly authorized, it can reuse the same Host retirement semantics.
• Artifact staging, service switching, verification, and repair remain implementation-specific deployment responsibilities.

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:

currentRelease
stagedRelease
serviceTarget
cutoverStarted
storageTransition
lastVerification

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:

• an SSH management plane independent of the Runtime Host Domain protocol;
• exact release or development-package deployment;
• an OS service owner;
• idempotent setup;
• credential pairing separated from package installation;
• connection verification before saving the Client profile.

That work should not absorb the full replacement lifecycle. It only needs to preserve the right boundaries:

• Profile state is connection configuration, not update authority;
• package deployment and credential pairing remain separate;
• service management remains outside the Runtime Host;
• setup and future management commands report stable installation identity and exact installed release;
• retries converge on existing deployment facts instead of creating parallel authorities.

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:

Define the explicit maintenance and single-writer retirement contract shared by local and managed Runtime Hosts, while keeping compatibility, package deployment, and OS service lifecycle outside the Runtime Host Domain authority.

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。

更合适的问题是：

当 installation owner 已获得明确的维护授权后，当前 Runtime Host 如何安全退场、释放唯一的 State Root writer，并让 replacement Host 恢复 durable work？

Runtime Host 不应更新自己，也不应拥有完整的 deployment transaction。

应保留的不变量

以下约束是正确且必要的：

• 一个 State Root 至多有一个 writer；
• 不兼容 Client 不能为了升级而准入 Domain command；
• 普通 remote credential 不具备 service 或 deployment authority；
• active Host 不覆盖自己；
• replacement artifact 必须在 cutover 前完成 stage；
• 无法确认的外部 effect 必须保留 result_unknown；
• storage transition 已不可逆时不能承诺 rollback。

这些约束定义了安全边界，但并不要求建立一套通用的 durable upgrade state machine。

三种不同的生命周期意图

设计应区分三种用户意图。

1. Surface 断开

关闭窗口、连接中断或某个 Client 断开，不代表用户授权 Maka 停止 durable Host-owned work。

Surface 断开：
  释放 Client-owned resources
  durable residency 仍存在时保持 Host 运行

Goal、Automation、Scheduled Task、pending Interaction 和其他 Host-owned work 可以继续运行。

2. 主动“退出 Maka”/“立即停止 Maka”

明确的完整退出操作应授权 Maka 停止本地 Host 拥有的所有活动，并终止该 Host。

主动退出：
  停止新的 admission
  持久化 durable intent
  收敛或中断当前 execution
  释放 writer
  停止 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。

主动更新：
  stage 新版本
  停止新的 admission
  持久化 durable intent
  收敛或中断当前 execution
  释放 writer
  安装并启动 replacement
  恢复 durable work

无需为每个 Goal 或 Scheduled Task 分别请求确认。点击更新本身就是 maintenance authorization。

因此三者的区别是：

Surface 断开：
  durable residency 可以让 Host 保持运行

主动退出：
  maintenance intent 覆盖 residency
  持久化可恢复工作，然后停止 Host

主动更新：
  maintenance intent 覆盖 residency
  持久化可恢复工作，替换 Host，然后恢复

维护授权允许停止当前 execution，但不允许丢失 durable intent。

Recovery 应以语义状态定义

“重启后续上”不应被理解为每个 in-flight Turn 都能从原位置逐字节继续。应为每种 authority state 明确恢复语义：

状态	退场后的预期行为
Scheduled Task schedule	保持持久化，并在 Host 再次运行后继续调度
pending scheduled fire	按现有 delivery guarantee 进行 reconciliation
active/waiting Goal	恢复 durable continuation intent
Automation	恢复 schedule、pending fire 与 prerequisite waiting
pending Interaction	仅在其 execution 可恢复时继续，否则明确 cancelled 或 interrupted
正在运行的 Turn	从支持的 durable checkpoint 恢复，否则明确 interrupted
外部 tool effect	无法证明结果时保留 result_unknown
Client capability	属于临时状态，Client 重连后重新发布
草稿、弹窗和选中 tab	属于 Client presentation state，不属于 Host recovery state

在释放 State Root writer 前，Host 应当：

• 停止准入新工作；
• 持久化可恢复的 Domain intent；
• 以明确的 maintenance reason 收敛或中断当前 execution；
• 保留未解决的 effect uncertainty；
• 关闭 Domain resources；
• 释放 writer lease。

将 Runtime 退场与软件部署分开

这里实际存在三个独立职责：

1. Compatibility 决定 Client 是否可以使用当前 Host contract。
2. Runtime retirement 决定当前 Host 是否已 fence 新工作、保存权威状态并释放 writer。
3. Deployment 负责 stage、切换、启动、验证、repair 或 rollback 已安装的 artifact。

Runtime Host 只应拥有 retirement 部分：

• 当前活动和恢复事实；
• admission fence；
• execution 的有序收敛或中断；
• 唯一 State Root writer 的释放。

installation owner 应拥有：

• 解析并 stage 精确 release；
• 切换 service 或 application artifact；
• 启动并验证 replacement；
• deployment recovery，以及仍然有效时的 rollback。

操作系统 service manager 继续拥有进程和 service lifecycle。

这个边界可以避免 Runtime Host 逐渐成为另一个 package manager 或 deployment authority。

避免建立永久的跨版本 maintenance protocol

本地更新是在旧 Desktop 与当前 Host 仍然兼容时发起的，因此正常顺序应为：

stage 新版本
      ↓
请求当前兼容 Host 退场
      ↓
释放 writer
      ↓
安装并启动 replacement

不应先安装一个已经不兼容的新 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 和失败边界。

• Desktop 更新只授权停止该 Desktop 安装所拥有的本地 Host。
• 更新共享的 managed Host 是独立的 operator action，因为它可能影响其他 Desktop、TUI 或 CLI Client。
• remote maintenance 获得明确授权后，可以复用相同的 Host retirement 语义。
• artifact staging、service 切换、验证和 repair 仍属于具体 deployment implementation。

真正值得共享的是一个小型 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，并且只保存必要事实，例如：

currentRelease
stagedRelease
serviceTarget
cutoverStarted
storageTransition
lastVerification

本地应用 updater 可能已经拥有等价的安装状态，不应仅为了架构形式统一而被迫使用同一 representation。

当前工作如何支持这个方向

当前 managed onboarding 工作已经建立了有价值的基础：

• 独立于 Runtime Host Domain protocol 的 SSH management plane；
• 精确 release 或 development package 部署；
• OS service owner；
• 幂等 setup；
• credential pairing 与 package installation 分离；
• 保存 Client profile 前完成连接验证。

这项工作不应顺带吸收完整的 replacement lifecycle，只需保持正确边界：

• Profile state 是连接配置，不是 update authority；
• package deployment 与 credential pairing 保持分离；
• service management 保持在 Runtime Host 之外；
• setup 与未来管理命令能够报告稳定的 installation identity 和精确 installed release；
• 重试应收敛到已有 deployment facts，而不是创建并行 authority。

未来的手动更新可以围绕这个小型 Host retirement contract 构建 deployment transaction。自动 channel reconciliation 应在手动 cutover 和 recovery 语义得到验证之后再引入。

建议的聚焦方向

我建议将这个 issue 收窄为：

定义本地与 managed Runtime Host 可以共享的显式 maintenance 和单写者 retirement contract，同时让 compatibility、package deployment 和 OS service lifecycle 保持在 Runtime Host Domain authority 之外。

这样既保留重要的安全约束，也为主动退出和主动更新提供清晰语义，并避免过早引入一套庞大的通用升级状态机。

[me2seeks]

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:

• old Desktop/Host: 807fea450a, RUNTIME_HOST_COMPATIBILITY_EPOCH = 24;
• new Desktop: 0ef1c55b5e, RUNTIME_HOST_COMPATIBILITY_EPOCH = 25;
• one active Scheduled Task was created under epoch 24;
• the epoch 24 Desktop was then fully exited without manually terminating the Host;
• the Scheduled Task residency kept the epoch 24 Host alive;
• starting the epoch 25 Desktop against the same State Root produced the conflict below.

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:

1. Quit currently behaves more like a Surface shutdown than an explicit “Stop Maka now”.
2. An already-incompatible Client cannot retire the old Host through the ordinary Domain protocol.

I suggest #3231 own only:

• the distinction between Surface disconnect, explicit full quit, and explicit update;
• the Host retirement contract: fence admission, preserve durable intent, settle or explicitly interrupt execution, release the sole writer, and report completion;
• semantic recovery expectations for Scheduled Tasks, Goals, pending Interactions, in-flight Turns, and unresolved external effects.

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 进行的真实测试：

• 旧 Desktop/Host：807fea450a，RUNTIME_HOST_COMPATIBILITY_EPOCH = 24；
• 新 Desktop：0ef1c55b5e，RUNTIME_HOST_COMPATIBILITY_EPOCH = 25；
• 在 epoch 24 下创建一个 active Scheduled Task；
• 完全退出 epoch 24 Desktop，但不手动结束 Host；
• Scheduled Task residency 使 epoch 24 Host 继续运行；
• 使用同一 State Root 启动 epoch 25 Desktop，出现下图冲突。

epoch 25 Desktop 能正确识别不兼容 Host 并显示其活动，但当前 Client 路径不能直接重启跨 epoch 冲突，因此界面只有等待和取消启动。这与语言和操作系统无关。recurring durable residency 一直存在时，“等待”不会自然结束。

这确认了两个当前缺口：

1. 当前 Quit 更接近 Surface shutdown，而不是明确的“立即停止 Maka”。
2. 已经不兼容的新 Client 无法通过普通 Domain protocol 让旧 Host 退场。

因此 #3231 建议只负责：

• 区分 Surface 断开、完全退出和主动更新；
• 定义 Host retirement contract：停止准入、保存 durable intent、收敛或明确中断执行、释放唯一 writer、报告完成；
• 明确 Scheduled Task、Goal、pending Interaction、in-flight Turn 和未知 external effect 的恢复语义。

兼容窗口仍由 #3204 负责；#3227 作为 storage transition 的实际证据；本地和 remote 的 artifact/service 部署继续由 installation owner 与 #3228 负责。

永久跨版本 maintenance protocol、通用 deployment journal 和完整升级状态机应删除，或继续明确标记为 Exploratory。

[me2seeks]

I'd like to take the TUI slice tracked here.

Proposed scope:

• keep /exit as disconnect this Surface, so closing one TUI does not stop Host-owned durable work or a shared managed remote Host;
• add an explicit installation-owner stop/restart path for the local Host, with clear interruption and recovery semantics;
• when an epoch conflict is detected, show the exact Host facts and direct the user to the appropriate local-owner or remote-operator action;
• coordinate with fix(cli): explain residency-blocked host conflicts #3208 so this extends its diagnostics and wait/cancel behavior instead of duplicating it;
• add focused TUI/CLI tests for resident Scheduled Tasks/Goals and incompatible epochs.

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。