@zq-silk/yui 0.14.2 → 0.15.1

package/ARCHITECTURE.md

@@ -366,18 +366,33 @@ cleanup revalidates ownership and fails safely when concurrent state changes;
 manual retry is the recovery boundary rather than another durable state
 machine.
 
-Storage still records layout, aggregate, and record-family versions, but this
-release deliberately re-baselines all three axes at the current contract. The
-production migration registry is empty. Ordinary opening, Controller startup,
-doctor, update preflight, and the storage upgrade entry point therefore accept
-only an exact current manifest and current record shapes. An older Home is
-unsupported and must not be normalized, rewritten, or switched in place.
-
-SQLite bootstrap DDL is an implementation detail for initializing a fresh Home.
-Its ledger must be complete on every later open; a partial or older ledger is
-rejected rather than advanced. This keeps one durable model for Turn,
-TaskRoleSessionSet, WorkMailbox, and Provider Runtime Binding and prevents an
-old writer or migration transform from recreating removed delivery state.
+Storage has one compatibility authority: the highest contiguous, checksummed
+version in SQLite's append-only migration ledger. The CLI exposes that release's
+current version and minimum supported migration version. Ordinary opening and
+Controller startup accept only the exact current version; historical decoding
+and rewriting exist only inside `yui upgrade` and the migration phase of
+`yui update`.
+
+Yui 0.15.0 establishes storage version 1 as the clean single-version baseline:
+`schema.json` has no authority, and layout/aggregate/record-version axes are
+absent from Home metadata. Pre-0.15.0 Homes are outside the migration floor.
+Future releases append one immutable migration per storage version and retain
+the complete chain from version 1. A fresh Home replays that same chain, so
+fresh and upgraded Homes converge on one current schema.
+
+The staged `upgrade --update-preflight` / `--update-apply` machine handshake is
+also a compatibility contract: target releases keep its established outcomes
+and required fields, plus the parent-owned handover-lock proof, readable by
+every updater released since version 1. Additive detail is allowed; renaming or
+removing consumed fields would strand an otherwise valid cross-version
+migration path.
+
+An upgrade runs only while the Controller is quiesced, creates a consistent
+database backup, applies all missing migrations in one transaction, and
+validates the current record model before writes resume. A missing or changed
+ledger row, a migration gap, a Home below the migration floor, a future Home,
+or malformed data fails closed. Runtime code contains no dual readers,
+historical normalizers, or independently writable compatibility state.
 
 The Web control room is loopback-only and never receives Controller socket
 credentials. It presents durable records and native terminal access without

package/README.md

@@ -15,6 +15,10 @@ execution and continuity, but they are not competing sources of Task truth.
 
 The current implementation restores the useful Role/Agent/session and CLI framework without restoring the later data-maintenance, lease, schedule, and recovery-ledger systems.
 
+The [target architecture handbook](docs/architecture/README.md) preserves the
+2026-09-06 design baseline for the upcoming refactor; it does not describe
+already implemented behavior.
+
 ## Requirements
 
 - Node.js 20.17+, 22.9+, or 24.x
@@ -72,12 +76,12 @@ export YUI_HOME=/absolute/path/to/yui-home
 yui setup
 ```
 
-The home contains `schema.json`, the authoritative SQLite database `yui.db`,
-Project Catalog and knowledge, and Controller discovery files. Stable Project
-checkouts and managed worktrees live under the configured workspace, outside
-Yui home. Runtime storage accepts only the exact current contract; it never
-falls back to `state.json`, normalizes an older shape, or repairs a historical
-Home in place.
+The home contains the authoritative SQLite database `yui.db`, Project Catalog
+and knowledge, and Controller discovery files. Stable Project checkouts and
+managed worktrees live under the configured workspace, outside Yui home.
+Legacy `schema.json` and `state.json` files are evidence only. Runtime storage
+accepts only the exact current contract; supported earlier storage versions
+enter only through the explicit upgrade boundary.
 
 Every Task-owned record family allocates a monotonically increasing local ID
 inside its Task. Different Tasks may therefore both contain `work-item-1`,
@@ -89,43 +93,41 @@ and `task integration start`, keep their subordinate IDs local to that Task.
 Candidate IDs are local to their WorkItem and carry both Task and WorkItem
 provenance.
 
-Yui records layout, aggregate, and per-record-family versions in `schema.json`.
-Runtime admission has only two outcomes: exact current, or rejected; a
-Controller never migrates storage while serving work. `yui upgrade --dry-run`
-is read-only, while `yui upgrade` validates only the release's exact current
-contract. Older, newer, incomplete, and malformed Homes fail closed.
+Yui has one Home storage version, recorded by the append-only SQLite migration
+ledger. Every CLI reports both its current storage version and its minimum
+supported migration version. Runtime admission still has only two outcomes:
+exact current, or rejected; a Controller never migrates storage while serving
+work. `yui upgrade --dry-run` is read-only. `yui upgrade` quiesces a running
+Controller, creates a consistent backup, applies every missing migration in
+one transaction, validates the current contract, and then restarts the
+Controller when it was running before the upgrade.
 
 `yui update` stages and pins one exact package, runs that staged binary's
 storage preflight, stops the exact old Controller, activates the same artifact,
-verifies the installed binary and current Home, and starts the replacement
-Controller. If the staged binary does not support the current Home exactly,
-the update stops before activation and leaves both the Home and current
-installation unchanged.
-
-To retain an old Home, keep it byte-for-byte and open it only with its original
-Yui version for read-only inspection. For unfinished work, initialize a new
-Home and let the Operator create a new Task from the old Task's objective,
-relevant WorkItems, current repository state, and available exact Turn results.
-The Operator creates new identities and may consult available exact Turn
-results; it does not import old runtime/session state or pretend that the old
-Task continued.
+applies the staged release's migration chain when required, verifies the
+installed binary and current Home, and starts the replacement Controller. A
+Home inside the staged release's supported range can upgrade directly across
+multiple versions without installing intermediate releases. A newer Home, a
+Home below the migration floor, an incomplete migration ledger, or malformed
+data fails closed without a guessed repair.
+
+Yui 0.15.0 establishes storage version 1 and the migration floor. Homes created
+by earlier releases, including 0.14.2, are not on this compatibility line:
+preserve them for inspection with their matching Yui release or initialize a
+new Home. From 0.15.0 onward, each release retains the complete chain, so later
+`yui update` invocations can cross versions directly.
 
 See [Task-local identity](docs/task-local-identity.md) for the current reference
 contract.
 
-Schema work across Tasks is not serialized: any Task may advance a version axis
-(`layout`, `aggregate`, or a `record` family) on its own isolated branch without
-waiting for another Task's schema change to land. The later-integrating branch
-owns the reconciliation — rebasing onto the latest project head, resolving schema
-and code conflicts, re-advancing the schema versions and record-version-map
-entries the rebase requires, rebuilding and re-validating the wiring, and
-re-running the isolated E2E and docs. This is a deliberate scheduling trade-off
-that avoids cross-Task blocking, not an accident to repair ad hoc. The
-current manifest descriptor map is re-derived against the newest head, while the
-post-baseline descriptor snapshot remains frozen. If another Task later lands a
-record-schema change, the integrating branch must rebase, allocate the next
-current contract without collision, and re-test to convergence. It does not
-preserve an upgrade path for the displaced intermediate contract.
+Schema work across Tasks is not serialized: any Task may propose the next
+storage migration on its own isolated branch without waiting for another Task's
+schema change to land. The later-integrating branch owns the reconciliation:
+rebase onto the latest project head, preserve every already released migration
+unchanged, allocate the next contiguous storage version, resolve schema and code
+conflicts, and re-run the bounded validation. A migration may update physical
+tables and current record payloads together; it must not introduce another
+writable compatibility axis.
 
 Yui provides four reusable Worker Profile definitions through
 `yui config profile reset`; minimum setup makes each one inherit the current
@@ -601,7 +603,11 @@ future launch. Each Turn and native Role Session stores the complete actual
 agent, adapter, model, effort, Profile access intent, exact writable Projects,
 permission strategy and native options, workspace, context, and source desired revision. Updating,
 switching, or clearing Role overrides never
-hot-mutates an existing process. `task context`, Role views, Turn history,
+hot-mutates an existing process. When the Role has a live Session,
+`task role update`, `config role update`, and `config agent update` report that
+Session once and require `--yes`, so the change is recorded in the knowledge
+that it applies to the next activation; stopping the Session applies it
+immediately instead. `task context`, Role views, Turn history,
 Events, and Web show desired/effective revisions, Profile intent, permission, and
 pending next-launch drift.
 
@@ -911,16 +917,19 @@ Session/Driver lifecycle facts.
 Global Operator and global Role sessions remain native interactive CLIs. Codex
 connects that TUI to the default shared App Server, so the same thread can move
 between Yui and Desktop without transferring a rollout writer or losing its
-Global Context entry:
+Global Context entry. A thin Host in the same pane transparently forwards the
+native TUI's App Server connection and acknowledges its exact `thread/start`
+or `thread/resume` response. Yui records that Thread ID before the first user
+Turn, without depending on `notify`, scanning history, or creating a bootstrap
+message. The attachment outlives Controller restarts but exits with the TUI:
 
 ```sh
 yui session enter <global-role>
 ```
 
-`yui update` accepts only the current Home contract. Unsupported older Homes
-remain untouched; inspect those with a compatible Yui version and let the
-current Operator recreate unfinished intent as new Tasks in a newly initialized
-Home.
+`yui update` accepts either the current Home contract or any valid historical
+contract at or above the staged CLI's minimum supported migration version.
+Unsupported newer Homes and Homes below that floor remain untouched.
 
 tmux fixes a pane's history capacity when that pane is created. Existing panes
 retain their configured capacity; managed runtime output remains observable in
@@ -937,12 +946,23 @@ running, Yui asks before stopping it and switching the conversation. On a
 cross-Agent switch, the saved model and effort are reused unless the user
 explicitly chooses to update them.
 
-The Role's active binding is desired state for the next compatible launch. A
+Window existence does not imply a running Agent: `pane_dead=0` is live and
+`pane_dead=1` is an exited, retained diagnostic pane. Status reads never delete
+that evidence, and unreadable state is an error rather than proof of exit.
+An explicit launch can rebuild the exact dead window; tmux refuses to replace
+a live pane. An unidentified live Operator still cannot be overwritten.
+
+The Role's active binding is desired state for the next launch. A
 running Turn and its native Session continue under their immutable
-effective snapshot even if the Role is edited or switched. Resume is allowed
-only when the complete effective snapshot and workspace remain compatible;
-otherwise Yui starts a new Session after the old process has stopped and keeps
-the terminal Session's immutable effective snapshot in history. Managed
+effective snapshot even if the Role is edited or switched. Resume is refused
+only when continuation is impossible: no recoverable native Session, a
+different Agent or adapter, or a different physical workspace. Desired launch
+configuration such as model, effort, permission, Role context, Skills, or
+declared write scope shapes the next activation instead of ending the Session,
+and Turn-scoped facts such as ReviewRound identity or candidate commits never
+affect reuse. When continuation is impossible Yui starts a new Session after
+the old process has stopped and keeps the terminal Session's immutable
+effective snapshot in history. Managed
 Sessions invoke the ordinary `yui` command; their Manifest and durable
 Role/Turn fences authenticate scope while protocol and storage compatibility
 allow a CLI package or Controller upgrade in place. Exact internal callbacks
@@ -952,8 +972,9 @@ Use `yui config role unbind <global-role> <agent-id>` or `yui task role unbind <
 
 Claude session IDs are preallocated at launch. Codex discovers its native
 thread identity from App Server responses. Managed Task Turns use structured
-Provider observations for both CLIs. Global interactive Codex sessions may
-still use its `notify` callback for conversation presentation.
+Provider observations for both CLIs. Global Codex uses the native TUI's exact
+App Server startup response and the existing Host acknowledgement. Legacy
+global `notify` callbacks cannot register a Session or change its lifecycle.
 
 Automated lifecycle and delivery decisions use structured Provider events or
 supported Hook payloads, persisted identities, usage snapshots, tmux process state, receipts, and pane
@@ -1003,9 +1024,10 @@ hiding the resources that remain. Use `--all` to include discovered Yui homes.
 `controller restart` replaces the Controller process and its scheduler/socket services with the currently installed Yui version. It can recover a lost discovery record only when the old process still matches the current UID, Controller entrypoint, physical Home, PID, and process-start identity. It does not stop or restart managed tmux/Agent sessions.
 
 Successful `setup` and `update` commands ensure that the current Home has a
-running Controller, starting one when the Home was previously idle. `upgrade`
-is read-only and does not start a Controller. `update` replaces an
-already-running Controller only after the new binary passes its health checks.
+running Controller, starting one when the Home was previously idle. A
+successful `upgrade` restores a Controller only when it stopped one for the
+migration. `update` starts the replacement only after migration and health
+checks pass.
 
 Its recovery reconciliation runs every 120 seconds by default. Normal durable state changes enqueue a Task, Role, or Operator key and return immediately; keys received in the same fixed 100 ms window trigger one non-overlapping targeted pass. Operator presentation has an independent lane, so a blocked Task workspace operation cannot delay a user question. Periodic Git/worktree work is limited to Tasks with durable Task-mailbox work, while active Role liveness uses one tmux inventory. Structured Agent Driver observations, whether received from native provider events or supported Hooks, are exact-fenced before they reach the durable runtime inbox. A terminal Turn observation atomically records the exact Turn result. Durable mailboxes freeze the current batch while new signals merge into the next batch. Task-orchestration failures retain the exact Controller-owned processing batch for two bounded fast retries and later periodic recovery; a successful retry completes that batch before newer pending work is claimed. Recommended InputRequest and pending Turn deadlines share one nearest-deadline selector and therefore do not wait for the recovery interval. Explicit `task reconcile` still requests an immediate recovery pass. The retained loop is:
 
@@ -1097,15 +1119,17 @@ yui project reset|replace|retire|delete
 ```
 
 `yui update` stages the newly published package side by side and asks that exact
-binary to verify the current Home. Only then does it stop the exact old
-Controller, activate the same concrete package version, validate the actually
-installed binary and Home, and start the replacement Controller. Unsupported
-Homes block preflight and remain untouched.
-
-`yui upgrade --dry-run` validates an exact current Home without writing.
-`yui upgrade` performs the same validation. This release provides no migration
-from older aggregate contracts; use their matching Yui version or initialize a
-new Home.
+binary to classify the Home. Only then does it stop the exact old Controller,
+activate the same concrete package version, apply the complete missing
+migration chain when needed, validate the actually installed binary and Home,
+and start the replacement Controller. Unsupported Homes block preflight and
+remain untouched.
+
+`yui upgrade --dry-run` prints the ordered migration plan without writing.
+`yui upgrade` creates a timestamped SQLite backup and upgrades any valid Home
+from the CLI's minimum supported storage version to its current version. Yui
+0.15.0 is storage version 1; pre-0.15.0 Homes remain outside that migration
+line and are never rewritten.
 
 Agent environment bindings store process-environment variable names, never secret values. Adapter-owned lifecycle arguments cannot be overridden through raw arguments.
 

package/dist/cli/commandCatalog.js

@@ -118,7 +118,7 @@ const agentChildren = [
         name: "update",
         summary: "Update a configured Agent.",
         usage: "yui config agent update <id> [--adapter <adapter>] [--command <command>] [--arg <arg> ... | --clear-args] [--env TARGET=PROCESS_NAME ... | --clear-env]",
-        options: ["--adapter", "--command", "--arg", "--clear-args", "--env", "--clear-env"],
+        options: ["--adapter", "--command", "--arg", "--clear-args", "--env", "--clear-env", "--yes"],
         optionValues: { "--adapter": supportedAgentAdapterIds() },
         executableOptions: ["--command"]
     },
@@ -170,7 +170,7 @@ const roleChildren = [
         summary: "Update a global Role.",
         usage: "yui config role update <name> [profile options] [clear options]",
         options: ["--agent", "--workspace", ...roleProfileOptions, ...roleAgentOptions,
-            ...roleProfileClearOptions, ...roleAgentClearOptions],
+            ...roleProfileClearOptions, ...roleAgentClearOptions, "--yes"],
         optionValues: roleAgentOptionValues,
         fileOptions: ["--workspace"]
     },
@@ -578,7 +578,7 @@ const taskChildren = [
                 summary: "Update a Task Role; Agent settings target the named or active binding without switching it.",
                 usage: "yui task role update <task> <role> [--profile <id>] [--agent <id>] [Role and Agent settings]",
                 options: ["--profile", "--agent", ...roleProfileOptions, ...roleAgentOptions,
-                    ...roleProfileClearOptions, ...roleAgentClearOptions],
+                    ...roleProfileClearOptions, ...roleAgentClearOptions, "--yes"],
                 optionValues: roleAgentOptionValues
             },
             { name: "remove", summary: "Remove a Task Role.", usage: "yui task role remove <task> <role>" },
@@ -995,7 +995,7 @@ export const ROOT_COMMAND = buildNode({
         { name: "update", summary: "Install the latest published Yui package globally." },
         {
             name: "upgrade",
-            summary: "Validate this Home against the exact current storage contract.",
+            summary: "Plan or apply supported storage migrations for this Home.",
             usage: "yui upgrade [--dry-run]",
             options: ["--dry-run"]
         },
@@ -1132,7 +1132,7 @@ export const ROOT_COMMAND = buildNode({
                 ...CONFIG_DOMAINS.map(durableConfigDomainNode),
                 {
                     name: "agent",
-                    summary: "Manage configured native Agent CLIs; launch-setting changes require affected Sessions to be stopped.",
+                    summary: "Manage configured native Agent CLIs; launch-setting changes apply to the next Session activation.",
                     examples: ["yui config agent list", "yui config agent capabilities codex"],
                     sections: [
                         { id: "inspect", title: "Inspect", entries: ["list", "show", "capabilities"] },
@@ -1152,7 +1152,7 @@ export const ROOT_COMMAND = buildNode({
                 },
                 {
                     name: "role",
-                    summary: "Manage reusable global Roles and desired Agent launch configuration for the next compatible Session.",
+                    summary: "Manage reusable global Roles and desired Agent launch configuration for the next Host activation.",
                     examples: ["yui config role list", "yui config role show operator"],
                     sections: [
                         { id: "inspect", title: "Inspect", entries: ["list", "show"] },

package/dist/cli/updateCommand.js

@@ -5,9 +5,9 @@ import { runUpdate } from "./updateOrchestrator.js";
  * Run `yui update` as a side-by-side, recoverable orchestration.
  *
  * The new package is staged beside the live install and used to run a read-only
- * preflight against the target Home. Only the exact current storage contract is
- * accepted; the exact Controller handoff then promotes and verifies the binary
- * without changing the Home. Older Homes remain untouched.
+ * preflight against the target Home. A current Home proceeds directly; a Home
+ * inside the staged release's supported range is migrated after the exact
+ * Controller handoff and before post-update verification.
  *
  * Returns a process exit code: 0 on success or already-current, 5 on abort.
  */
@@ -27,15 +27,23 @@ export function renderUpdateResult(result) {
             case "already-current":
                 return "Yui is already up to date; nothing to install.";
             case "updated":
-                return `Updated Yui to ${result.version}; the current Home was not modified.`;
+                return result.backupPath === undefined
+                    ? `Updated Yui to ${result.version}; storage was already current.`
+                    : `Updated Yui to ${result.version} and migrated storage. Backup: ${result.backupPath}`;
             case "aborted":
                 return [
                     `Update aborted during ${result.phase}: ${result.message}`,
-                    result.recoverable
-                        ? "The current install and Home remain usable."
-                        : result.phase === "activate-binary"
-                            ? "The Home was unchanged, but binary health is unknown; do not assume the current install is usable."
-                            : "Manual recovery is required (see below).",
+                    result.phase === "migrate-storage"
+                        || (result.phase === "post-verify" && result.recoverable)
+                        ? "The target binary is installed; the Home remains quiesced pending successful verification."
+                        : result.recoverable
+                            ? "The current install and Home remain usable."
+                            : result.phase === "activate-binary"
+                                ? "The Home was unchanged, but binary health is unknown; do not assume the current install is usable."
+                                : "Manual recovery is required (see below).",
+                    ...(result.backupPath === undefined
+                        ? []
+                        : [`Storage backup: ${result.backupPath}`]),
                     `Action: ${result.action}`
                 ].join("\n");
         }

package/dist/cli/updateOrchestrator.js

@@ -1,8 +1,10 @@
 /**
- * Side-by-side `yui update` orchestration for the current storage contract.
+ * Side-by-side `yui update` orchestration for the supported storage range.
  *
- * The staged binary proves an exact-current Home before the exact Controller
- * is stopped and the replacement is activated, verified, and restarted.
+ * The staged binary proves either an exact-current Home or a complete
+ * migration path before the exact Controller is stopped. The replacement is
+ * then activated, any required storage migration is applied, and the result is
+ * verified before the Controller is restarted.
  */
 export function runUpdate(ports, options) {
     let staged;
@@ -61,6 +63,26 @@ function runStagedUpdate(ports, staged, home) {
             ...(preflight.sceneUnchanged === true ? { sceneUnchanged: true } : {})
         };
     }
+    if (preflight.status === "migration-ready" && ports.migrateStorage === undefined) {
+        return {
+            outcome: "aborted",
+            phase: "preflight",
+            message: "The staged binary requires a storage migration, but no migration operation is available.",
+            action: "Use the complete Yui updater or run the staged release's `yui upgrade` explicitly.",
+            recoverable: true,
+            version: staged.version
+        };
+    }
+    if (preflight.status === "migration-ready" && !hasCompleteControllerLifecycle(ports)) {
+        return {
+            outcome: "aborted",
+            phase: "preflight",
+            message: "Storage migration requires a complete, fenced Controller handoff.",
+            action: "Provide status, exact stop, replacement start, and exact restore operations.",
+            recoverable: true,
+            version: staged.version
+        };
+    }
     let releaseHandover;
     try {
         releaseHandover = ports.beginControllerHandover?.(home);
@@ -79,13 +101,13 @@ 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);
+        return activateAndVerify(ports, staged, home, captured.lifecycle, preflight);
     }
     finally {
         releaseHandover?.();
     }
 }
-function activateAndVerify(ports, staged, home, lifecycle) {
+function activateAndVerify(ports, staged, home, lifecycle, preflight) {
     try {
         ports.activateBinary(staged);
     }
@@ -99,19 +121,46 @@ function activateAndVerify(ports, staged, home, lifecycle) {
             version: staged.version
         });
     }
+    let migration;
+    if (preflight.status === "migration-ready") {
+        try {
+            migration = ports.migrateStorage(staged, home);
+            if (!isStorageMigrationResult(migration)) {
+                throw new Error("Storage migration returned a malformed result.");
+            }
+        }
+        catch (error) {
+            return {
+                outcome: "aborted",
+                phase: "migrate-storage",
+                message: `Storage migration failed: ${messageOf(error)}`,
+                action: "The target Yui binary is installed and the Home remains quiesced. "
+                    + "Resolve the reported problem, rerun `yui upgrade`, then verify "
+                    + "`yui doctor` before starting the Controller.",
+                recoverable: true,
+                version: staged.version
+            };
+        }
+    }
     try {
         ports.verify(staged, home);
     }
     catch (error) {
+        const storageMigrated = preflight.status === "migration-ready";
         const failure = {
             outcome: "aborted",
             phase: "post-verify",
             message: `Post-update health check failed: ${messageOf(error)}`,
             action: binaryHealthUncertainAction(),
-            recoverable: false,
-            version: staged.version
+            recoverable: storageMigrated,
+            version: staged.version,
+            ...(migration?.backupPath === undefined
+                ? {}
+                : { backupPath: migration.backupPath })
         };
-        return restoreControllerOrReport(ports, home, lifecycle, failure);
+        return storageMigrated
+            ? failure
+            : restoreControllerOrReport(ports, home, lifecycle, failure);
     }
     if (lifecycle.ensureRunning) {
         try {
@@ -119,6 +168,7 @@ function activateAndVerify(ports, staged, home, lifecycle) {
         }
         catch (error) {
             const unknownActive = isUnknownActiveControllerFailure(error);
+            const storageMigrated = preflight.status === "migration-ready";
             const failure = {
                 outcome: "aborted",
                 phase: "post-verify",
@@ -127,21 +177,27 @@ function activateAndVerify(ports, staged, home, lifecycle) {
                     : "The replacement Controller could not start after activation and verification"}: ${messageOf(error)}.`,
                 action: unknownActive
                     ? unknownActiveControllerAction(home)
-                    : lifecycle.wasRunning
-                        ? "Keep the Home quiesced and restore the captured Controller identity before retrying."
-                        : "Verify the activated binary, then start the Controller explicitly.",
-                recoverable: false,
+                    : storageMigrated
+                        ? "Keep the Home quiesced, verify the activated binary, then start the current Controller explicitly."
+                        : lifecycle.wasRunning
+                            ? "Keep the Home quiesced and restore the captured Controller identity before retrying."
+                            : "Verify the activated binary, then start the Controller explicitly.",
+                recoverable: storageMigrated && !unknownActive,
                 version: staged.version,
-                controllerOwnershipUnknown: true
+                ...(migration?.backupPath === undefined
+                    ? {}
+                    : { backupPath: migration.backupPath }),
+                ...(unknownActive ? { controllerOwnershipUnknown: true } : {})
             };
-            return unknownActive
+            return unknownActive || storageMigrated
                 ? failure
                 : restoreControllerOrReport(ports, home, lifecycle, failure);
         }
     }
     return {
         outcome: "updated",
-        version: staged.version
+        version: staged.version,
+        ...(migration?.backupPath === undefined ? {} : { backupPath: migration.backupPath })
     };
 }
 function captureControllerLifecycle(ports, version, home) {
@@ -259,6 +315,16 @@ function isControllerLifecycleStatus(value) {
 function isControllerStopResult(value) {
     return isRecord(value) && typeof value.stopped === "boolean";
 }
+function hasCompleteControllerLifecycle(ports) {
+    return ports.controllerStatus !== undefined
+        && ports.stopController !== undefined
+        && ports.startController !== undefined
+        && ports.restoreController !== undefined;
+}
+function isStorageMigrationResult(value) {
+    return isRecord(value)
+        && (value.backupPath === undefined || typeof value.backupPath === "string");
+}
 function isPositivePid(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }