fix(desktop): support safe WSL on-demand Host handoff across incompatible deployments

[me2seeks]

What happened

Desktop cannot complete an incompatible managed WSL on-demand Host handoff. It directs the user to a manual update elsewhere and keeps an elapsed timer running, but provides no usable action for the managed WSL deployment it already knows how to address.

This issue is narrowed following review feedback. It covers one end-to-end WSL journey: classify the existing management route, retire through the persisted source operator, activate the selected exact deployment and reconnect, with truthful blocker UI. It does not define general WSL/SSH version governance.

Two lifecycles remain distinct:

• The WSL Host process is on-demand/ephemeral. It can be reused by multiple surfaces and may remain alive for connections or work, but it does not promise long-term availability. Closing one client does not authorize stopping other work.
• The deployment, exact package, operator and State Root ownership are durable. Process exit neither uninstalls the package nor deletes sessions. A restart of the same old package does not fix a cross-epoch mismatch.

How to reproduce / evidence

1. Retain a WSL managed on-demand Host installed by Desktop.
2. Connect with a Desktop whose contract is incompatible with that deployment.
3. Observe the manual-update blocker with Cancel/Recheck but no WSL handoff action. The reported window reached 89:14; that duration is user-reported, not independently timed.
4. The separate re-onboarding workaround can fail with Runtime Host cannot prepare for retirement: incompatible when new setup code attempts to retire a running incompatible on-demand Host. The precise user click before that error remains unconfirmed.

Source findings:

• runtime-host-desktop-candidate.ts classifies profile targets as external; runtime-host-desktop-manager.ts supplies no replacement route for them. Connect-only SSH and an authority-verified managed WSL environment must not be treated identically.
• runtime-host-lifecycle-transaction.ts requires a compatible connection for on-demand retirement when there is no supervisor. An isolated diagnostic using its real State Root writer lock and a stubbed incompatible handshake reproduced the error with either interruption policy. Releasing the writer allowed retirement. This is not a full Windows handoff E2E claim.
• The existing managed update transaction already uses the installed source operator. Reuse that authority, rather than inventing a second updater or lifecycle owner.

Environment

• Windows installed Desktop artifact inspected: 0.2.0-dev.25.20260908.
• WSL Ubuntu / Linux x64 / 6.6.87.2-microsoft-standard-WSL2.
• Managed Host 0.2.0-dev-fe229269f0df, epoch 121. Source TUI epoch 133 and a later Desktop diagnostic epoch 136 were separately observed; they are not asserted to belong to the inspected Desktop build.
• Source investigation at f09119884e3e640f1c10755da19a583416aed19f; relevant Desktop manager paths subsequently checked locally.

Expected behavior

1. Ordinary connection reuses/activates the installed deployment. Deterministic incompatibility is a blocker, not update progress. Show Cancel, Recheck and, when managed WSL authority and a valid target are available, an explicit action equivalent to Stop the old Host and continue with the selected Host. If this changes the package, disclose current/target identities; do not disguise a package change as a restart.
2. Recognize managed WSL control capability from the validated persisted operator and deployment binding. Being a WSL profile alone is not authority. Do not grant a connect-only SSH profile replacement rights.
3. After explicit handoff selection, execute safe retirement automatically only when absence of active work is established through the source operator/Host contract. A connected idle TUI is not itself proof of active work. Active work needs a separate interruption confirmation; if safe admission cannot be established, block truthfully. Do not add new cooperative-transfer promises.
4. Stage/verify the selected exact target, retire through the persisted source operator, then use existing lifecycle transaction/writer fences for cutover, readiness verification and reconnect. New-client business-protocol compatibility with the old Host must not be a prerequisite to this control operation.
5. Bind and revalidate deployment identity, Root ID and Host epoch under existing serialization. Changed identity, missing source operator or unknown activity produces a bounded blocker. No wsl --terminate, raw PID kill, deletion of ownership records or second writer.
6. No Host downgrade. If the Host is known to be newer than Desktop, guide the user to update Desktop. Do not infer product ordering from epoch or source hash; uncertain target suitability is not permission to downgrade.
7. Cancel before commit leaves existing work/deployment intact; once mutation has committed, complete the existing safe settlement/recovery contract and report that state. Do not claim an unsafe old-version rollback after the target may have opened storage. Distinguish successful handoff from failed Desktop reconnection.
8. Keep the strict protocol/epoch/composition contract. Source builds may use an explicit development artifact without release-channel parity, but do not bypass ownership, storage admission or activity protection.

Acceptance

• Existing compatible WSL Host is reused; stopped deployment can be activated without incidental replacement.
• Running incompatible old Host + no active work: explicit action completes source-operator retirement, selected deployment activation and Desktop reconnect.
• Connected idle TUI vs active TUI work: source-owned maintenance admission distinguishes them; activity interruption is separately confirmed. A TUI incompatible after cutover remains truthfully disconnected, not silently replaced or promised recovery.
• Newer Host + older Desktop: no downgrade; compatible connection succeeds, otherwise client-update guidance.
• Missing operator, unknown activity, changed Host/deployment or concurrent handoff: bounded non-destructive blocker/revalidation.
• Cancel, transport loss and WSL exit around transaction boundaries recover from existing durable authority; no double writer or fabricated success.
• Blocker state has no false update-progress timer; an actual handoff has real progress and truthful cancellation semantics.
• Connect-only SSH remains unable to replace its Host; no broad SSH maintenance redesign is required.

Scope and related work

• fix(desktop): separate WSL onboarding from shared Host update and interruption consent #5144 remains an independent related fix: WSL onboarding must not translate update authorization into interruption authorization.
• feat(desktop): expose safe explicit WSL Host updates through the installed operator #5145 and fix(runtime-host): make shared Host incompatibility and version status actionable #5146 are consolidated here, not completed independently. This issue owns backend, consent and UI for the same WSL handoff journey.
• Foundations: feat(runtime-host): add safe managed Host updates #3591, Runtime Host: managed deployments, on-demand activation, WSL, and OpenRC #3984, feat(runtime-host): establish canonical managed lifecycle transactions #4049, feat(runtime-host): support WSL as a local environment #4064, feat(runtime-host): make Host handoff automatic at safe boundaries #4958. Desktop 0.1.11 remote SSH Host incompatible with maka-agent@0.1.0-beta.1 #3973 remains separate release-artifact alignment work.
• Out of scope: SSH-wide matrix completion, latest-channel selection, generic client inventory, exhaustive source/release combinations, matching-TUI launchers, broader cross-epoch compatibility or a new version-governance policy.

简体中文

根据审查意见收窄为一条完整的 WSL 按需 Host 交接：Desktop 遇到不兼容时，识别受验证的部署管理入口，通过旧 operator 安全退场，启动选定的精确部署并重连。临时的是进程，不是安装和数据；按需也不表示可以随意结束其他客户端的任务。

界面提供取消、重新检查，以及具备管理能力时“停止旧 Host 并继续”。需要换包时明确展示当前/目标版本；普通连接不隐含换包授权。选择交接后，无活动工作才自动完成；中断活动工作另行确认。有一个空闲 TUI 不等于有活动工作，未知状态也不能当成空闲。

操作复用现有部署事务，绑定并复验 deployment、Root ID 和 Host epoch。不终止整个 WSL、不裸杀 PID、不新增 owner、不绕过 epoch。不降级 Host；Host 较新时引导更新 Desktop。管理入口缺失、状态未知或身份改变均明确阻塞。取消与断线按事务阶段恢复，不能虚假承诺回滚。

保留 #5144 独立修复 onboarding 授权问题；#5145/#5146 的 WSL 必要部分合并到这里。移除 SSH 全矩阵、最新频道、客户端 inventory 和完整源码/发布组合等关闭条件。尚未实现，不因合并 issue 宣称缺陷已修复。

AI disclosure: OpenAI Codex investigated and revised/submitted this issue under explicit user direction accepting the review feedback.

[M4n5ter]

English

I do not think #5143 should proceed as currently written. It identifies real gaps, but expands a concrete WSL on-demand Host handoff problem into a complete shared WSL/SSH maintenance and version-governance design.

Two lifecycles need to remain distinct:

• The Host process inside WSL is intentionally short-lived, on-demand, and ephemeral. It does not carry a long-term availability guarantee.
• The deployment, exact package, operator, and State Root ownership are durable and managed.

The right objective is therefore not to give WSL SSH-grade Host maintenance parity. It is:

When Desktop encounters an incompatible WSL on-demand Host, use the existing managed deployment authority to retire that Host safely, start the selected exact deployment, and reconnect.

For the reported scenario, Desktop should offer an action equivalent to “Stop the old Host and use the new Host,” subject to these boundaries:

• Retire the old Host through the persisted source operator. A cross-epoch transition must not require the new client to complete a business-protocol handshake with the old Host first.
• Bind the action to the exact deployment, Root ID, and Host epoch, and revalidate them under the existing lifecycle transaction and writer fence.
• Retire automatically only when there is no active work. Interrupting active work requires a separate explicit confirmation.
• Do not use wsl --terminate, a raw PID kill, or a second lifecycle authority.
• A missing source operator, unknown activity, or changed identity must produce a bounded blocker rather than forced takeover.
• If the Host is newer than Desktop, guide the user to update Desktop. Do not downgrade the Host to match an older client.

There are three concrete implementation gaps:

1. WSL onboarding unconditionally passes --update-existing, and package replacement then implicitly receives allowInterruptActiveTasks. Clicking “Connect” cannot simultaneously authorize package replacement and interruption of other work. Update consent and interruption consent must be separate.

2. Desktop classifies every profileTarget as external and consequently disables replacement for all of them. That is appropriate for connect-only SSH, but not for a managed WSL environment for which Desktop holds the distribution, Root ID, and persisted operator.

3. The incompatibility window says that a manual update is required and keeps an elapsed timer running even though no update transaction exists and WSL exposes no corresponding management action. Deterministic incompatibility is an actionable blocker, not progress. The UI should offer Cancel, Recheck, and—when WSL authority is available—Stop the old Host and continue.

I also do not think this needs three sub-issues. The current split divides one end-to-end user journey into backend, consent, and UI layers. As a result, each issue repeats the product contract and expands the scope independently.

I suggest:

• Keep fix(desktop): separate WSL onboarding from shared Host update and interruption consent #5144 as the independent fix for onboarding treating update authorization as interruption authorization.
• Narrow fix(desktop): support safe WSL on-demand Host handoff across incompatible deployments #5143 to the end-to-end WSL on-demand Host handoff: control-route classification, source-operator retirement, and the resulting blocker UI.
• Fold feat(desktop): expose safe explicit WSL Host updates through the installed operator #5145 and fix(runtime-host): make shared Host incompatibility and version status actionable #5146 back into fix(desktop): support safe WSL on-demand Host handoff across incompatible deployments #5143 unless there is a separately confirmed non-WSL problem that justifies independent tracking.
• Remove SSH-wide matrix completion, latest-channel selection, generic client inventory, and exhaustive source/release combinations from the closure criteria. They are not required to solve this problem and should not redefine general compatibility or version-governance policy through this issue.

A more accurate title would be:

fix(desktop): support safe WSL on-demand Host handoff across incompatible deployments

This is a request for changes: preserve the single lifecycle authority, active-work protection, exact identity fences, and no-downgrade rule, but bring the scope back to the WSL ephemeral Host handoff experience that actually needs to be fixed before implementation proceeds.

简体中文

我不建议按当前 #5143 推进。它抓到了真实缺口，但把一个具体的 WSL on-demand Host 交接问题，扩张成了 WSL/SSH 共用的完整维护和版本治理设计。

这里需要区分两个生命周期：

• WSL 中的 Host 进程是短生命周期、on-demand、ephemeral 的，不承诺长期可用。
• deployment、exact package、operator 和 State Root ownership 是持久且 managed 的。

因此，正确目标不是为 WSL 补齐一套 SSH 级的 Host maintenance 产品，而是：

当 Desktop 遇到不兼容的 WSL on-demand Host 时，能够通过已有 managed deployment authority 安全退场旧 Host、启动所选 exact deployment，并重新连接。

对于当前报告的场景，Desktop 应当提供“停止旧 Host 并使用新 Host”的能力，但需要遵守以下边界：

• 使用 persisted source operator 退场旧 Host；跨 epoch 时不能要求新客户端先通过旧 Host 的业务握手。
• 操作绑定到准确的 deployment、Root ID 和 Host epoch，并在已有 lifecycle transaction 和 writer fence 内复验。
• 默认只在没有活动工作时完成交接；存在活动工作时，必须单独确认中断。
• 不使用 wsl --terminate、裸 PID kill，也不新增第二套 lifecycle authority。
• source operator 缺失、活动状态未知或身份变化时，应返回明确 blocker，而不是强制接管。
• 如果 Host 比 Desktop 新，应引导更新 Desktop，不能为了匹配旧客户端而降级 Host。

当前有三个明确缺口：

1. WSL onboarding 无条件传入 --update-existing，package replacement 又隐含获得 allowInterruptActiveTasks。点击“连接”不能同时代表授权换包和授权中断工作。更新授权与中断授权必须分开。

2. Desktop 将所有 profileTarget 都视为 external，因此统一禁止 replacement。这个模型适合 connect-only SSH，但不适合持有 distribution、Root ID 和 persisted operator 的 managed WSL environment。

3. incompatibility 窗口显示“需要手动更新”和持续 elapsed timer，但实际上没有更新事务正在运行，WSL 也没有对应的 management action。确定性不兼容是 actionable blocker，不是 progress。界面应提供取消、重新检查，以及在具备 WSL authority 时“停止旧 Host 并继续”。

我也不认为这里需要三个子 issue。当前拆分把同一条端到端用户旅程按 backend、consent 和 UI 分开，导致每个 issue 都重复定义产品契约，并进一步扩张范围。

建议：

• 保留 fix(desktop): separate WSL onboarding from shared Host update and interruption consent #5144，单独修复 onboarding 将更新授权等同于中断授权的问题。
• 将 fix(desktop): support safe WSL on-demand Host handoff across incompatible deployments #5143 收窄为 WSL on-demand Host handoff，包含 control-route classification、source-operator retirement 和最终 blocker UI。
• 将 feat(desktop): expose safe explicit WSL Host updates through the installed operator #5145、fix(runtime-host): make shared Host incompatibility and version status actionable #5146 合并回 fix(desktop): support safe WSL on-demand Host handoff across incompatible deployments #5143；除非存在独立、已经确认的非 WSL 问题，否则不需要分别追踪。
• 删除 SSH 全矩阵、latest-channel 选择、通用客户端 inventory、完整 source/release 组合等关闭条件。这些不是解决当前问题所必需的，也不应借本 issue 重新定义广义兼容和版本治理策略。

建议标题改为：

fix(desktop): support safe WSL on-demand Host handoff across incompatible deployments

这是一个 request changes：保留单一 authority、active-work protection、精确身份围栏和不降级原则，但在实施前先把范围收回到真正需要解决的 WSL ephemeral Host 交接体验。