@zq-silk/yui 0.13.9 → 0.14.0

package/dist/cli/updateOrchestrator.js

@@ -1,55 +1,12 @@
 /**
- * The `yui update` orchestration.
+ * Side-by-side `yui update` orchestration for the current storage contract.
  *
- * The previous implementation ran `npm install --global` *first*, which is
- * self-contradictory with "on failure the old CLI and Home are both unchanged":
- * once the global package is replaced there is nothing to fall back to. This
- * orchestrator replaces that with a side-by-side staging flow:
- *
- *   stage (side-by-side, never touches the live install)
- *     -> preflight  (the STAGED new binary classifies the target Home read-only)
- *     -> current/compatible: exact Controller stop -> activate the same binary
- *     -> migration-required: authoritative offline inventory -> recoverable
- *        storage switch -> activate the same binary
- *     -> post-verify through the activated binary, then replacement Controller
- *
- * ## Rollback boundary (NARROWED — no versioned binary pointer is introduced)
- *
- * The managed Session launcher is an in-place forwarder, not a versioned package
- * pointer, so this release does NOT claim binary+Home dual-resource atomicity.
- * The guarantees it DOES make, precisely:
- *
- *  - **Staging is isolated.** `stage` installs side-by-side and never mutates the
- *    live global install, so a stage/preflight failure leaves the old binary and
- *    the Home byte-for-byte unchanged.
- *  - **Compatible activation does not switch the Home.** The fast path stops the
- *    exact Controller, promotes the staged artifact, and verifies a compatible
- *    current-model loader without copy, backup, rename, or Session wait.
- *  - **Storage activation is recoverable until writes resume.** The Home switch is
- *    atomic with a timestamped backup (see the migration engine). Before the new
- *    version resumes writes, recovery is a single restore of that backup.
- *  - **No auto-downgrade after writes.** Once the new version has resumed writes
- *    (a new Controller/first write against the migrated Home), the tool never
- *    auto-reverts; the migrated Home is authoritative.
- *
- * The one window it CANNOT make atomic is: storage already switched to the new
- * schema, but binary promotion then fails. Because the axes are version-gated,
- * the old binary fail-closes on the new Home rather than misreading it; recovery
- * is to restore the timestamped Home backup (the exact command is printed), after
- * which the old binary works again. This is stated in the failure output, not
- * hidden behind a false atomicity claim.
- */
-import { isAbsolute } from "node:path";
-import { switchProgressPath } from "../storage/upgrade/switchProgress.js";
-import { upgradeReceiptPath } from "../storage/upgrade/upgradeReceipt.js";
-/**
- * Run the update orchestration. Never performs an irreversible step before the
- * read-only preflight has proven the Home is safe, and reports the precise phase
- * plus a recovery action on any failure.
+ * The staged binary may only prove that the target Home already implements the
+ * exact current contract. Updating never rewrites, normalizes, migrates, or
+ * repairs storage. An older Home stays untouched so an Operator can inspect it
+ * with its original Yui version and create a new current Task explicitly.
  */
 export function runUpdate(ports, options) {
-    const home = options.home;
-    // 1) Stage side-by-side. A failure here leaves the live install untouched.
     let staged;
     try {
         staged = ports.stage();
@@ -66,27 +23,19 @@ export function runUpdate(ports, options) {
     let result;
     let cleanupWarning;
     try {
-        result = runStagedUpdate(ports, staged, home);
+        result = runStagedUpdate(ports, staged, options.home);
     }
     finally {
         try {
             ports.cleanup(staged);
         }
         catch (error) {
-            // Cleanup is deliberately best-effort. Once the orchestrator has
-            // determined an update/abort/ambiguous result, a staging I/O failure must
-            // not replace that authoritative outcome or turn it into a generic error.
             cleanupWarning = `Staging cleanup could not be completed: ${messageOf(error)}`;
         }
     }
     return cleanupWarning === undefined ? result : { ...result, cleanupWarning };
 }
-/** Run the staged flow; cleanup is owned by the caller so warnings are retained. */
 function runStagedUpdate(ports, staged, home) {
-    // 2) Preflight — the staged binary inspects the Home read-only; no switch.
-    // A preflight port that throws unexpectedly (e.g. an I/O fault) is not a safe
-    // green light: treat it as a blocked preflight (recoverable, no switch) rather
-    // than letting the exception escape (R4-F1).
     let preflight;
     try {
         preflight = ports.preflight(staged, home);
@@ -96,7 +45,7 @@ function runStagedUpdate(ports, staged, home) {
             outcome: "aborted",
             phase: "preflight",
             message: `Preflight failed unexpectedly: ${messageOf(error)}`,
-            action: "The current install and Home are unchanged. Investigate the staged binary and retry.",
+            action: "The current install and Home are unchanged. Inspect the staged binary and retry.",
             recoverable: true,
             version: staged.version
         };
@@ -110,9 +59,7 @@ function runStagedUpdate(ports, staged, home) {
             recoverable: true,
             version: staged.version,
             ...(preflight.blockers === undefined ? {} : { blockers: preflight.blockers }),
-            ...(preflight.retryCommand === undefined
-                ? {}
-                : { retryCommand: preflight.retryCommand }),
+            ...(preflight.retryCommand === undefined ? {} : { retryCommand: preflight.retryCommand }),
             ...(preflight.sceneUnchanged === true ? { sceneUnchanged: true } : {})
         };
     }
@@ -125,234 +72,76 @@ function runStagedUpdate(ports, staged, home) {
             outcome: "aborted",
             phase: "coordination",
             message: `Controller handover could not be acquired: ${messageOf(error)}`,
-            action: "Another maintenance operation owns this Home. Wait for it to finish, then retry; no Controller, binary, or storage change was made.",
+            action: "Wait for the other maintenance operation to finish, then retry; nothing was changed.",
             recoverable: true,
             version: staged.version
         };
     }
-    let releaseStorageWriteFence;
-    const migrationPath = preflight.status === "in-place-migration"
-        || preflight.status === "migration-required"
-        || preflight.status === "migratable";
-    if (migrationPath && ports.beginControllerHandover !== undefined) {
-        if (ports.beginStorageWriteFence === undefined) {
-            releaseHandover?.();
-            return {
-                outcome: "aborted",
-                phase: "coordination",
-                message: "The update lifecycle does not provide a storage write-admission fence.",
-                action: "Use an updater that holds write admission through storage migration, binary activation, and loader verification; no Controller, binary, or storage change was made.",
-                recoverable: true,
-                version: staged.version
-            };
-        }
-        try {
-            releaseStorageWriteFence = ports.beginStorageWriteFence(home);
-        }
-        catch (error) {
-            releaseHandover?.();
-            return {
-                outcome: "aborted",
-                phase: "coordination",
-                message: `Storage write admission could not be acquired: ${messageOf(error)}`,
-                action: "Another maintenance operation owns this Home. Wait for it to finish, then retry; no Controller, binary, or storage change was made.",
-                recoverable: true,
-                version: staged.version
-            };
-        }
-    }
-    const resumeWrites = () => {
-        releaseStorageWriteFence?.();
-        releaseStorageWriteFence = undefined;
-    };
     try {
-        return runPreflightedUpdate(ports, staged, home, preflight, resumeWrites);
+        const captured = captureControllerLifecycle(ports, staged.version, home);
+        if ("outcome" in captured)
+            return captured;
+        return activateAndVerify(ports, staged, home, captured.lifecycle);
     }
     finally {
-        resumeWrites();
         releaseHandover?.();
     }
 }
-function runPreflightedUpdate(ports, staged, home, preflight, resumeWrites) {
-    // Capture and stop the old Controller exactly once after preflight but
-    // before either storage activation or binary promotion. This parent update
-    // process remains the sole lifecycle owner for both binary-only and
-    // migratable updates.
-    const lifecycle = captureControllerLifecycle(ports, staged.version, home);
-    if ("outcome" in lifecycle)
-        return lifecycle;
-    if (preflight.status === "already-current" || preflight.status === "compatible") {
-        // Current and all-compatible chains share the lean path: no Home copy,
-        // backup, rename, or command replay. The exact Controller handoff prevents
-        // old/new writers from overlapping while the same staged artifact activates.
-        return activateAndVerify(ports, staged, home, undefined, lifecycle.lifecycle, preflight.status === "compatible" ? "compatible-fast" : "current-fast", resumeWrites);
-    }
-    // 3) Activate storage — recoverable: atomic switch + timestamped backup. An
-    // activation port that throws unexpectedly may have committed the switch
-    // before failing, so its state is UNKNOWN — resolve it as ambiguous from the
-    // durable on-disk evidence, never let the exception escape as a false clean
-    // failure (R4-F1 / P1-2).
-    let activation;
-    try {
-        activation = ports.activateStorage(staged, home);
-    }
-    catch (error) {
-        return resolveAmbiguousActivation(ports, staged, home, `the activation step threw unexpectedly: ${messageOf(error)}`, preflight.status === "in-place-migration"
-            ? { kind: "in-place", migration: preflight.sqliteMigration }
-            : { kind: "switch" }, lifecycle.lifecycle, resumeWrites);
-    }
-    if (activation.status === "blocked") {
-        const failure = {
-            outcome: "aborted",
-            phase: "activate-storage",
-            message: activation.message,
-            action: activation.action,
-            // The engine guarantees the source Home is unchanged on a blocked/failed
-            // migration, and the binary has not been promoted, so this is recoverable.
-            recoverable: true,
-            version: staged.version,
-            ...(activation.blockers === undefined ? {} : { blockers: activation.blockers }),
-            ...(activation.retryCommand === undefined
-                ? {}
-                : { retryCommand: activation.retryCommand }),
-            ...(activation.sceneUnchanged === true ? { sceneUnchanged: true } : {})
-        };
-        // The child was externally quiesced by this parent. A clean pre-switch
-        // refusal therefore restores the exact captured identity; an ambiguous
-        // activation is handled separately and never restores blindly.
-        resumeWrites();
-        return restoreBeforeSwitchOrReport(ports, home, lifecycle.lifecycle, undefined, false, failure);
-    }
-    if (activation.status === "ambiguous") {
-        // The activation child left no parseable receipt: the switch may or may not
-        // have committed. Resolve the true state from the durable on-disk evidence
-        // and report an explicit manual recovery — never a false "recoverable".
-        return resolveAmbiguousActivation(ports, staged, home, activation.detail, preflight.status === "in-place-migration"
-            ? { kind: "in-place", migration: preflight.sqliteMigration }
-            : { kind: "switch" }, lifecycle.lifecycle, resumeWrites);
-    }
-    if (activation.status === "migrated" && !isValidBackupPath(activation.backupPath)) {
-        // A migrated/upgraded success without a concrete backup path violates
-        // the recoverable storage-activation contract. Resolve it through the
-        // existing durable receipt/schema probe instead of inferring that the
-        // Home was untouched.
-        return resolveAmbiguousActivation(ports, staged, home, "the activation reported migrated without a non-empty absolute backupPath", { kind: "switch" }, lifecycle.lifecycle, resumeWrites);
-    }
-    const backupPath = activation.status === "migrated" ? activation.backupPath : undefined;
-    const path = activation.status === "migrated-in-place"
-        ? "in-place-migration"
-        : "offline-migration";
-    // 4/5) Promote the binary, then post-verify with the new binary's loader.
-    return activateAndVerify(ports, staged, home, backupPath, lifecycle.lifecycle, path, resumeWrites);
-}
-/**
- * Promote the staged binary and run the new-binary health check. This is the
- * last, non-atomic step: after storage has switched, binary promotion cannot be
- * made atomic with it, so a failure here is reported with the exact backup-based
- * recovery and is NOT auto-reverted once the new version would resume writes.
- */
-function activateAndVerify(ports, staged, home, storageBackupPath, lifecycle, path, resumeWrites) {
-    const inPlaceCommitted = path === "in-place-migration";
+function activateAndVerify(ports, staged, home, lifecycle) {
     try {
         ports.activateBinary(staged);
     }
     catch (error) {
-        const failure = {
+        return restoreControllerOrReport(ports, home, lifecycle, {
             outcome: "aborted",
             phase: "activate-binary",
             message: `Failed to activate the new binary: ${messageOf(error)}`,
-            action: inPlaceCommitted
-                ? inPlaceMigrationRecoveryAction(home)
-                : storageBackupPath === undefined
-                    ? binaryActivationUncertainAction()
-                    : postSwitchRecoveryAction(home, storageBackupPath),
-            // Once binary activation begins, its outcome is not knowable from a
-            // failed npm process. Home-not-switched is useful evidence, but it does
-            // not prove the current installation remains usable.
+            action: binaryActivationUncertainAction(),
             recoverable: false,
-            version: staged.version,
-            ...(storageBackupPath === undefined ? {} : { storageBackupPath })
-        };
-        if (!inPlaceCommitted && storageBackupPath === undefined)
-            resumeWrites();
-        return restoreBeforeSwitchOrReport(ports, home, lifecycle, storageBackupPath, inPlaceCommitted || storageBackupPath !== undefined, failure);
+            version: staged.version
+        });
     }
     try {
         ports.verify(staged, home);
     }
     catch (error) {
-        const failure = {
+        return restoreControllerOrReport(ports, home, lifecycle, {
             outcome: "aborted",
             phase: "post-verify",
             message: `Post-update health check failed: ${messageOf(error)}`,
-            action: inPlaceCommitted
-                ? inPlaceMigrationRecoveryAction(home)
-                : storageBackupPath === undefined
-                    ? binaryHealthUncertainAction()
-                    : postSwitchRecoveryAction(home, storageBackupPath),
+            action: binaryHealthUncertainAction(),
             recoverable: false,
-            version: staged.version,
-            ...(storageBackupPath === undefined ? {} : { storageBackupPath })
-        };
-        if (!inPlaceCommitted && storageBackupPath === undefined)
-            resumeWrites();
-        return restoreBeforeSwitchOrReport(ports, home, lifecycle, storageBackupPath, inPlaceCommitted || storageBackupPath !== undefined, failure);
+            version: staged.version
+        });
     }
-    // The migrated database has now been opened successfully by the activated
-    // binary. Release direct-write admission before starting the replacement
-    // Controller, whose startup scheduler is itself an authoritative writer.
-    resumeWrites();
-    if (lifecycle?.ensureRunning === true) {
+    if (lifecycle.ensureRunning) {
         try {
             ports.startController(home);
         }
         catch (error) {
             const unknownActive = isUnknownActiveControllerFailure(error);
-            const startFailureAction = inPlaceCommitted
-                ? inPlaceMigrationRecoveryAction(home)
-                : lifecycle.wasRunning
-                    ? "The Home was not migrated. Keep writes quiesced and restore the previously running Controller identity before retrying."
-                    : "The Home was not migrated. Keep writes quiesced and start the replacement Controller after verifying the activated binary.";
             const failure = {
                 outcome: "aborted",
                 phase: "post-verify",
-                message: `${unknownActive ? "Replacement Controller ownership could not be authenticated safely" : "The replacement Controller could not start after activation and health verification"}: `
-                    + `${messageOf(error)}.`,
+                message: `${unknownActive
+                    ? "Replacement Controller ownership could not be authenticated safely"
+                    : "The replacement Controller could not start after activation and verification"}: ${messageOf(error)}.`,
                 action: unknownActive
-                    ? unknownActiveControllerAction(home, storageBackupPath, inPlaceCommitted)
-                    : storageBackupPath === undefined
-                        ? startFailureAction
-                        : postSwitchRecoveryAction(home, storageBackupPath),
+                    ? 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,
                 version: staged.version,
-                // P1-1 (rr22): ANY failure to start or authenticate the replacement
-                // Controller leaves the lifecycle handoff unresolved — not just
-                // UPDATE_CONTROLLER_UNKNOWN_ACTIVE. Even when the old identity is
-                // restored below, the running Controller is not the replacement the
-                // step promised, so the adapter must persist the step as unknown
-                // rather than letting a controller-home query confirm it on binary
-                // health alone.
-                controllerOwnershipUnknown: true,
-                ...(storageBackupPath === undefined ? {} : { storageBackupPath })
+                controllerOwnershipUnknown: true
             };
-            // An ownership-unknown mismatch is a live-process blocker, not a
-            // recoverable pre-switch failure.  Restoring the captured identity here
-            // could overwrite or race a foreign process, so leave the Home quiesced
-            // and preserve the explicit manual blocker.
             return unknownActive
                 ? failure
-                : restoreBeforeSwitchOrReport(ports, home, lifecycle, storageBackupPath, inPlaceCommitted || storageBackupPath !== undefined, failure);
+                : restoreControllerOrReport(ports, home, lifecycle, failure);
         }
     }
-    return storageBackupPath === undefined
-        ? { outcome: "updated", version: staged.version, path }
-        : { outcome: "updated", version: staged.version, path, storageBackupPath };
+    return { outcome: "updated", version: staged.version, path: "current-fast" };
 }
-/**
- * Capture the old Controller before a binary-only update mutates the install.
- * A partial lifecycle port set is rejected rather than silently selecting a
- * staged/new `ensureFileTaskController` for restoration.
- */
 function captureControllerLifecycle(ports, version, home) {
     const supplied = [
         ports.controllerStatus,
@@ -361,7 +150,7 @@ function captureControllerLifecycle(ports, version, home) {
         ports.restoreController
     ].some((port) => port !== undefined);
     if (!supplied) {
-        return { lifecycle: { ensureRunning: false, wasRunning: false, stopped: false } };
+        return { lifecycle: { ensureRunning: false, wasRunning: false } };
     }
     if (ports.controllerStatus === undefined
         || ports.stopController === undefined
@@ -371,7 +160,7 @@ function captureControllerLifecycle(ports, version, home) {
             outcome: "aborted",
             phase: "preflight",
             message: "Controller lifecycle ownership is incomplete for this update.",
-            action: "Provide status, stop, replacement-start, and exact-identity restore seams; refusing to activate a binary without a complete lifecycle owner.",
+            action: "Provide status, exact stop, replacement start, and exact restore operations.",
             recoverable: true,
             version
         };
@@ -385,43 +174,19 @@ function captureControllerLifecycle(ports, version, home) {
             outcome: "aborted",
             phase: "preflight",
             message: `Controller status could not be verified: ${messageOf(error)}`,
-            action: "Do not activate the binary while Controller ownership is unknown; inspect the Controller and retry once status is verified.",
+            action: "Inspect Controller ownership and retry after its status is known.",
             recoverable: true,
             version
         };
     }
     if (!isControllerLifecycleStatus(status)) {
-        return {
-            outcome: "aborted",
-            phase: "preflight",
-            message: "Controller status was malformed; expected a boolean running field.",
-            action: "Inspect the Controller status provider and retry; no binary activation was attempted.",
-            recoverable: true,
-            version
-        };
+        return malformedControllerResult(version, "Controller status was malformed.");
     }
     if (!status.running) {
-        return { lifecycle: { ensureRunning: true, wasRunning: false, stopped: false } };
-    }
-    if (!isPositivePid(status.pid)) {
-        return {
-            outcome: "aborted",
-            phase: "preflight",
-            message: "The Controller is running but its exact PID could not be captured.",
-            action: "Refusing an unfenced stop; inspect Controller ownership and retry only after its PID is authenticated.",
-            recoverable: true,
-            version
-        };
+        return { lifecycle: { ensureRunning: true, wasRunning: false } };
     }
-    if (!isControllerIdentity(status.identity)) {
-        return {
-            outcome: "aborted",
-            phase: "preflight",
-            message: "The Controller is running but its executable/version identity could not be captured.",
-            action: "Refusing to stop a Controller that cannot be restored exactly; provide its executable path, arguments, and version, then retry.",
-            recoverable: true,
-            version
-        };
+    if (!isPositivePid(status.pid) || !isControllerIdentity(status.identity)) {
+        return malformedControllerResult(version, "The running Controller did not expose an exact PID and launch identity.");
     }
     let stopped;
     try {
@@ -432,85 +197,56 @@ function captureControllerLifecycle(ports, version, home) {
             outcome: "aborted",
             phase: "preflight",
             message: `Controller stop/drain failed: ${messageOf(error)}`,
-            action: "The Controller may still be active or draining. Do not retry stop blindly; inspect it and retry once the Home is quiesced.",
+            action: "Inspect the captured Controller before retrying; binary activation was not attempted.",
             recoverable: true,
             version
         };
     }
-    if (!isControllerStopResult(stopped)
-        || stopped.stopped !== true
-        || stopped.pid !== status.pid) {
-        return {
-            outcome: "aborted",
-            phase: "preflight",
-            message: `Controller stop did not confirm the captured PID ${status.pid} with stopped:true.`,
-            action: "Keep the Home quiesced and inspect the Controller; no binary activation was attempted and no stop retry was issued.",
-            recoverable: true,
-            version
-        };
+    if (!isControllerStopResult(stopped) || stopped.stopped !== true || stopped.pid !== status.pid) {
+        return malformedControllerResult(version, `Controller stop did not confirm captured PID ${status.pid}.`);
     }
     return {
         lifecycle: {
             ensureRunning: true,
             wasRunning: true,
-            stopped: true,
             identity: status.identity
         }
     };
 }
-function restoreBeforeSwitchOrReport(ports, home, lifecycle, storageBackupPath, storageCommitted, failure) {
-    // Once storage switched, the old Controller is never safe to restore. Keep
-    // the failure structured and point at all durable recovery evidence instead.
-    if (storageCommitted || lifecycle?.wasRunning !== true)
+function malformedControllerResult(version, message) {
+    return {
+        outcome: "aborted",
+        phase: "preflight",
+        message,
+        action: "Refusing an unfenced Controller handoff; inspect ownership and retry.",
+        recoverable: true,
+        version
+    };
+}
+function restoreControllerOrReport(ports, home, lifecycle, failure) {
+    if (!lifecycle.wasRunning)
         return failure;
     try {
         ports.restoreController(home, lifecycle.identity);
         return failure;
     }
     catch (error) {
-        // Preserve the original phase, Home-switch evidence, and binary-health
-        // uncertainty guidance.  A restore failure is an appended blocker, not a
-        // replacement generic post-verify result.
         return {
             ...failure,
-            message: `${failure.message} The previously running Controller identity could not be restored: `
-                + `${messageOf(error)}.`,
-            action: `${failure.action} The old Controller restore also failed: ${messageOf(error)}. `
-                + "Keep the Home quiesced; inspect the restore blocker and resolve it before any bounded retry. ",
+            message: `${failure.message} Captured Controller restore failed: ${messageOf(error)}.`,
+            action: `${failure.action} Keep the Home quiesced and resolve the restore failure.`,
             recoverable: false
         };
     }
 }
-function postSwitchRecoveryAction(home, backupPath) {
-    return `The storage switch is committed (backup at ${backupPath}); do not restore the old Controller. `
-        + `Inspect the backup, receipt marker "${upgradeReceiptPath(home)}", and switch-progress marker `
-        + `"${switchProgressPath(home)}". Verify the migrated Home, then either finish the update or `
-        + `restore the backup explicitly with mv "${backupPath}" "${home}".`;
-}
 function binaryActivationUncertainAction() {
-    return "The Home was not migrated, but binary activation began and its outcome is unknown; "
-        + "do not assume the current install is usable. Reinstall Yui, verify `yui version` and "
-        + "`yui doctor`, then retry `yui update` before resuming writes.";
+    return "Binary activation began and its result is unknown. Reinstall Yui, then verify `yui version` and `yui doctor` before resuming the Controller.";
 }
 function binaryHealthUncertainAction() {
-    return "The Home was not migrated, but the activated binary failed health verification; do not "
-        + "assume the current install is usable. Reinstall Yui, verify `yui version` and `yui doctor`, "
-        + "then retry `yui update` before resuming writes.";
-}
-function inPlaceMigrationRecoveryAction(home) {
-    return `The SQLite migration for ${home} committed in place and has no rollback backup. `
-        + "Do not restore the old Controller; finish installing this or a newer Yui version, run `yui doctor`, then start the Controller.";
+    return "The activated binary failed health verification. Reinstall Yui and verify `yui version` and `yui doctor` before resuming the Controller.";
 }
-function unknownActiveControllerAction(home, backupPath, inPlaceCommitted) {
-    const storageEvidence = inPlaceCommitted
-        ? "The SQLite migration committed in place; do not restore the old Controller. "
-        : backupPath === undefined
-            ? "The Home was not migrated."
-            : `The storage switch is committed (backup at ${backupPath}); do not restore the old Controller. `;
-    return `${storageEvidence} A replacement Controller may still be active under unknown ownership. `
-        + `Keep writes quiesced and do not claim recovery or resume writes. Inspect the authenticated `
-        + `Controller status for ${home}, stop only the PID proven to belong to this update, then `
-        + "verify `yui version` and `yui doctor` before a bounded retry.";
+function unknownActiveControllerAction(home) {
+    return `A replacement Controller may be active under unknown ownership for ${home}. Keep it quiesced, authenticate its PID, and stop only that proven owner before retrying.`;
 }
 function isUnknownActiveControllerFailure(error) {
     return isRecord(error) && error.code === "UPDATE_CONTROLLER_UNKNOWN_ACTIVE";
@@ -533,166 +269,9 @@ function isControllerIdentity(value) {
         && typeof value.version === "string"
         && value.version.length > 0;
 }
-/**
- * Resolve an ambiguous storage activation (P1-2): the activation child left no
- * parseable receipt, so the switch may or may not have committed. Probe the
- * durable on-disk evidence and report an explicit manual recovery — this is
- * NEVER reported as recoverable-and-unchanged.
- *
- * The verdict is driven by the completion receipt first (the switch writes it the
- * instant it commits), then corroborated by the on-disk schema:
- *  - receipt present  -> the switch committed; point at the backup and require
- *    the operator to verify the migrated Home before resuming (the binary was
- *    never promoted, so the old binary fail-closes on the new schema).
- *  - no receipt, schema already current -> most likely the switch never ran
- *    (or fully reverted); still require an explicit re-run rather than asserting
- *    "unchanged", because stdout was lost.
- *  - no receipt, schema not current -> genuinely indeterminate; give the
- *    operator the exact files to inspect.
- */
-function resolveAmbiguousActivation(ports, staged, home, detail, expected, lifecycle, resumeWrites) {
-    let probe;
-    try {
-        probe = ports.probeStorage(home);
-    }
-    catch (error) {
-        // Even the probe failed: report maximum uncertainty with the raw evidence.
-        if (expected.kind === "in-place") {
-            return {
-                outcome: "ambiguous",
-                phase: "activate-storage",
-                message: `SQLite activation result is unknown (${detail}); reading its migration ledger also failed: ${messageOf(error)}.`,
-                action: `Do not restore the old Controller or assume the migration committed. Inspect the `
-                    + `schema_migrations ledger in "${home}/yui.db" with the staged/current Yui version, `
-                    + `then re-run "yui update" only after the ledger state is known.`,
-                version: staged.version,
-                schemaCurrent: false,
-                switched: false
-            };
-        }
-        return {
-            outcome: "ambiguous",
-            phase: "activate-storage",
-            message: `Storage activation result is unknown (${detail}); probing the Home also failed: ${messageOf(error)}.`,
-            action: `Do NOT assume the update succeeded or was a no-op. Manually inspect ${home} and any `
-                + `"${home}.backup-*" sibling, "${upgradeReceiptPath(home)}", and `
-                + `"${switchProgressPath(home)}"; if a receipt exists the `
-                + `switch committed — verify the migrated Home with "yui doctor" before resuming, otherwise `
-                + `restore the newest backup with mv before re-running "yui update".`,
-            version: staged.version,
-            schemaCurrent: false,
-            switched: false
-        };
-    }
-    if (expected.kind === "in-place"
-        && sameSqliteLedgerHead(probe.sqliteSchemaHead, expected.migration.target)) {
-        return {
-            outcome: "ambiguous",
-            phase: "activate-storage",
-            message: `The SQLite transaction committed according to its migration ledger, but the activation process did not confirm success (${detail}). The new binary was NOT promoted.`,
-            action: "Do not restore the old Controller. Re-run `yui update` with this or a newer version; the current ledger will make the storage step a no-op, then the binary and Controller handoff can finish.",
-            version: staged.version,
-            schemaCurrent: probe.schemaCurrent,
-            switched: false
-        };
-    }
-    if (expected.kind === "in-place"
-        && sameSqliteLedgerHead(probe.sqliteSchemaHead, expected.migration.current)) {
-        const failure = {
-            outcome: "aborted",
-            phase: "activate-storage",
-            message: `The SQLite activation process did not confirm success (${detail}), but the atomic migration ledger proves that no schema transaction committed.`,
-            action: "The database remains at its previous schema. The captured Controller identity was restored when possible; retry the update after diagnosing the activation child.",
-            recoverable: true,
-            version: staged.version
-        };
-        resumeWrites();
-        return restoreBeforeSwitchOrReport(ports, home, lifecycle, undefined, false, failure);
-    }
-    if (expected.kind === "in-place") {
-        const actual = probe.sqliteSchemaHead === undefined
-            ? "unavailable"
-            : `${probe.sqliteSchemaHead.version}:${probe.sqliteSchemaHead.checksum}`;
-        return {
-            outcome: "ambiguous",
-            phase: "activate-storage",
-            message: `SQLite activation did not confirm a result (${detail}), and its migration ledger head `
-                + `(${actual}) matches neither the validated source nor target boundary.`,
-            action: `Do not restore the old Controller or resume writes. Inspect the schema_migrations ledger `
-                + `in "${home}/yui.db" with the staged/current Yui version and resolve the unexpected `
-                + `ledger state before re-running "yui update".`,
-            version: staged.version,
-            schemaCurrent: probe.schemaCurrent,
-            switched: false
-        };
-    }
-    if (probe.interrupted === true) {
-        // A partially-applied, interrupted switch: the original was moved to the
-        // backup and neither promotion nor rollback completed, so the Home path may
-        // be missing. This is the strongest "restore the backup now" signal — never a
-        // "verify the migrated Home" or a "recoverable no-op".
-        return {
-            outcome: "ambiguous",
-            phase: "activate-storage",
-            message: `Storage switch was INTERRUPTED mid-rename (${detail}); the Home may be missing and was `
-                + `NOT left intact. The new binary was NOT promoted.`,
-            action: `Restore the timestamped backup to recover the original Home: `
-                + `mv "${probe.backupPath ?? "<home>.backup-*"}" "${home}". Do NOT resume writes until it is `
-                + `restored; inspect "${switchProgressPath(home)}" for the interrupted phase, then re-run "yui update".`,
-            version: staged.version,
-            schemaCurrent: probe.schemaCurrent,
-            switched: false,
-            ...(probe.backupPath === undefined ? {} : { storageBackupPath: probe.backupPath })
-        };
-    }
-    if (probe.switched) {
-        // The switch provably committed; the binary was not promoted.
-        return {
-            outcome: "ambiguous",
-            phase: "activate-storage",
-            message: `Storage was switched (a completion receipt is present) but the activation process `
-                + `did not confirm success (${detail}). The new binary was NOT promoted.`,
-            action: `Verify the migrated Home before resuming writes: run "yui doctor"`
-                + `${probe.backupPath === undefined ? "" : ` (its timestamped backup is ${probe.backupPath})`}. `
-                + `Inspect "${upgradeReceiptPath(home)}" and "${switchProgressPath(home)}" before deciding. `
-                + `If it is healthy, finish by re-running "yui update" to promote the binary; if not, restore `
-                + `the backup with mv "${probe.backupPath ?? "<home>.backup-*"}" "${home}". Do NOT resume `
-                + `writes with the old binary against the migrated Home.`,
-            version: staged.version,
-            schemaCurrent: probe.schemaCurrent,
-            switched: true,
-            ...(probe.backupPath === undefined ? {} : { storageBackupPath: probe.backupPath })
-        };
-    }
-    // No receipt: the switch most likely never committed, but stdout was lost so we
-    // cannot assert "unchanged". Require an explicit, verified re-run.
-    return {
-        outcome: "ambiguous",
-        phase: "activate-storage",
-        message: `Storage activation did not confirm a result (${detail}) and no completion receipt was found`
-            + `${probe.schemaCurrent ? "; the Home currently loads at the current schema" : ""}.`,
-        action: `The switch most likely did not commit, but this was not confirmed. Verify with "yui doctor" `
-            + `and check for any "${home}.backup-*" sibling, "${upgradeReceiptPath(home)}", and `
-            + `"${switchProgressPath(home)}" before retrying; then re-run "yui update". Do `
-            + `NOT assume the update completed.`,
-        version: staged.version,
-        schemaCurrent: probe.schemaCurrent,
-        switched: false
-    };
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function messageOf(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function sameSqliteLedgerHead(actual, expected) {
-    return actual?.version === expected.version && actual.checksum === expected.checksum;
-}
-function isValidBackupPath(value) {
-    return typeof value === "string"
-        && value.length > 0
-        && value.trim() === value
-        && !value.includes("\0")
-        && isAbsolute(value);
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}