@zq-silk/yui 0.11.3 → 0.12.1

package/ARCHITECTURE.md

@@ -19,6 +19,16 @@ units. For a feature, the Leader judges whether the whole result is small
 enough to own in the same way or large enough to need independently owned
 delivery units.
 
+Operator updates have one durable path. Domain and runtime transitions first
+append an immutable TaskEvent; user-owned questions append an InputRequest.
+Only those record references enter the global Operator mailbox. The Controller
+batches pending references into one receipt-backed synthetic user message for
+the existing interactive Operator and defers the complete batch while that
+Operator is busy or unavailable. The message carries CLI read pointers rather
+than copied Task or Provider narrative. No lower layer calls the Operator, no
+mutable notification projection duplicates the event history, and no Goal or
+polling protocol is required to follow work.
+
 `WorkItem` means one substantial, independently acceptable requirement with a
 clear owner. Create multiple WorkItems only when multiple Workers can own and
 advance those requirements independently, normally in parallel. Internal
@@ -128,10 +138,14 @@ late results until explicitly reopened.
 
 Stable Project checkouts are read-only references. Task identity follows one
 bounded outcome rather than Project count. A Task binds zero or more Projects,
-records an independent base ref for each binding, and owns one workspace root
-containing a managed main worktree for each binding. The
-`<workspace>/tasks/<task>/main` root is a logical multi-Project container, not a
-Git repository. Each Project child (for example
+records an independent base ref for each binding, and adopts one workspace root
+only when it becomes active. A Draft owns planning state and Project bindings,
+not a writable Workspace. Activation prepares physical worktrees first and then
+commits status, workspace identity, cwd, and durable Workspace ownership in one
+TaskStore transaction; failure discards unadopted resources and leaves the Task
+Draft. The active Workspace contains a managed main worktree for each binding.
+The `<workspace>/tasks/<task>/main` root is a logical multi-Project container,
+not a Git repository. Each Project child (for example
 `<workspace>/tasks/<task>/main/yui`) is the supported Git cwd and points to
 `<workspace>/worktree/<project>/<task>/main`; Git commands run in that child.
 For a single-Project workspace, the native Agent starts in that Project's
@@ -142,6 +156,11 @@ additional-directory mechanism. The active Leader may append a Project when the
 same outcome expands; replacing an existing binding is not a scope-repair
 mechanism.
 
+Before a Role launch, Yui verifies that every physical Project HEAD still
+descends from its Workspace's recorded base. Normal committed progress is
+allowed; a reset or repoint outside that lineage is reported as
+`physical-drift` and fails closed before Provider launch.
+
 A WorkItem can read the full Task workspace but has an explicit Project write
 scope. Isolation creates a second root with independent worktrees for writable
 Projects and Task-main context for the rest. The managed dispatch and

package/README.md

@@ -274,6 +274,12 @@ yui task context <task-id>
 yui task activate <task-id>
 ```
 
+A Draft stores planning state and Project bindings only; it does not adopt a
+writable managed Workspace. `task activate` prepares every bound Project first,
+then commits the Task's `active` status and Task-owned Workspace together. A
+preparation or consistency failure leaves the Task Draft and reports the
+workspace diagnosis instead of exposing a partially adopted execution root.
+
 Task type describes intent rather than selecting an execution protocol.
 Software Projects use `bugfix` or `feature`: a bugfix is Leader-owned; if it
 grows into independently owned delivery requirements, reclassify it as a
@@ -390,14 +396,16 @@ acceptance so the Leader can accept it directly or run
 Leader-managed candidates awaiting a decision instead of marking them done.
 `final` does not create WorkItem ReviewRounds or decide Task topology. The
 Leader explicitly requests a Task-scoped Review, unless an immutable Task
-contract requires one. The Round freezes Task main directly, so even a
-Leader-owned Task with no WorkItem can be reviewed. A changed frozen head needs
-a new semantic Round; the same compatible Reviewer Session may continue in its
+contract requires one. The Round snapshots the exact Task-main Project heads
+directly, so even a Leader-owned Task with no WorkItem can be reviewed without
+locking the mutable Task workspace. A changed frozen head needs a new semantic
+Round; the same Reviewer Session continues in its
 stable workspace, while every Run remains bound to its exact Round and head.
 The Reviewer follows Project Policy/Knowledge and reports reachable, material,
 actionable findings across the complete Task.
-A ReviewRound freezes the Candidate's exact Git commit and creates a fresh,
-ReviewRound-owned writable worktree on a unique branch. Its AgentRun may edit,
+A ReviewRound freezes the Candidate's exact Git commit and updates the
+Reviewer Role's stable writable workspace to that head while recording exact
+Round-owned workspace evidence. Its AgentRun may edit,
 test, and optionally commit diagnostic evidence there, but never changes the
 Candidate or Worker workspace and never creates another WorkItem, Candidate,
 ChangeSet, or recursive review. The result wakes the Leader, who decides whether
@@ -405,6 +413,17 @@ to route evidence to the original Worker, accept, reject and redispatch that
 Worker in its existing Session, review again, or request user input.
 A failed review remains visible evidence and wakes the Leader, but does not
 take that decision away from the Leader.
+Task context and next-action expose direct Review facts: every frozen Project
+commit, its relation to the current candidate, the active Run, and the Reviewer
+workspace. A request that fails after Round creation retains the ReviewRound
+and reports its exact reason; the Leader opens that Round and decides whether
+to retry, inspect or clean the workspace, use another Reviewer, or continue
+other work.
+An active Task-final Review freezes only its own candidate; it does not prevent
+the Leader from processing new input or advancing a later candidate. Delta
+Recheck is always available when Yui can prove an accepted contiguous baseline
+and exact diff. Yui does not select a mode from generic size thresholds;
+`requires-full-review` returns to the Leader without creating another Round.
 Candidate history, every ReviewRound, and the Leader decision remain grouped
 under the original WorkItem. A rejected result creates a new Candidate on the
 next dispatch while reusing the original execution Role, Session, and
@@ -530,19 +549,18 @@ yui operator new
 yui operator enter
 ```
 
-When a Task Role's current native Session cannot continue, reset it by intent:
+When a Task Role's current Provider Conversation cannot continue, request a
+bounded switch with an audited reason:
 
 ```sh
-yui task role reset <task-id> <role> --reason "<why this generation cannot continue>"
+yui task role session switch <task-id> <role> --reason "<why this conversation cannot continue>"
 ```
 
-Yui derives the current Run, Agent, launch, receipt, and native Session from its
-own records. It fails only that exact active Run (and its execution WorkItem),
-stores the current Session as broken history, and asks the Controller to stop
-only the Role-owned runtime. The command never creates a Candidate, accepts
-work, or completes the Task. While cleanup is pending, `task role status` and
-`task context` block a fresh launch. Existing messages, reviews, and delivery
-history remain durable.
+The command records intent only. It does not fail active work, stop a live
+runtime, or forget the current Conversation. Once the Role has ready work and
+the current writer/Turn is settled, Yui creates and binds the replacement; a
+failure before that bind leaves the old Conversation authoritative. Existing
+messages, reviews, and delivery history remain durable.
 
 Without `--task`, `operator submit` creates a new Draft. Drafts accept planning changes but must be activated before Agent execution.
 Operator resolves every request against the Project catalog and existing Task
@@ -594,11 +612,14 @@ Every stage is a new immutable ExecutionGroup. Its ContextSnapshot and selected
 parent Lane results are durable references; `retry` repeats a stage within its
 attempt budget, while `retry` at Resolve begins the next bounded round.
 
-Each new stage also freezes one Resource Broker contract: token, tool-call and
-wall-clock budgets; quorum and deadline; a straggler window; and the minimum
-marginal value for more Lane spend. Omitted values reuse the existing context
-budget and runtime-health windows; stage retries share the original cumulative
-spend and absolute deadline. Execution, Lane retry, and Reviewer-panel
+Each new stage also freezes one Resource Broker contract: behavioral tool-call
+and wall-clock budgets; a display-only token threshold; quorum and deadline; a
+straggler window; and the minimum marginal value for more Lane spend. Omitted
+values reuse the existing context budget and runtime-health windows; stage
+retries share the original cumulative observations and absolute deadline.
+Observed token totals and the configured token threshold are cost context only:
+they never close spend, block admission, suppress scheduling, or stop a Lane.
+Execution, Lane retry, and Reviewer-panel
 admission all count active Lanes at Home, Task, WorkItem, Group, Provider,
 Agent, and model scopes. Capacity pressure keeps the excess Lane durably
 pending instead of failing the Group. Capacity release or deadline arrival
@@ -613,8 +634,9 @@ The Leader may add `--early-stop <0-100>` to an accepting Group resolution.
 Yui permits it only after quorum and T5's passed Verify/Resolve evidence prove
 sufficiency. It may skip Lanes that never started; active stragglers are
 reported and retained, never killed automatically for cost. If evidence is
-insufficient, budget or deadline exhaustion blocks the stage for Leader
-judgment instead of turning thin evidence into success.
+insufficient, behavioral tool-call/wall-clock budget or deadline exhaustion
+blocks the stage for Leader judgment instead of turning thin evidence into
+success.
 
 New exploration histories also freeze the structured candidate-convergence
 contract. Yui appends the exact stage-local JSON shape to every Lane assignment
@@ -792,7 +814,7 @@ yui task input request <task-id> --question "Which format should be the default?
 
 The recommendation is shown to the user. If no answer arrives, the nearest-deadline timer wakes the Controller to atomically apply that exact choice and queue the fixed Leader session to resume. Free-text and user-required requests never auto-resolve.
 
-`task input list` is the authoritative global open-input Inbox; add a Task ID to scope it, or `--all` to include answered and cancelled requests. The Controller also makes one receipt-backed, best-effort delivery to an already-running Operator process. It never starts or interrupts an Operator for this notification; unavailable process state or a changed pane fence falls back to the durable Inbox and is reconsidered on a later Controller pass. It does not inspect or classify Agent terminal text. Answers may be submitted by the user or Operator. An open request prevents unrelated pending wakes and Task completion or archival. The originating Leader may instead run `yui task input cancel <task-id> <input-id> --reason "..."`; cancellation queues that fixed Leader session to resume.
+`task input list` is the authoritative global open-input Inbox; add a Task ID to scope it, or `--all` to include answered and cancelled requests. Task completion, retirement, Leader attention, stalls, and open input are queued to the global Operator mailbox only as immutable TaskEvent or InputRequest references. The Controller merges one pending mailbox batch into one receipt-backed `[Yui updates]` user message for an existing ready Operator; the Operator reads the referenced records through the CLI and decides what is worth presenting. A running or unavailable Operator is never started or interrupted: the whole batch remains durable and is retried after native turn completion or a later Controller pass. This path is a user message, not a tool call, and it never inspects or classifies Agent terminal text. Answers may be submitted by the user or Operator. An open request prevents unrelated pending wakes and Task completion or archival. The originating Leader may instead run `yui task input cancel <task-id> <input-id> --reason "..."`; cancellation queues that fixed Leader session to resume.
 
 Inspect the result:
 

package/dist/cli/commandCatalog.js

@@ -59,8 +59,7 @@ function durableConfigDomainNode(domain) {
     const values = CONFIG_KEY_VALUES.filter(({ name }) => keys.includes(name));
     const options = domain === "workflow"
         ? [
-            "--soft-tokens", "--hard-tokens", "--role", "--trigger", "--finding-ledger",
-            "--delta-recheck", "--delta-recheck-max-lines", "--delta-recheck-max-files"
+            "--soft-tokens", "--hard-tokens", "--role", "--trigger", "--finding-ledger"
         ]
         : domain === "runtime"
             ? ["--quiet-after-seconds", "--diagnostic-after-seconds", "--stall-after-seconds"]
@@ -86,8 +85,7 @@ function durableConfigDomainNode(domain) {
                 optionValues: domain === "workflow"
                     ? {
                         "--trigger": ["always", "leader", "final"],
-                        "--finding-ledger": ["shadow", "enforce"],
-                        "--delta-recheck": ["enabled", "disabled"]
+                        "--finding-ledger": ["shadow", "enforce"]
                     }
                     : {}
             },
@@ -542,7 +540,7 @@ const taskChildren = [
         name: "role",
         summary: "Manage Roles within a Task.",
         sections: [{ id: "manage", title: "Commands", entries: [
-                    "add", "list", "status", "show", "update", "remove", "bind", "unbind", "reset",
+                    "add", "list", "status", "show", "update", "remove", "bind", "unbind", "session",
                     "view", "takeover", "release"
                 ] }],
         children: [
@@ -572,10 +570,15 @@ const taskChildren = [
             { name: "bind", summary: "Bind and activate an Agent for a Task Role.", usage: "yui task role bind <task> <role> <agent-id>" },
             { name: "unbind", summary: "Unbind a dormant Agent from a Task Role.", usage: "yui task role unbind <task> <role> <agent-id>" },
             {
-                name: "reset",
-                summary: "Fail current work, forget the native Session, and request verified cleanup.",
-                usage: "yui task role reset <task> <role> --reason <text>",
-                options: ["--reason"]
+                name: "session",
+                summary: "Manage the Provider Conversation bound to a Task Role.",
+                sections: [{ id: "manage", title: "Commands", entries: ["switch"] }],
+                children: [{
+                        name: "switch",
+                        summary: "Request a fresh Conversation after the current one reaches a safe boundary.",
+                        usage: "yui task role session switch <task> <role> --reason <text>",
+                        options: ["--reason"]
+                    }]
             },
             {
                 name: "view",
@@ -738,7 +741,7 @@ const taskChildren = [
             {
                 name: "recover",
                 summary: "Record one exact Leader-controlled Run recovery decision.",
-                usage: "yui task run recover <task>/<run> --action <diagnose|retry|replace-session|terminate> (--expected-progress-at <timestamp>|--from-next-action <fingerprint>) --provider-acceptance <accepted|rejected|ambiguous> --reason <text>",
+                usage: "yui task run recover <task>/<run> --action <diagnose|retry|terminate> (--expected-progress-at <timestamp>|--from-next-action <fingerprint>) --provider-acceptance <accepted|rejected|ambiguous> --reason <text>",
                 options: ["--action", "--expected-progress-at", "--progress-at", "--from-next-action", "--provider-acceptance", "--reason", "--role", "--agent-id", "--adapter-id", "--native-session-id", "--launch-id"]
             },
             {

package/dist/cli/interactionPolicy.js

@@ -347,19 +347,18 @@ export const INTERACTION_POLICIES = Object.freeze([
         ]
     })),
     {
-        commandPath: ["task", "role", "reset"],
+        commandPath: ["task", "role", "session", "switch"],
         selectors: [
-            { argumentIndex: 3, entity: "task", provider: "tasks", actionTarget: true, statuses: ["active"] },
+            { argumentIndex: 4, entity: "task", provider: "tasks", actionTarget: true, statuses: ["active"] },
             {
-                argumentIndex: 4,
+                argumentIndex: 5,
                 entity: "task-role",
                 provider: "task-roles",
-                dependsOn: 3,
+                dependsOn: 4,
                 actionTarget: true
             }
         ],
-        trailingOptions: { "--reason": "value" },
-        confirmation: { action: "Reset Task Role Session", targetArgumentIndex: 4 }
+        trailingOptions: { "--reason": "value" }
     },
     ...["view", "takeover", "release"].map((command) => ({
         commandPath: ["task", "role", command],

package/dist/cli/updateCommand.js

@@ -38,7 +38,9 @@ export function renderUpdateResult(result) {
                 return result.storageBackupPath === undefined
                     ? result.path === "compatible-fast"
                         ? `Updated Yui to ${result.version} via the compatible fast path; the Home was not migrated.`
-                        : `Updated Yui to ${result.version}; storage was already current.`
+                        : result.path === "in-place-migration"
+                            ? `Updated Yui to ${result.version}; SQLite was migrated in place without rebuilding the database.`
+                            : `Updated Yui to ${result.version}; storage was already current.`
                     : `Updated Yui to ${result.version}. Storage was migrated; original Home backed up at `
                         + `${result.storageBackupPath}.`;
             case "aborted":

package/dist/cli/updateOrchestrator.js

@@ -116,6 +116,64 @@ function runStagedUpdate(ports, staged, home) {
             ...(preflight.sceneUnchanged === true ? { sceneUnchanged: true } : {})
         };
     }
+    let releaseHandover;
+    try {
+        releaseHandover = ports.beginControllerHandover?.(home);
+    }
+    catch (error) {
+        return {
+            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.",
+            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);
+    }
+    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
@@ -127,7 +185,7 @@ function runStagedUpdate(ports, staged, home) {
         // 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");
+        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
@@ -139,7 +197,9 @@ function runStagedUpdate(ports, staged, home) {
         activation = ports.activateStorage(staged, home);
     }
     catch (error) {
-        return resolveAmbiguousActivation(ports, staged, home, `the activation step threw unexpectedly: ${messageOf(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 = {
@@ -160,24 +220,30 @@ function runStagedUpdate(ports, staged, home) {
         // 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.
-        return restoreBeforeSwitchOrReport(ports, home, lifecycle.lifecycle, undefined, failure);
+        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);
+        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");
+        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, "offline-migration");
+    return activateAndVerify(ports, staged, home, backupPath, lifecycle.lifecycle, path, resumeWrites);
 }
 /**
  * Promote the staged binary and run the new-binary health check. This is the
@@ -185,7 +251,8 @@ function runStagedUpdate(ports, staged, home) {
  * 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) {
+function activateAndVerify(ports, staged, home, storageBackupPath, lifecycle, path, resumeWrites) {
+    const inPlaceCommitted = path === "in-place-migration";
     try {
         ports.activateBinary(staged);
     }
@@ -194,9 +261,11 @@ function activateAndVerify(ports, staged, home, storageBackupPath, lifecycle, pa
             outcome: "aborted",
             phase: "activate-binary",
             message: `Failed to activate the new binary: ${messageOf(error)}`,
-            action: storageBackupPath === undefined
-                ? binaryActivationUncertainAction()
-                : postSwitchRecoveryAction(home, storageBackupPath),
+            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.
@@ -204,7 +273,9 @@ function activateAndVerify(ports, staged, home, storageBackupPath, lifecycle, pa
             version: staged.version,
             ...(storageBackupPath === undefined ? {} : { storageBackupPath })
         };
-        return restoreBeforeSwitchOrReport(ports, home, lifecycle, storageBackupPath, failure);
+        if (!inPlaceCommitted && storageBackupPath === undefined)
+            resumeWrites();
+        return restoreBeforeSwitchOrReport(ports, home, lifecycle, storageBackupPath, inPlaceCommitted || storageBackupPath !== undefined, failure);
     }
     try {
         ports.verify(staged, home);
@@ -214,31 +285,41 @@ function activateAndVerify(ports, staged, home, storageBackupPath, lifecycle, pa
             outcome: "aborted",
             phase: "post-verify",
             message: `Post-update health check failed: ${messageOf(error)}`,
-            action: storageBackupPath === undefined
-                ? binaryHealthUncertainAction()
-                : postSwitchRecoveryAction(home, storageBackupPath),
+            action: inPlaceCommitted
+                ? inPlaceMigrationRecoveryAction(home)
+                : storageBackupPath === undefined
+                    ? binaryHealthUncertainAction()
+                    : postSwitchRecoveryAction(home, storageBackupPath),
             recoverable: false,
             version: staged.version,
             ...(storageBackupPath === undefined ? {} : { storageBackupPath })
         };
-        return restoreBeforeSwitchOrReport(ports, home, lifecycle, storageBackupPath, failure);
-    }
+        if (!inPlaceCommitted && storageBackupPath === undefined)
+            resumeWrites();
+        return restoreBeforeSwitchOrReport(ports, home, lifecycle, storageBackupPath, inPlaceCommitted || storageBackupPath !== undefined, failure);
+    }
+    // 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) {
         try {
             ports.startController(home);
         }
         catch (error) {
             const unknownActive = isUnknownActiveControllerFailure(error);
-            const startFailureAction = 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 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)}.`,
                 action: unknownActive
-                    ? unknownActiveControllerAction(home, storageBackupPath)
+                    ? unknownActiveControllerAction(home, storageBackupPath, inPlaceCommitted)
                     : storageBackupPath === undefined
                         ? startFailureAction
                         : postSwitchRecoveryAction(home, storageBackupPath),
@@ -260,7 +341,7 @@ function activateAndVerify(ports, staged, home, storageBackupPath, lifecycle, pa
             // and preserve the explicit manual blocker.
             return unknownActive
                 ? failure
-                : restoreBeforeSwitchOrReport(ports, home, lifecycle, storageBackupPath, failure);
+                : restoreBeforeSwitchOrReport(ports, home, lifecycle, storageBackupPath, inPlaceCommitted || storageBackupPath !== undefined, failure);
         }
     }
     return storageBackupPath === undefined
@@ -377,10 +458,10 @@ function captureControllerLifecycle(ports, version, home) {
         }
     };
 }
-function restoreBeforeSwitchOrReport(ports, home, lifecycle, storageBackupPath, failure) {
+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 (storageBackupPath !== undefined || lifecycle?.wasRunning !== true)
+    if (storageCommitted || lifecycle?.wasRunning !== true)
         return failure;
     try {
         ports.restoreController(home, lifecycle.identity);
@@ -416,10 +497,16 @@ function binaryHealthUncertainAction() {
         + "assume the current install is usable. Reinstall Yui, verify `yui version` and `yui doctor`, "
         + "then retry `yui update` before resuming writes.";
 }
-function unknownActiveControllerAction(home, backupPath) {
-    const storageEvidence = backupPath === undefined
-        ? "The Home was not migrated."
-        : `The storage switch is committed (backup at ${backupPath}); do not restore the old Controller. `;
+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.";
+}
+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 `
@@ -463,13 +550,26 @@ function isControllerIdentity(value) {
  *  - no receipt, schema not current -> genuinely indeterminate; give the
  *    operator the exact files to inspect.
  */
-function resolveAmbiguousActivation(ports, staged, home, detail) {
+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",
@@ -484,6 +584,48 @@ function resolveAmbiguousActivation(ports, staged, home, detail) {
             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
@@ -541,6 +683,9 @@ function resolveAmbiguousActivation(ports, staged, home, detail) {
 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