Repository navigation
feat(tui): add explicit local Runtime Host lifecycle and upgrade-conflict actions #3245
Description
English
Problem
TUI currently has only Surface-exit behavior and compatibility-conflict diagnostics. It does not expose the three distinct user intents required by #3231:
- disconnect this TUI Surface;
- explicitly stop or restart the owned local Runtime Host;
- update/replace the installed local Host.
/exit closes the TUI connection and must remain Surface-only. The CLI connection path currently sends no Host generation, so a same-compatibility-epoch CLI build silently reuses an older Host build. If generation matching is added naively, upgrade_required is not handled by the current TUI conflict prompt. #3208 improves incompatibility facts and repeated wait/cancel behavior, but intentionally does not grant retirement or update authority.
Desired outcome
Add a thin TUI lifecycle adapter over the installation-owner and Host-retirement contracts. TUI presents authoritative facts and collects explicit user intent; it does not own package deployment, compatibility policy, or remote service authority.
Scope
- Keep
/exitand/quitas disconnect this Surface - Expose active Host identity, lifecycle mode, release/build identity, compatibility facts, connections, operations, and residencies supplied by the Host/installation owner
- Add explicit local-owner stop and restart actions with unambiguous wording
- For same-epoch release skew, distinguish “compatible but older active Host” from “replacement required”; never derive incompatibility from version distance alone (discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204)
- For
upgrade_requiredor epoch conflict, present exact restart / wait / cancel choices allowed by the owner contract - Show the interruption and semantic-recovery consequences for Goals, Scheduled Tasks, Interactions, in-flight Turns, and unresolved external effects
- Direct managed remote users to the remote operator path instead of offering a local restart action
- Reuse fix(cli): explain residency-blocked host conflicts #3208 diagnostics and retry behavior without duplicating conflict formatting or retry policy
- Invoke [Tracking] Runtime Host maintenance and single-writer retirement #3231 retirement and feat(cli): coordinate local Runtime Host handoff across npm upgrades #3243 installed-update operations through bounded adapters
- Incorporate the ownership decision from discussion(cli): define durable Runtime Host ownership for npx launches #3244 before allowing an
npxTUI to stop or replace a durable Host
Authority boundary
TUI may:
- render authoritative lifecycle and recovery facts;
- ask for explicit maintenance consent;
- invoke an authorized local installation-owner operation;
- reconnect after a new
hostEpochbecomes ready.
TUI may not:
- install or switch npm artifacts itself;
- infer package authority from an ordinary Runtime Host credential;
- silently stop a shared managed remote Host;
- invent a second update journal or lifecycle state machine;
- promise byte-exact continuation or safe rollback without evidence.
Candidate UX
/exit
Disconnect this TUI. Background Host work may continue.
/host status
Show active release, lifecycle owner, activity, and compatibility.
/host stop
Stop the owned local Host after explicit recovery/interruption review.
/host restart
Retire and restart the owned local Host without changing the installed release.
/update
Enter the #3243 installed-update flow; TUI only renders and confirms it.
Command names remain Planned until the product wording is reviewed.
Verification matrix
- same release, multiple TUI/Desktop Surfaces
- same compatibility epoch, different release/build identity
- incompatible epoch with no durable residency
- incompatible epoch retained by a recurring Scheduled Task or Goal
- in-flight external effect with
result_unknown - user chooses restart, wait, and cancel
- global npm installation, external npm replacement, and the selected discussion(cli): define durable Runtime Host ownership for npx launches #3244
npxmodel - managed remote profile, where local stop/restart is unavailable
- restart failure after the writer is released
Success criteria
/exitnever retires a Host merely because one Surface closed.- Explicit local stop/restart uses one owner and one [Tracking] Runtime Host maintenance and single-writer retirement #3231 retirement contract.
- Compatible build skew is visible but not automatically treated as protocol incompatibility.
- Incompatible or replacement-required startup never enters an unbounded wait without a cancel or operator action.
- Remote profiles never expose an unauthorized local replacement action.
- Tests prove the TUI is a projection/adapter and does not become a second lifecycle authority.
Part of #3231. Depends on the owner/update contract in #3243 and the npx ownership decision in #3244. Builds on, but does not broaden, #3208.
简体中文
问题
当前 TUI 只有 Surface 退出语义和兼容冲突诊断，没有展示 #3231 要求区分的三种用户意图：
- 只断开当前 TUI Surface；
- 明确停止或重启所拥有的本地 Runtime Host；
- 更新/替换已安装的本地 Host。
/exit 会关闭 TUI connection，必须继续保持 Surface-only。当前 CLI connection 不发送 Host generation，所以同 compatibility epoch 的新 CLI build 会静默复用旧 Host build。如果直接加 generation，upgrade_required 也不会进入当前 TUI conflict prompt。#3208 改进不兼容事实与重复 wait/cancel 行为，但有意不提供 retirement 或 update authority。
期望结果
在 installation-owner 与 Host-retirement contract 上增加一层很薄的 TUI lifecycle adapter。TUI 只展示权威事实并收集明确用户意图，不拥有 package deployment、compatibility policy 或 remote service authority。
范围
- 保持
/exit与/quit的只断开当前 Surface语义 - 展示 Host/installation owner 提供的 active Host identity、lifecycle mode、release/build identity、compatibility、connection、operation 与 residency facts
- 增加措辞明确的本地 owner stop/restart action
- 同 epoch release skew 下区分“兼容但 active Host 较旧”与“必须替换”，不从版本距离推断不兼容（discussion(runtime-host): define version skew and operator-led remote Host upgrades #3204）
upgrade_required或 epoch conflict 时，根据 owner contract 展示精确的 restart / wait / cancel 选择- 展示 Goal、Scheduled Task、Interaction、in-flight Turn 与 unresolved external effect 的中断和语义恢复后果
- Managed remote 场景引导用户走 remote operator path，不提供本地 restart action
- 复用 fix(cli): explain residency-blocked host conflicts #3208 的诊断和 retry 行为，不重复 conflict formatting 或 retry policy
- 通过有界 adapter 调用 [Tracking] Runtime Host maintenance and single-writer retirement #3231 retirement 与 feat(cli): coordinate local Runtime Host handoff across npm upgrades #3243 installed-update operation
- discussion(cli): define durable Runtime Host ownership for npx launches #3244 决定 ownership model 前，不允许
npxTUI 停止或替换 durable Host
Authority 边界
TUI 可以：
- 渲染权威 lifecycle 与 recovery facts；
- 请求明确 maintenance consent；
- 调用已授权的本地 installation-owner operation；
- 新
hostEpochready 后重连。
TUI 不可以：
- 自己安装或切换 npm artifact；
- 从普通 Runtime Host credential 推断 package authority；
- 静默停止共享 managed remote Host；
- 再创建一套 update journal 或 lifecycle state machine；
- 在没有证据时承诺逐字节续跑或安全 rollback。
候选 UX
/exit
断开当前 TUI；Host 后台工作可以继续。
/host status
显示 active release、lifecycle owner、activity 与 compatibility。
/host stop
在明确检查恢复/中断后，停止所拥有的本地 Host。
/host restart
不改变 installed release，只让所拥有的本地 Host 退场并重启。
/update
进入 #3243 installed-update 流程；TUI 只负责展示和确认。
命令名称在产品措辞评审前仍为 Planned。
验证矩阵
- 同 release、多个 TUI/Desktop Surface
- 同 compatibility epoch、不同 release/build identity
- 没有 durable residency 的不兼容 epoch
- recurring Scheduled Task 或 Goal 保持常驻的不兼容 epoch
- 存在
result_unknown的 in-flight external effect - 用户分别选择 restart、wait 与 cancel
- global npm installation、外部 npm replacement，以及 discussion(cli): define durable Runtime Host ownership for npx launches #3244 最终选择的
npxmodel - 不允许本地 stop/restart 的 managed remote profile
- writer 释放后 replacement 启动失败
完成标准
/exit不会仅因一个 Surface 关闭而让 Host 退场。- 显式本地 stop/restart 只使用一个 owner 和一套 [Tracking] Runtime Host maintenance and single-writer retirement #3231 retirement contract。
- 兼容 build skew 可见，但不会自动视为协议不兼容。
- 不兼容或必须替换时，不会进入缺少 cancel/operator action 的无限等待。
- Remote profile 不显示未授权的本地 replacement action。
- 测试证明 TUI 只是 projection/adapter，而不是第二个 lifecycle authority。
属于 #3231；依赖 #3243 的 owner/update contract 与 #3244 的 npx ownership 决策；建立在 #3208 之上，但不扩大其范围。
AI assistance disclosure
This issue was investigated and drafted with Codex using current source and isolated same-epoch and cross-epoch Runtime Host experiments.
Activity
me2seeks commentedon Aug 19, 2026
I’m working on this.
我正在推进这项工作。