@zq-silk/yui 0.15.9 → 0.15.12

package/ARCHITECTURE.md

@@ -169,8 +169,9 @@ Leader management is limited to its Task; executable code still requires exact
 Operator-issued grants. Plugin validation is not a security certification.
 
 CLI contributions and controlled Web panels are projections of the Registry.
-Web is loopback-only and Controller-owned; browser credentials do not become
-Operator authority. See [Plugin SDK](docs/plugin-sdk.md) and
+Web is loopback-only and Controller-owned. Its authenticated local-user controls
+share CLI domain operations; query panels remain read-only and cannot borrow
+that user authority for mutations or plugin management. See [Plugin SDK](docs/plugin-sdk.md) and
 [capabilities and resources](docs/architecture/capabilities-and-resources.md).
 
 ## Persistence, completion and operation
@@ -181,8 +182,11 @@ Homes; malformed state is diagnosed, not automatically repaired.
 
 Completion freezes the delivery result and checks applicable acceptance,
 integration and review contracts. It is distinct from publication, verified
-remote merge, physical quiescence and archive. Archive requires settled work
-and clean removable managed resources, preserves Task history, and cannot reopen.
+remote merge, physical quiescence and archive. Ordinary archive requires settled
+work and clean removable managed resources. Explicitly authorized force archive
+can retain unresolved evidence and unsafe resources without claiming delivery or
+quiescence. Both preserve Task history and cannot reopen.
+See [Task delivery and archive](docs/task-delivery.md#archive).
 
 Runtime health and cost are observations, not semantic verdicts. The Agent reads
 exact faults and current intent to choose retry, repair or abandonment. Yui does

package/ARCHITECTURE.zh-CN.md

@@ -132,7 +132,8 @@ Registry 暴露 context、消息、artifact、环境、插件以及部分 Task/J
 由 Operator 签发的 grant。插件验证不是安全认证。
 
 CLI 贡献和受控的 Web 面板是 Registry 的投影。Web 仅本地回环、由 Controller 拥有；浏览器
-凭据不会变成 Operator 权限。参见[插件 SDK](docs/plugin-sdk.zh-CN.md)和
+凭据认证本地用户控制，这些控制复用 CLI 领域操作；查询面板仍只读，不能借用该用户权限
+执行修改或插件管理。参见[插件 SDK](docs/plugin-sdk.zh-CN.md)和
 [能力与资源](docs/architecture/capabilities-and-resources.zh-CN.md)。
 
 ## 持久化、完成与运维
@@ -141,7 +142,9 @@ Home 有一条只追加的存储迁移链。普通运行时只接受当前记录
 有效 Home；畸形状态被诊断，而不是自动修复。
 
 完成会冻结交付结果，并检查适用的验收、集成和审查合同。它区别于发布、已验证的远程合并、
-物理静止和归档。归档要求工作已了结、受管资源干净可移除，保留 Task 历史，且不可重开。
+物理静止和归档。普通归档要求工作已了结、受管资源干净可移除。明确授权的 force 归档
+可以保留未解决证据与不安全资源，但不宣称交付或物理静止。两者都保留 Task 历史且不可
+重开。参见[Task 交付与归档](docs/task-delivery.zh-CN.md#归档)。
 
 运行时健康度和成本是观察，而不是语义判定。Agent 读取精确的故障和当前意图，以选择重试、
 修复或放弃。Yui 不会自动创建救援 Worker 或选择另一个模型。

package/README.md

@@ -30,7 +30,7 @@ not from terminal windows you juggle or details you have to remember.
 - **Bring your own Agent** — Codex CLI, Claude Code CLI and ACP peers run behind
   one boundary and stay replaceable without losing the Task.
 - **Local-first and private** — everything runs on your machine for one trusted
-  user; the Web view is loopback and read-only.
+  user; Web is loopback-only, with read-only views and authenticated user controls.
 - **Isolated by default** — repository work happens in managed Git worktrees;
   the stable checkout stays read-only.
 
@@ -137,7 +137,11 @@ when necessary. A failed process does not erase the Task, and an uncertain
 submission is not silently repeated.
 
 For a visual overview, run `yui web` in another terminal. The local Web view
-shows the same tasks and pending questions; it is not a separate task system.
+shows the same tasks and pending questions and lets you send messages, answer
+questions and explicitly queue, steer or interrupt Task input. These authenticated
+Task controls use the same operations as the CLI; Web is not a separate task system.
+See [Web permissions](docs/architecture/capabilities-and-resources.md#cli-and-web)
+and [input timing](docs/managed-turn-and-session-runtime.md#input-timing-queue-steer-and-interrupt).
 
 ## Architecture
 
@@ -243,7 +247,7 @@ the Controller are what touch the store:
      it moves work and records facts — it never judges an answer
 
   Agents work in Projects: read-only checkout + isolated worktrees.
-  Web view (yui web): a loopback, read-only projection of the store.
+  Web (yui web): loopback views + authenticated user controls.
 ```
 
 ### Layered design
@@ -253,7 +257,7 @@ never a fixed workflow:
 
 ```text
   Experience   —  how you interact
-    CLI (Operator) · Web (loopback, read-only) · native Agent sessions
+    CLI (Operator) · Web (loopback, authenticated) · native Agent sessions
     collect input · show facts · confirm actions · invoke capabilities
         ▼
   Intelligence —  who decides
@@ -290,9 +294,13 @@ extra states:
   WorkItem  open ─▶ accepted ─▶ retired
 
   Draft holds planning only; activation adopts a delivery workspace.
-  Archive needs settled work and clean worktrees; it cannot reopen.
+  Ordinary archive needs settled work and clean worktrees; it cannot reopen.
 ```
 
+Explicitly authorized force archive can retain unresolved evidence and unsafe
+resources; it does not prove delivery or permission to delete them.
+See the [archive contract](docs/task-delivery.md#archive).
+
 ## Design principles
 
 ### Agents make decisions; Yui makes work durable

package/dist/agent/launchEnvironment.js

@@ -122,6 +122,13 @@ export function operationalAgentEnvironment(adapterId, source) {
             || `${dirname(process.execPath)}:/usr/local/bin:/usr/bin:/bin`,
         HOME: source.HOME || homedir(),
         TERM: usableInteractiveTerminal(source.TERM),
+        // Base fallback only. Every managed Task launch has its isolation
+        // environment (TMPDIR = the Home-side runtime `roots.temporary`) assigned
+        // OVER this by the launch planner, so this branch is reached only by
+        // non-isolated global/ad-hoc launches with no managed runtime. Those run in
+        // the operator's own context, where their inherited TMPDIR (or the system
+        // temp) is the correct scratch — forcing it under control Home would
+        // misroute user scratch into Yui-managed storage.
         TMPDIR: source.TMPDIR || tmpdir()
     };
 }

package/dist/agentRun/agentRun.js

@@ -2,6 +2,7 @@ import { validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js"
 import { validateTaskRecordReference } from "../task/taskRecordReference.js";
 import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
 import { createRunInput, createRunInputEnvelope, validateRunInput } from "../context/runInputContract.js";
+import { providerRetryProjection } from "../runtime/providerRetry.js";
 import { boundedRunFailureDiagnostic, MAX_RUN_FAILURE_DIAGNOSTIC_BYTES, MAX_RUN_RESULT_OUTPUT_BYTES } from "../domain/agentResultTransport.js";
 export { boundedRunFailureDiagnostic, MAX_RUN_FAILURE_DIAGNOSTIC_BYTES, MAX_RUN_RESULT_OUTPUT_BYTES, transportAgentResult } from "../domain/agentResultTransport.js";
 /** Record lifecycle and observed delivery are separate read-only facts. */
@@ -17,6 +18,8 @@ export function runExecutionObservation(run, binding, events = []) {
     return {
         recordStatus: run.status,
         delivery,
+        retry: binding?.retry?.previousRunId === run.id || binding?.retry?.successorRunId === run.id
+            ? providerRetryProjection(binding) : null,
         ...(current === undefined ? {} : {
             attemptId: current.attemptId, observedAt: current.updatedAt,
             ...(current.nativeTurnId === undefined ? {} : { nativeTurnId: current.nativeTurnId })

package/dist/cli/commandCatalog.js

@@ -215,6 +215,11 @@ const globalSessionChildren = [
         summary: "Reconcile durable Session owners with native sessions.",
         usage: "yui session reconcile [--report] [--cleanup]",
         options: ["--report", "--cleanup"]
+    },
+    {
+        name: "retry",
+        summary: "Inspect or control bounded Provider recovery for this Global Session.",
+        usage: "yui session retry <role> [show|cancel|disable|enable]"
     }
 ];
 const profileChildren = [
@@ -373,9 +378,9 @@ const taskChildren = [
     },
     {
         name: "list",
-        summary: "List unarchived Task overviews.",
-        usage: "yui task list [--all] [--verbose]",
-        options: ["--all", "--verbose"]
+        summary: "List Task overviews or a bounded discovery catalog.",
+        usage: "yui task list [--all] [--verbose] | --view compact [--all] [--status <status>] [--project <id>] [--search <text>] [--attention <category>] [--limit <1..100>] [--cursor <cursor>]",
+        options: ["--all", "--verbose", "--view", "--status", "--project", "--search", "--attention", "--limit", "--cursor"]
     },
     { name: "show", summary: "Show a Task.", usage: "yui task show <id>" },
     {
@@ -406,10 +411,16 @@ const taskChildren = [
         usage: "yui task remote-delivery <task> [--json]",
         options: ["--json"]
     },
+    {
+        name: "archive-preflight",
+        summary: "Inspect current archive and exact-owner cleanup blockers without changing state or authorizing removal.",
+        usage: "yui task archive-preflight <id> (--integrated|--abandon) [--force] [--json]",
+        options: ["--integrated", "--abandon", "--force", "--json"]
+    },
     {
         name: "archive",
-        summary: "Archive a Task after confirming the main worktree outcome.",
-        usage: "yui task archive <id> (--integrated [--force]|--abandon)",
+        summary: "Archive a terminal Task; explicit --force commits despite delivery/cleanup warnings, retaining unsafe resources.",
+        usage: "yui task archive <id> (--integrated|--abandon) [--force]",
         options: ["--integrated", "--abandon", "--force"]
     },
     { name: "reconcile", summary: "Run one immediate Controller reconciliation.", usage: "yui task reconcile <id>" },
@@ -435,7 +446,7 @@ const taskChildren = [
     {
         name: "message",
         summary: "Manage durable Task messages.",
-        sections: [{ id: "manage", title: "Commands", entries: ["send", "handoff", "list", "show", "update", "retire"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["send", "queue", "steer", "handoff", "list", "show", "update", "retire"] }],
         children: [
             {
                 name: "handoff",
@@ -454,6 +465,20 @@ const taskChildren = [
                 },
                 fileOptions: ["--body-file"]
             },
+            {
+                name: "queue",
+                summary: "Queue an input for delivery at the recipient's next legal opportunity (idempotent by request id).",
+                usage: "yui task message queue <id> (<body>|--body-file <path|->) --request-id <id> [--to <role> --work-item <id>|--review-round <id>]",
+                options: ["--body-file", "--request-id", "--to", "--work-item", "--review-round"],
+                fileOptions: ["--body-file"]
+            },
+            {
+                name: "steer",
+                summary: "Steer only a Role's exact current native Turn; saved and reported without fallback when unsupported.",
+                usage: "yui task message steer <id> (<body>|--body-file <path|->) --request-id <id> --expected-target <turn> --to <role> [--work-item <id>|--review-round <id>]",
+                options: ["--body-file", "--request-id", "--expected-target", "--to", "--work-item", "--review-round"],
+                fileOptions: ["--body-file"]
+            },
             {
                 name: "list",
                 summary: "List Task messages.",
@@ -592,17 +617,29 @@ const taskChildren = [
     {
         name: "publication",
         summary: "Create or update external PR/MR publication evidence for a Task.",
-        sections: [{ id: "manage", title: "Commands", entries: ["upsert", "verify", "list", "show"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["upsert", "diff", "adopt", "verify", "list", "show"] }],
         children: [
             {
                 name: "upsert",
                 summary: "Create or immutably update an external PR/MR and its publication state.",
-                usage: "yui task publication upsert <task> --project <project> --provider <github|gitlab> --repository <owner/name> --kind <pull-request|merge-request> --id <external-id> [--url <url>] [--title <text>] [--source-branch <branch>] [--target-branch <branch>] [--local-commit <sha>] [--remote-commit <sha>] [--state <open|merged|closed>] [--reported|--verified] [--evidence <text>] [--merged-at <iso-timestamp>]",
-                options: ["--project", "--provider", "--repository", "--kind", "--id", "--url", "--title", "--source-branch", "--target-branch", "--local-commit", "--remote-commit", "--state", "--reported", "--verified", "--evidence", "--merged-at"]
+                usage: "yui task publication upsert <task> --project <project> --provider <github|gitlab> --repository <owner/name> --kind <pull-request|merge-request> --id <external-id> [--url <url>] [--title <text>] [--source-branch <branch>] [--target-branch <branch>] [--local-commit <sha>] [--head-commit <sha>] [--remote-commit <sha>] [--state <open|merged|closed>] [--reported|--verified] [--evidence <text>] [--merged-at <iso-timestamp>]",
+                options: ["--project", "--provider", "--repository", "--kind", "--id", "--url", "--title", "--source-branch", "--target-branch", "--local-commit", "--head-commit", "--remote-commit", "--state", "--reported", "--verified", "--evidence", "--merged-at"]
+            },
+            {
+                name: "diff",
+                summary: "Read a completed Task's fixed acceptance-to-publication candidate diff using local Git only.",
+                usage: "yui task publication diff <task>/<publication> [--integration <id>]",
+                options: ["--integration"]
+            },
+            {
+                name: "adopt",
+                summary: "Explicitly accept the reviewed publication candidate as covering the original completion.",
+                usage: "yui task publication adopt <task>/<publication> --reviewed-diff <sha256> --acceptance <text> [--integration <id>]",
+                options: ["--reviewed-diff", "--acceptance", "--integration"]
             },
             {
                 name: "verify",
-                summary: "Verify one current GitHub PR against the exact Task delivery head through gh.",
+                summary: "Observe the current PR/MR head and merge through its provider; record verification separately from Task coverage.",
                 usage: "yui task publication verify (<task>/<publication-id> | <task> <publication-id>)"
             },
             {
@@ -622,7 +659,7 @@ const taskChildren = [
         summary: "Manage Roles within a Task.",
         sections: [{ id: "manage", title: "Commands", entries: [
                     "add", "list", "status", "show", "update", "remove", "bind", "unbind",
-                    "session", "view", "takeover", "release"
+                    "session", "interrupt", "view", "takeover", "release"
                 ] }],
         children: [
             {
@@ -654,8 +691,13 @@ const taskChildren = [
                 name: "session",
                 summary: "Inspect, stop or explicitly select a new Task Role Session.",
                 executable: true,
-                sections: [{ id: "manage", title: "Commands", entries: ["inspect", "stop", "new"] }],
+                sections: [{ id: "manage", title: "Commands", entries: ["inspect", "retry", "stop", "new"] }],
                 children: [
+                    {
+                        name: "retry",
+                        summary: "Inspect or control Provider recovery without stopping an admitted Turn.",
+                        usage: "yui task role session retry <task> <role> [show|cancel|disable|enable]"
+                    },
                     {
                         name: "inspect",
                         summary: "Read the current Session, Host process, and AgentRun facts.",
@@ -680,6 +722,12 @@ const taskChildren = [
                 summary: "Attach read-only to an independent Provider presentation surface.",
                 usage: "yui task role view <task> <role>"
             },
+            {
+                name: "interrupt",
+                summary: "Interrupt a Role's exact current native Turn via native cancel; optionally deliver a saved Message once after a proven terminal.",
+                usage: "yui task role interrupt <task> <role> --expected-target <turn> [--then-message <task/message>] [--request-id <id>]",
+                options: ["--expected-target", "--then-message", "--request-id"]
+            },
             {
                 name: "takeover",
                 summary: "Enter the PTY input gateway for an independent Provider process.",
@@ -706,7 +754,7 @@ const taskChildren = [
         children: [
             {
                 name: "create",
-                summary: "Create a work item.",
+                summary: "Create a separately managed result; a coherent Task may use zero WorkItems. Omit --role for Leader-direct execution; --role (including leader) selects a managed AgentRun executor. Isolate writable direct work before editing, then submit, integrate and accept its Candidate.",
                 usage: "yui task work create <task> <title> [--project <project> ...] [--base-ref <project>=<ref> ...] [--objective <text>] [--accept <criterion> ...] [--after <work> ...] [--role <name>]",
                 options: ["--project", "--base-ref", "--objective", "--accept", "--after", "--role"]
             },
@@ -922,7 +970,7 @@ const taskChildren = [
             },
             {
                 name: "abort",
-                summary: "Abandon a running or blocked Integration Attempt.",
+                summary: "Abandon an unadvanced Integration while preserving evidence; reconcile an already-applied target.",
                 usage: "yui task integration abort <task>/<integration> --reason <text>",
                 options: ["--reason"]
             },
@@ -1461,7 +1509,7 @@ export const ROOT_COMMAND = buildNode({
             sections: [
                 { id: "global", title: "Global Role sessions", entries: ["context", "enter", "record", "replace"] },
                 { id: "maintenance", title: "Maintenance", entries: ["stop"] },
-                { id: "recovery", title: "Recovery", entries: ["reconcile"] }
+                { id: "recovery", title: "Recovery", entries: ["reconcile", "retry"] }
             ],
             children: globalSessionChildren
         },
@@ -1469,7 +1517,7 @@ export const ROOT_COMMAND = buildNode({
             name: "task",
             summary: "Manage Tasks, WorkItems, AgentRuns, and integration.",
             sections: [
-                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "base", "update", "activate", "activation", "execution", "complete", "cancel", "reopen", "retire", "list", "show", "context", "next-action", "remote-delivery", "archive", "replace", "reconcile", "upstream", "artifact"] },
+                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "base", "update", "activate", "activation", "execution", "complete", "cancel", "reopen", "retire", "list", "show", "context", "next-action", "remote-delivery", "archive-preflight", "archive", "replace", "reconcile", "upstream", "artifact"] },
                 { id: "collaboration", title: "Collaboration", entries: ["message", "input", "grant", "workflow", "publication", "work", "run", "review", "integration", "role", "overlap", "change-set"] },
                 { id: "knowledge", title: "Task Knowledge", entries: ["brief", "decision", "milestone", "event", "continuation", "wake"] }
             ],

package/dist/cli/interactionPolicy.js

@@ -229,6 +229,10 @@ export const INTERACTION_POLICIES = Object.freeze([
         ...taskTarget("remote-delivery"),
         trailingOptions: { "--json": "flag" }
     },
+    {
+        ...taskTarget("archive-preflight"),
+        trailingOptions: { "--integrated": "flag", "--abandon": "flag", "--force": "flag", "--json": "flag" }
+    },
     {
         ...taskTarget("archive", 2, ["completed", "cancelled"]),
         trailingOptions: { "--integrated": "flag", "--abandon": "flag", "--force": "flag" },
@@ -574,9 +578,9 @@ export const INTERACTION_POLICIES = Object.freeze([
                 entity: "integration-attempt",
                 provider: "integration-attempts",
                 actionTarget: true,
-                ...(command === "continue" ? { statuses: ["blocked", "validating"] } : {}),
-                ...(command === "resolve" ? { statuses: ["blocked"] } : {}),
-                ...(command === "abort" ? { statuses: ["running", "blocked"] } : {})
+                ...(command === "continue" ? { statuses: ["running", "conflicted", "blocked", "validating"] } : {}),
+                ...(command === "resolve" ? { statuses: ["blocked", "conflicted"] } : {}),
+                ...(command === "abort" ? { statuses: ["running", "conflicted", "blocked", "validating"] } : {})
             }],
         ...(command === "resolve"
             ? { trailingOptions: { "--option": "value", "--rationale": "value" } }

package/dist/cli/managedDiagnostics.js

@@ -3,7 +3,7 @@
 export function taskDiagnosticTarget(args) {
     if (args[0] !== "task")
         return undefined;
-    if (["show", "context", "next-action"].includes(args[1] ?? "")) {
+    if (["show", "context", "next-action", "archive-preflight"].includes(args[1] ?? "")) {
         return args[1] === "context" && ["inspect", "delta"].includes(args[2] ?? "")
             ? args[3] : args[2];
     }

package/dist/cli/updateOrchestrator.js

@@ -101,7 +101,30 @@ function runStagedUpdate(ports, staged, home) {
         const captured = captureControllerLifecycle(ports, staged.version, home);
         if ("outcome" in captured)
             return captured;
-        return activateAndVerify(ports, staged, home, captured.lifecycle, preflight);
+        // An older Controller can finish a launch between preflight and drain.
+        // Recheck after its exact stop, before changing the install or storage.
+        let fencedPreflight;
+        try {
+            fencedPreflight = ports.preflight(staged, home);
+        }
+        catch (error) {
+            return restoreControllerOrReport(ports, home, captured.lifecycle, {
+                outcome: "aborted", phase: "preflight",
+                message: `Quiesced compatibility preflight failed: ${messageOf(error)}`,
+                action: "The install and storage are unchanged; inspect the compatibility failure before retrying.",
+                recoverable: true, version: staged.version
+            });
+        }
+        if (fencedPreflight.status === "blocked") {
+            return restoreControllerOrReport(ports, home, captured.lifecycle, {
+                outcome: "aborted", phase: "preflight",
+                message: fencedPreflight.message, action: fencedPreflight.action,
+                recoverable: true, version: staged.version,
+                ...(fencedPreflight.blockers === undefined ? {} : { blockers: fencedPreflight.blockers }),
+                ...(fencedPreflight.sceneUnchanged === true ? { sceneUnchanged: true } : {})
+            });
+        }
+        return activateAndVerify(ports, staged, home, captured.lifecycle, fencedPreflight);
     }
     finally {
         releaseHandover?.();

package/dist/cli/updatePorts.js

@@ -25,14 +25,15 @@
  *    mismatch fails closed.
  */
 import { spawnSync } from "node:child_process";
-import { accessSync, constants, existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { accessSync, constants, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runtimeError } from "../errors/cliError.js";
 import { isConcreteVersion } from "../domain/validation.js";
 import { STORAGE_DOCTOR_CHECK_NAMES } from "../doctor/doctor.js";
 import { acquireHandoverLock } from "../release/runtimeRelease.js";
+import { updateStagingRoot } from "../storage/homeLayout.js";
+import { resolveYuiHome } from "../storage/taskStore.js";
 const PACKAGE_NAME = "@zq-silk/yui";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 function resolveExecutable(command, environmentPath) {
@@ -64,7 +65,7 @@ function failedSpawnResult(message) {
     };
 }
 /** Build the real ports. `spawn` is injectable so tests avoid real installs. */
-export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot = tmpdir()) {
+export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot = updateStagingRoot(resolveYuiHome(environment))) {
     // The production adapter must not let a later PATH change select a
     // different npm during staging, activation, or recovery. Test doubles are
     // intentionally left untouched so deterministic tests can dispatch on the
@@ -105,6 +106,9 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                 throw runtimeError(`Refusing to stage a non-concrete version (${String(version)}): only an exact `
                     + "major.minor.patch version can be pinned for an update.");
             }
+            // The Home staging parent may not exist yet on a Home that has never
+            // run an update; create it (private) before minting a throwaway prefix.
+            mkdirSync(stagingRoot, { recursive: true, mode: 0o700 });
             const stagingPath = mkdtempSync(join(stagingRoot, "yui-update-stage-"));
             let ownsStaging = true;
             try {

package/dist/cli/upgradeCommand.js

@@ -1,6 +1,8 @@
 /** `yui upgrade` plans or applies the supported linear storage migration chain. */
 import { runStorageUpgrade } from "../storage/upgrade/upgradeOrchestrator.js";
-import { ensureFileTaskController, stopFileTaskController } from "../controller/clientRuntime.js";
+import { ensureFileTaskController, ensureFileTaskControllerIdentity, stopFileTaskController } from "../controller/clientRuntime.js";
+import { callController, ControllerClientError } from "../core/controllerClient.js";
+import { spawn } from "node:child_process";
 import { runtimeError, usageError } from "../errors/cliError.js";
 import { acquireHandoverLock, isForeignHandoverLockHeld, isHandoverLockHeld } from "../release/runtimeRelease.js";
 /**
@@ -43,12 +45,29 @@ async function runInteractiveUpgrade(home, environment) {
     const handover = acquireHandoverLock(home);
     let controllerWasRunning = false;
     try {
+        const previous = await captureUpgradeController(home);
         const stopped = await stopFileTaskController(home, {
             environment,
-            handoverOwnerPid: process.pid
+            handoverOwnerPid: process.pid,
+            ...(previous === undefined ? {} : { expectedPid: previous.pid })
         });
         controllerWasRunning = stopped.stopped;
         const result = await runStorageUpgrade({ home, mode: "execute" });
+        if (controllerWasRunning && result.outcome === "blocked") {
+            if (previous === undefined) {
+                throw runtimeError("Upgrade was blocked without changing storage; the stopped Controller identity is unknown. Keep the Home quiesced.");
+            }
+            await ensureFileTaskControllerIdentity(home, previous.identity, {
+                environment, handoverOwnerPid: process.pid,
+                spawnController: (_home, launchEnvironment) => {
+                    const child = spawn(previous.identity.executablePath, [...previous.identity.args], {
+                        env: launchEnvironment, detached: true, stdio: "ignore"
+                    });
+                    child.unref();
+                    return child.pid;
+                }
+            });
+        }
         if (controllerWasRunning
             && (result.outcome === "upgraded" || result.outcome === "already-current")) {
             try {
@@ -70,6 +89,27 @@ async function runInteractiveUpgrade(home, environment) {
         handover.release();
     }
 }
+async function captureUpgradeController(home) {
+    let value;
+    try {
+        value = await callController(home, "controller.identity", {});
+    }
+    catch (error) {
+        if (error instanceof ControllerClientError && error.code === "CONTROLLER_NOT_RUNNING")
+            return undefined;
+        throw error;
+    }
+    const identity = value;
+    if (!Number.isSafeInteger(identity.pid) || identity.pid < 1
+        || typeof identity.executablePath !== "string" || !identity.executablePath
+        || !Array.isArray(identity.args) || identity.args.some(arg => typeof arg !== "string")
+        || typeof identity.version !== "string" || !identity.version) {
+        throw runtimeError("Cannot capture the exact Controller for a reversible upgrade preflight.");
+    }
+    return { pid: identity.pid, identity: {
+            executablePath: identity.executablePath, args: identity.args, version: identity.version
+        } };
+}
 async function runUpdateOwnedUpgrade(home, environment) {
     const ownerText = environment.YUI_UPDATE_HANDOVER_OWNER_PID;
     const ownerPid = ownerText === undefined ? Number.NaN : Number(ownerText);