@zq-silk/yui 0.12.0 → 0.12.2

package/README.md

@@ -549,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

package/dist/cli/commandCatalog.js

@@ -540,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: [
@@ -570,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",
@@ -736,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