@zq-silk/yui 0.12.0 → 0.12.1

package/dist/storage/upgrade/upgradeOrchestrator.js

@@ -34,14 +34,17 @@
  * authoritative input byte-for-byte unchanged.
  */
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import Database from "better-sqlite3";
 import { describeReport, runMigration } from "../migration/index.js";
 import { validateCompatibleFileTaskStore } from "../compatibleTaskStore.js";
 import { stopFileTaskController, ensureFileTaskController, ensureFileTaskControllerIdentity } from "../../controller/clientRuntime.js";
 import { callController } from "../../core/controllerClient.js";
 import { FileTaskStore, STORAGE_STATE_FILE, withStorageWriteLock } from "../taskStore.js";
 import { SqliteTaskStore } from "../sqliteStore.js";
+import { migrateSqliteSchema } from "../sqliteSchema.js";
 import { clearUpgradeFence, placeUpgradeFence, readUpgradeFence, UpgradeFenceError } from "../upgradeFence.js";
 import { withUpgradeCoordinationLock } from "../upgradeCoordination.js";
 import { clearUpgradeReceipt, writeUpgradeReceipt, upgradeReceiptPath } from "./upgradeReceipt.js";
@@ -52,7 +55,7 @@ import { repairPseudoLayout7 } from "./pseudoLayoutRepair.js";
 import { createSqliteMigrationTarget } from "./sqliteMigrationTarget.js";
 import { createSqliteRecordMigrationTarget } from "./sqliteRecordMigrationTarget.js";
 import { COMMITTED_DATABASE_FILENAME } from "./sqliteStateMigration.js";
-import { inspectOfflineUpgradeInventory } from "./offlineUpgradeInventory.js";
+import { inspectOfflineUpgradeInventory, inspectSqliteDurableUpgradeInventory } from "./offlineUpgradeInventory.js";
 /**
  * Run the storage upgrade for one Home. Never throws for an expected blocker;
  * it returns a structured `blocked` result instead. It only throws on a truly
@@ -95,6 +98,9 @@ export async function runStorageUpgrade(options) {
             action: blocker.action
         }, classification);
     }
+    if (classification.sqliteMigration !== undefined) {
+        return runSqliteInPlaceUpgrade(options, classification, now, callerPid);
+    }
     // A pseudo-layout-7 Home (manifest 7, no yui.db, readable state.json) needs
     // the deterministic staged state.json→SQLite repair, not the version
     // migration engine (Issue 01). The update preflight reports it as
@@ -357,6 +363,329 @@ function offlineInventoryBlocker(inventory, sceneUnchanged) {
         ...(sceneUnchanged ? { sceneUnchanged: true } : {})
     };
 }
+/**
+ * A valid SQLite migration prefix advances the authoritative database in
+ * place. It still uses the offline runtime gate because the old Controller
+ * cannot safely resume after the schema transaction commits, but it never
+ * snapshots, copies, rebuilds, or swaps the database.
+ */
+async function runSqliteInPlaceUpgrade(options, classification, now, callerPid) {
+    const migration = classification.sqliteMigration;
+    const inventory = await readOfflineInventory(options, options.home);
+    if (inventory.total > 0) {
+        return withClassification(offlineInventoryBlocker(inventory, true), classification);
+    }
+    if (options.mode === "update-preflight") {
+        return {
+            outcome: "update-preflight",
+            status: "in-place-migration",
+            stepCount: migration.pendingVersions.length,
+            classification,
+            sqliteMigration: migration
+        };
+    }
+    if (options.mode === "dry-run") {
+        return validateSqliteInPlaceDryRun(options, classification, now);
+    }
+    return executeSqliteInPlaceUpgrade(options, classification, now, callerPid);
+}
+/**
+ * Exercise every pending SQLite migration against a consistent disposable
+ * snapshot, then open that snapshot through the current production loader.
+ * The authoritative database is opened read-only and is never migrated.
+ */
+async function validateSqliteInPlaceDryRun(options, classification, now) {
+    const migration = classification.sqliteMigration;
+    const stagingRoot = mkdtempSync(join(tmpdir(), "yui-sqlite-upgrade-dry-run-"));
+    const stagedDatabasePath = join(stagingRoot, COMMITTED_DATABASE_FILENAME);
+    let source;
+    let staged;
+    let loader;
+    try {
+        source = new Database(join(options.home, COMMITTED_DATABASE_FILENAME), {
+            readonly: true,
+            fileMustExist: true
+        });
+        source.pragma("busy_timeout = 5000");
+        await source.backup(stagedDatabasePath);
+        source.close();
+        source = undefined;
+        staged = new Database(stagedDatabasePath);
+        staged.pragma("journal_mode = WAL");
+        staged.pragma("synchronous = FULL");
+        staged.pragma("foreign_keys = ON");
+        const applied = migrateSqliteSchema(staged, { mode: "apply" }).applied;
+        if (applied.join(",") !== migration.pendingVersions.join(",")) {
+            throw new Error(`staged SQLite migration applied versions ${applied.join(",") || "none"}; `
+                + `expected ${migration.pendingVersions.join(",")}`);
+        }
+        staged.close();
+        staged = undefined;
+        loader = new SqliteTaskStore(stagingRoot);
+        const quickCheck = loader.databaseHandle().pragma("quick_check", { simple: true });
+        if (quickCheck !== "ok") {
+            throw new Error(`staged SQLite quick_check returned ${String(quickCheck)}`);
+        }
+        loader.close();
+        loader = undefined;
+        return {
+            outcome: "dry-run",
+            classification,
+            report: sqliteInPlaceReport(options.latest, migration, "dry-run", now)
+        };
+    }
+    catch (error) {
+        return withClassification({
+            outcome: "blocked",
+            stage: "validate",
+            message: `SQLite dry-run validation failed: ${messageOf(error)}`,
+            action: "The authoritative database was not changed. Resolve the reported migration or loader failure, then retry the dry run."
+        }, classification);
+    }
+    finally {
+        try {
+            loader?.close();
+        }
+        catch { /* best-effort disposable cleanup */ }
+        try {
+            staged?.close();
+        }
+        catch { /* best-effort disposable cleanup */ }
+        try {
+            source?.close();
+        }
+        catch { /* best-effort disposable cleanup */ }
+        rmSync(stagingRoot, { recursive: true, force: true });
+    }
+}
+/** Acquire a local write fence or prove the exact parent-owned fence exists. */
+function acquireUpgradeAdmission(options, reason, now, callerPid) {
+    const externalOwnerPid = options.externalUpgradeFenceOwnerPid;
+    if (externalOwnerPid !== undefined) {
+        const fence = readUpgradeFence(options.home);
+        if (!isPositivePid(externalOwnerPid) || fence?.ownerPid !== externalOwnerPid) {
+            throw new UpgradeFenceError(`expected parent-owned upgrade fence for PID ${String(externalOwnerPid)}`);
+        }
+        return () => { };
+    }
+    return placeUpgradeFence(options.home, {
+        reason,
+        createdAt: now().toISOString(),
+        ownerPid: callerPid
+    });
+}
+async function executeSqliteInPlaceUpgrade(options, classification, now, callerPid) {
+    const { home } = options;
+    const migration = classification.sqliteMigration;
+    let releaseFence;
+    try {
+        releaseFence = acquireUpgradeAdmission(options, "SQLite schema migration in progress", now, callerPid);
+    }
+    catch (error) {
+        if (!(error instanceof UpgradeFenceError))
+            throw error;
+        return withClassification({
+            outcome: "blocked",
+            stage: "coordination",
+            message: `Upgrade coordination could not be acquired: ${error.message}`,
+            action: "Wait for the current maintenance operation to finish, then retry."
+        }, classification);
+    }
+    const externallyQuiesced = options.controllerLifecycle === "externally-quiesced";
+    let controllerWasRunning = false;
+    let controllerStopConfirmed = false;
+    let controllerIdentity;
+    let committed = false;
+    let result;
+    let unexpected;
+    try {
+        if (!externallyQuiesced) {
+            const controllerStatus = options.controllerStatus
+                ?? ((targetHome) => defaultControllerStatus(targetHome, options.controllerOptions));
+            let status;
+            try {
+                status = await controllerStatus(home);
+            }
+            catch (error) {
+                result = withClassification(controllerLifecycleBlocker("Controller status could not be verified", error), classification);
+            }
+            if (result === undefined && !isControllerLifecycleStatus(status)) {
+                result = withClassification(controllerLifecycleBlocker("Controller status was malformed", new Error("expected a boolean running field")), classification);
+            }
+            if (result === undefined && status.running && !isControllerLaunchIdentity(status.identity)) {
+                result = withClassification(controllerLifecycleBlocker("Controller launch identity could not be authenticated", new Error("executable/argv/version identity is unavailable")), classification);
+            }
+            if (result === undefined && status.running && !isPositivePid(status.pid)) {
+                result = withClassification(controllerLifecycleBlocker("Controller PID could not be authenticated", new Error("a positive status PID is unavailable for fenced stop")), classification);
+            }
+            if (result === undefined) {
+                controllerWasRunning = status.running;
+                controllerIdentity = status.running ? status.identity : undefined;
+                controllerStopConfirmed = !controllerWasRunning;
+            }
+            if (result === undefined && controllerWasRunning) {
+                const stopController = options.stopController
+                    ?? ((targetHome, expectedPid) => defaultStopController(targetHome, expectedPid, options.controllerOptions));
+                try {
+                    const expectedPid = status.pid;
+                    const stopped = await stopController(home, expectedPid);
+                    if (!confirmedControllerStopped(stopped, expectedPid)) {
+                        result = withClassification(controllerLifecycleBlocker("Controller stop did not confirm a drained process", new Error(`stop did not confirm captured PID ${expectedPid} with stopped:true`)), classification);
+                    }
+                    else {
+                        controllerStopConfirmed = true;
+                    }
+                }
+                catch (error) {
+                    result = withClassification(controllerLifecycleBlocker("Controller stop/drain failed", error), classification);
+                }
+            }
+        }
+        else {
+            controllerStopConfirmed = true;
+        }
+        // The first inventory is a cheap/read-only preflight. Re-read after the
+        // Controller has fully drained so a lifecycle request that committed while
+        // the fence was being placed cannot slip through on stale evidence.
+        if (result === undefined) {
+            const finalInventory = await readOfflineInventory(options, home);
+            if (finalInventory.total > 0) {
+                result = withClassification(offlineInventoryBlocker(finalInventory, true), classification);
+            }
+        }
+        if (result === undefined) {
+            try {
+                result = withUpgradeCoordinationLock(home, () => {
+                    const quiesce = verifyQuiesced(home, callerPid);
+                    if (quiesce !== null)
+                        return withClassification(quiesce, classification);
+                    const db = new Database(join(home, COMMITTED_DATABASE_FILENAME));
+                    try {
+                        db.pragma("journal_mode = WAL");
+                        db.pragma("synchronous = FULL");
+                        db.pragma("foreign_keys = ON");
+                        db.pragma("busy_timeout = 5000");
+                        const apply = db.transaction(() => {
+                            // BEGIN IMMEDIATE waits for every older SQLite writer. With the
+                            // upgrade fence still held, the state read here is the final
+                            // authoritative durable gate for the same schema transaction.
+                            const durableInventory = inspectSqliteDurableUpgradeInventory(home, db);
+                            if (durableInventory.total > 0) {
+                                return withClassification(offlineInventoryBlocker(durableInventory, true), classification);
+                            }
+                            migrateSqliteSchema(db, { mode: "apply" });
+                            return {
+                                outcome: "upgraded",
+                                classification,
+                                migrationMode: "in-place",
+                                report: sqliteInPlaceReport(options.latest, migration, "execute", now)
+                            };
+                        });
+                        const applied = apply.immediate();
+                        if (applied.outcome === "upgraded")
+                            committed = true;
+                        return applied;
+                    }
+                    finally {
+                        db.close();
+                    }
+                });
+            }
+            catch (error) {
+                unexpected = error;
+            }
+        }
+    }
+    finally {
+        try {
+            releaseFence();
+        }
+        catch (error) {
+            if (unexpected === undefined)
+                unexpected = error;
+        }
+    }
+    if (unexpected !== undefined) {
+        if (committed) {
+            return withClassification({
+                outcome: "blocked",
+                stage: "post-verify",
+                message: `SQLite migration committed but completion failed: ${messageOf(unexpected)}`,
+                action: "Do not restore the old Controller. Re-run this Yui version; the SQLite migration ledger is the commit record.",
+                storageCommitted: true
+            }, classification);
+        }
+        if (controllerWasRunning && controllerStopConfirmed) {
+            await restoreController(home, options, unexpected, controllerIdentity);
+        }
+        throw unexpected;
+    }
+    if (result === undefined)
+        throw new Error("SQLite in-place upgrade did not produce a result.");
+    if (result.outcome === "upgraded" && !externallyQuiesced && controllerWasRunning) {
+        try {
+            await (options.startController
+                ?? ((targetHome) => defaultStartController(targetHome, options.controllerOptions)))(home);
+        }
+        catch (error) {
+            return withClassification({
+                outcome: "blocked",
+                stage: "post-verify",
+                message: `SQLite migration committed but the replacement Controller did not start: ${messageOf(error)}`,
+                action: "Do not restore the old Controller. Start the current Yui Controller; the SQLite migration ledger already committed.",
+                storageCommitted: true
+            }, classification);
+        }
+        return result;
+    }
+    if (result.outcome === "blocked"
+        && !committed
+        && !externallyQuiesced
+        && controllerWasRunning
+        && controllerStopConfirmed) {
+        await restoreController(home, options, new Error(result.message), controllerIdentity);
+    }
+    return result;
+}
+function sqliteInPlaceReport(latest, migration, mode, now) {
+    const detail = `SQLite schema ${migration.currentVersion}->${migration.targetVersion}; `
+        + `pending versions ${migration.pendingVersions.join(", ")}`;
+    if (mode === "dry-run") {
+        return {
+            outcome: "dry-run",
+            mode,
+            source: latest,
+            target: latest,
+            steps: [],
+            effects: [],
+            derived: { rebuiltEffects: [] },
+            validation: {
+                checks: [{
+                        name: "SQLite staged migration and loader gate",
+                        outcome: "passed",
+                        detail: `${detail}; snapshot migrated and reopened by the current SQLite loader`
+                    }]
+            }
+        };
+    }
+    return {
+        outcome: "migrated",
+        mode,
+        source: latest,
+        target: latest,
+        steps: [],
+        effects: [],
+        derived: { rebuiltEffects: [] },
+        validation: {
+            checks: [{ name: "SQLite migration transaction", outcome: "passed", detail }]
+        },
+        switch: {
+            status: "switched",
+            detail: "SQLite schema migrated in place; no database copy or rebuild was created."
+        },
+        completedAt: now().toISOString()
+    };
+}
 /** Dry run: validate through the staged gate, then discard; never switch. */
 function dryRun(options, classification, target) {
     // Refuse to reuse a stale staging directory from an interrupted run.
@@ -390,11 +719,7 @@ async function execute(options, classification, target, callerPid, now) {
     // the other upgrader's fence.
     let releaseFence;
     try {
-        releaseFence = placeUpgradeFence(home, {
-            reason: "storage upgrade in progress",
-            createdAt: now().toISOString(),
-            ownerPid: callerPid
-        });
+        releaseFence = acquireUpgradeAdmission(options, "storage upgrade in progress", now, callerPid);
     }
     catch (error) {
         if (!(error instanceof UpgradeFenceError))
@@ -615,11 +940,7 @@ async function executePseudoLayout7Repair(options, classification, now) {
     const callerPid = options.callerPid ?? process.pid;
     let releaseFence;
     try {
-        releaseFence = placeUpgradeFence(home, {
-            reason: "storage repair in progress",
-            createdAt: now().toISOString(),
-            ownerPid: callerPid
-        });
+        releaseFence = acquireUpgradeAdmission(options, "storage repair in progress", now, callerPid);
     }
     catch (error) {
         if (!(error instanceof UpgradeFenceError))

package/dist/task/nextAction.js

@@ -50,40 +50,6 @@ export function projectNextAction(facts) {
     if (laneRecovery !== undefined) {
         return buildExecutionLaneRecoveryAction(facts, laneRecovery);
     }
-    // Quick Win (EXE-03): a resume Run that failed before durable Provider
-    // acceptance must not be retried against the same native Session.  The
-    // authoritative next action is to replace the Session, not to retry the
-    // same delivery.  The guard only applies while the failed resume Run is the
-    // *latest* Leader Run: once a newer Run exists (the fresh-Session launch),
-    // the historical failure is stale and must not keep recommending a Session
-    // replacement.
-    const latestLeaderRun = facts.leaderRuns.at(-1);
-    const failedResumeWithoutAcceptance = latestLeaderRun !== undefined
-        && latestLeaderRun.mode === "resume"
-        && latestLeaderRun.status === "failed"
-        && latestLeaderRun.deliveredAt === undefined
-        ? latestLeaderRun
-        : undefined;
-    if (failedResumeWithoutAcceptance !== undefined) {
-        return buildAction(facts, {
-            kind: "replace-leader-session",
-            reason: `Leader resume Run ${failedResumeWithoutAcceptance.id} failed before Provider acceptance; `
-                + "the native Session is proven unusable for this delivery. Replace it with a fresh Session "
-                + "after exact cleanup/reset.",
-            refs: [ref("agent-run", failedResumeWithoutAcceptance.id)],
-            preconditions: [
-                { fact: "Resume Run failed without durable acceptance", satisfied: true, ref: ref("agent-run", failedResumeWithoutAcceptance.id) },
-                { fact: "Old Session is cleaned up or reset before fresh launch", satisfied: false }
-            ],
-            // The failed resume Run is already terminal, so `task run recover
-            // --action replace-session` (which requires an active Run) cannot act
-            // on it.  The working recovery is to reset the Role's Session
-            // generation, then clear the Leader failure so the next wake launches
-            // a fresh Session (the failed-resume guard in the wakeup processor
-            // forces mode=new for the next launch).
-            recommendedCommand: `yui task role reset ${task.id} leader --reason "resume failed before acceptance" && yui jobs retry leader-recovery:${task.id}`
-        });
-    }
     const activeLeader = facts.activeRuns.find((run) => run.roleName === "leader");
     if (activeLeader !== undefined) {
         return buildAction(facts, {

package/dist/web/webSnapshot.js

@@ -224,7 +224,9 @@ function projectWebRunRuntimeHealth(reader, taskId, run, events, now, policy) {
 }
 function latestStallField(events, runId, field) {
     const stalled = events
-        .filter((event) => event.type === "run.stalled" && event.payload.runId === runId)
+        .filter((event) => event.type === "run.stalled"
+        && event.payload.runId === runId
+        && event.payload.status !== "diagnostic-only")
         .sort((left, right) => Date.parse(right.createdAt) - Date.parse(left.createdAt))[0];
     return stalled?.payload[field];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,

package/skills/yui-leader/SKILL.md

@@ -338,7 +338,9 @@ creating an explicit Task Role binding, also set and read back the required
 model and effort instead of relying on CLI defaults.
 Every managed reviewer must deliver through the current Run's exact
 `--summary-file -` yield command; a final response alone is not a durable
-handoff.
+handoff. Read the completed result as one review batch and route all reported
+findings together; do not manufacture another ReviewRound merely because one
+finding was handled before the rest of the batch.
 
 A direct or native-subagent WorkItem is roleless. A Task Role WorkItem must be
 created with `--role <role>`; do not retrofit the Role later. Reuse a compatible
@@ -782,8 +784,9 @@ yui task complete <task-id> --summary "<outcome, validation, and remaining risks
 ```
 
 Retire obsolete WorkItems with `yui task work retire <task>/<work> --summary
-"..."`, optionally using `--replacement`. If the current Role generation is
-unusable, reset it with `yui task role reset <task> <role> --reason "..."` and
-let Yui derive all runtime identities from durable state. Archiving is a
+"..."`, optionally using `--replacement`. If the current Provider Conversation
+cannot continue, request a bounded switch with
+`yui task role session switch <task> <role> --reason "..."`; the current
+Conversation remains authoritative until Yui safely binds the replacement. Archiving is a
 separate global Operator lifecycle action. It performs the final Task-owned
 runtime and clean-worktree teardown, including this Leader.

package/skills/yui-operator/SKILL.md

@@ -345,10 +345,10 @@ the workflow without claiming that version was delivered.
   conflicts on the Leader's behalf.
 - Reconcile a disappeared native Session with `task reconcile`; inspect the Run
   before retrying a confirmed failure.
-- If the current Task Role native generation cannot continue, use
-  `yui task role reset <task> <role> --reason "..."`. Let Yui derive the exact
-  Run, Agent, receipt, launch, and Session identities; never reconstruct them
-  from terminal text or ask the user to paste them.
+- If the current Provider Conversation cannot continue, use
+  `yui task role session switch <task> <role> --reason "..."`. The request is
+  audited, and Yui keeps the old Conversation authoritative until the exact
+  replacement bind succeeds; never reconstruct identities from terminal text.
 - Retry only an explicitly failed recovery Job.
 - When a Leader first-progress advisory is reported, inspect its native
   generations and absence of durable progress. It is cost evidence rather than

package/skills/yui-reviewer/SKILL.md

@@ -88,10 +88,13 @@ only its named resource, effect, and isolation boundary; never broaden it. A
 real Agent may develop or review code, but that does not authorize a real
 provider/model test.
 
-Report reachable material defects, verification gaps, checks actually run, and
-bounded next actions. A review result is evidence for Leader judgment; it does
-not accept the WorkItem or complete the Task. Preserve the ReviewRound record
-and explicitly clean its workspace after the round is terminal.
+Complete the assigned frozen-scope review before yielding. Accumulate all
+reachable findings, verification gaps, checks actually run, and bounded next
+actions, then submit them together in one Review Run result; do not yield as
+soon as the first finding is discovered. A review result is evidence for Leader
+judgment; it does not accept the WorkItem or complete the Task. Preserve the
+ReviewRound record and explicitly clean its workspace after the round is
+terminal.
 
 For normal software delivery, follow the applicable Project Policy. The
 Leader decides whether risk warrants one independent Task-final Review of the

package/dist/lifecycle/taskRoleSessionReset.js

@@ -1,118 +0,0 @@
-import { enqueueWork } from "../coordination/workMailboxQueue.js";
-import { resetTaskRoleSession } from "../executor/agentExecutor.js";
-import { createTaskEvent } from "../event/taskEvent.js";
-import { createTaskMessage } from "../message/message.js";
-import { updateRoleStatus } from "../role/role.js";
-import { enqueueOperatorEvent } from "../scheduler/operatorEvent.js";
-import { recordLeaderFailure } from "../scheduler/leaderFailure.js";
-import { RUNTIME_CLEANUP_REQUIRED_REASON, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
-import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
-import { updateWorkItemStatus, workItemOwnsUnresolvedExecutionLane } from "../workItem/workItem.js";
-import { terminalizeExactTaskRun } from "./exactRunTerminalization.js";
-/**
- * Resets the current native generation using Yui's own persisted identities.
- * The caller supplies intent only; the Controller verifies process cleanup.
- */
-export function resetTaskRoleSessionGeneration(store, taskId, roleName, reason, now) {
-    const task = store.getTask(requiredIdentity(taskId, "Task id"));
-    if (task === null)
-        throw new Error(`Task not found: ${taskId}.`);
-    if (task.status !== "active")
-        throw new Error(`Task is not active: ${task.id}/${task.status}.`);
-    const normalizedRole = requiredIdentity(roleName, "Role name");
-    const role = store.getRole(task.id, normalizedRole);
-    if (role === null)
-        throw new Error(`Role not found: ${task.id}/${normalizedRole}.`);
-    const summary = `Reset native Session: ${requiredText(reason, "Reset reason")}`;
-    let sessions = store.getTaskRoleSessionSet(task.id, role.name);
-    const current = sessions?.sessions[sessions.activeAgentId];
-    const activeRun = store.getActiveAgentRun(task.id, role.name);
-    if (activeRun !== null) {
-        const receiptId = sessions?.inFlight?.runId === activeRun.id
-            ? sessions.inFlight.receiptId
-            : formatAgentRunReceiptId(task.id, activeRun.id);
-        const terminal = terminalizeExactTaskRun(store, {
-            taskId: task.id,
-            roleName: role.name,
-            agentId: activeRun.effective.agentId,
-            runId: activeRun.id,
-            receiptId,
-            ...(current === undefined ? {} : {
-                nativeSessionId: current.nativeSessionId,
-                ...(current.launchId === undefined ? {} : { launchId: current.launchId })
-            }),
-            outcome: { status: "failed", summary }
-        }, now);
-        if (terminal.disposition !== "applied" || terminal.run === null) {
-            throw new Error(`Task Role reset lost its exact Run fence: ${terminal.reason ?? "obsolete"}.`);
-        }
-        if (activeRun.purpose === "execution" && activeRun.workItemId !== undefined) {
-            const item = store.getWorkItem(task.id, activeRun.workItemId);
-            if (item !== null
-                && !["completed", "failed", "retired"].includes(item.status)
-                && !workItemOwnsUnresolvedExecutionLane(item, activeRun.executionGroupId, activeRun.executionLaneId)) {
-                store.saveWorkItem(task.id, updateWorkItemStatus(item, "failed", now, summary));
-            }
-        }
-    }
-    enqueueWork(store, runtimeLifecycleTarget({
-        scope: "task",
-        taskId: task.id,
-        roleName: role.name
-    }), RUNTIME_CLEANUP_REQUIRED_REASON, now, [{ type: "task", id: task.id }]);
-    sessions = store.getTaskRoleSessionSet(task.id, role.name);
-    if (sessions !== null)
-        store.saveTaskRoleSessionSet(resetTaskRoleSession(sessions, now));
-    const updatedRole = store.getRole(task.id, role.name);
-    store.saveRole(task.id, updateRoleStatus(updatedRole, role.name === "leader" ? "failed" : "idle", now));
-    const message = createTaskMessage(store.nextMessageId(task.id), task.id, summary, "system", { type: "system" }, now, activeRun === null ? {} : {
-        runId: activeRun.id,
-        ...(activeRun.workItemId === undefined ? {} : { workItemId: activeRun.workItemId })
-    });
-    store.saveMessage(task.id, message);
-    const resetEvent = createTaskEvent(store.nextEventId(task.id), task.id, "runtime.role-session-reset", {
-        roleName: role.name,
-        reason: summary,
-        ...(activeRun === null ? {} : { runId: activeRun.id }),
-        ...(current?.nativeSessionId === undefined
-            ? {}
-            : { nativeSessionId: current.nativeSessionId })
-    }, now);
-    store.saveEvent(task.id, resetEvent);
-    if (role.name === "leader") {
-        const nativeSessionId = current?.nativeSessionId ?? `reset-${task.id}`;
-        store.saveLeaderFailure(recordLeaderFailure(task.id, nativeSessionId, summary, now, store.getLeaderFailure(task.id)));
-        enqueueOperatorEvent(store, resetEvent, "leader-run-failed", now);
-    }
-    else {
-        enqueueWork(store, { kind: "role", taskId: task.id, roleName: "leader" }, "role-run-failed", now, [
-            { type: "message", taskId: task.id, id: message.id },
-            ...(activeRun === null ? [] : [{
-                    type: "run",
-                    taskId: task.id,
-                    id: activeRun.id
-                }])
-        ]);
-    }
-    return {
-        taskId: task.id,
-        roleName: role.name,
-        run: activeRun === null ? null : store.getAgentRun(task.id, activeRun.id),
-        ...(current === undefined ? {} : { nativeSessionId: current.nativeSessionId })
-    };
-}
-function requiredIdentity(value, label) {
-    const normalized = requiredText(value, label);
-    if (["__proto__", "prototype", "constructor", ".", ".."].includes(normalized)
-        || /[\/\\\0]/u.test(normalized))
-        throw new Error(`${label} is invalid.`);
-    return normalized;
-}
-function requiredText(value, label) {
-    if (typeof value !== "string" || value.includes("\0"))
-        throw new Error(`${label} is invalid.`);
-    const normalized = value.trim();
-    if (normalized.length === 0)
-        throw new Error(`${label} is required.`);
-    return normalized;
-}