@zq-silk/yui 0.6.16 → 0.7.1

package/dist/scheduler/roleRunLiveness.js

@@ -1,9 +1,6 @@
 import { selectedSchedulerRoles, selectedActiveSchedulerTasks } from "./ports.js";
 import { formatTaskRecordReference } from "../task/taskRecordReference.js";
-import { queueLeaderWakeup } from "./wakeupQueue.js";
-import { wakeReason } from "./wakeReason.js";
 import { currentRoleRunProgressAt, DEFAULT_WORKFLOW_STALL_CANDIDATE_AGE_MS } from "./roleRunStall.js";
-export const EXITED_ROLE_RUN_SUMMARY = "The role's tmux session exited before the run yielded.";
 /**
  * Lightweight liveness only. Host absence may fail a Run only before any
  * prompt bytes were pushed. After push, acceptance may be unknown even when
@@ -11,6 +8,9 @@ export const EXITED_ROLE_RUN_SUMMARY = "The role's tmux session exited before th
  * evidence, not an application-level outcome. The Run stays active so native
  * child work or another observer can still contribute facts, while the stall
  * path raises bounded attention independently.
+ * Process liveness is only a recovery signal. An absent pane/Host never proves
+ * that the native Session or AgentRun ended; recover the same generation and
+ * native identity when possible, otherwise preserve the active Run.
  */
 export async function reconcileExitedRoleRuns(store, delivery, now, selection, excludedRunRefs = new Set(), liveStatuses, resourceEvidence, targetedInventory = selection !== undefined && !selection.full) {
     const failed = [];
@@ -52,7 +52,8 @@ export async function reconcileExitedRoleRuns(store, delivery, now, selection, e
         && candidates.every(({ task, role }) => liveStatuses.has(`${task.id}\0${role.name}`))
         ? {
             statuses: liveStatuses,
-            resources: resourceEvidence ?? new Map()
+            resources: resourceEvidence ?? new Map(),
+            hostExits: new Map()
         }
         : await inspectRoleStatuses(delivery, candidates, !targetedInventory
             ? candidates.flatMap(({ task, role, run, session }) => (isResourceCandidate(task, run, now)
@@ -90,27 +91,57 @@ export async function reconcileExitedRoleRuns(store, delivery, now, selection, e
             throw new Error("Role liveness snapshot is incomplete.");
         if (status === "present")
             continue;
-        const persisted = store.saveExitedRoleRun({
-            task,
-            role,
-            run,
-            session,
-            summary: EXITED_ROLE_RUN_SUMMARY,
-            now
-        });
-        if (persisted === "state-changed")
+        const hostExit = batchSnapshot.hostExits.get(`${task.id}\0${role.name}`);
+        if (hostExit !== undefined) {
+            store.saveRoleHostExitObservation?.({
+                taskId: task.id,
+                roleName: role.name,
+                runId: run.id,
+                ...(session?.launchId === undefined ? {} : { launchId: session.launchId }),
+                ...(session?.nativeSessionId === undefined
+                    ? {}
+                    : { nativeSessionId: session.nativeSessionId }),
+                ...(hostExit.deadStatus === undefined ? {} : { deadStatus: hostExit.deadStatus }),
+                observedAt: now
+            });
+        }
+        if (session?.nativeSessionId === undefined) {
+            store.queueTaskProgress(task.id, "host-missing-native-resume-unproven", now);
             continue;
-        delivery.forgetPrepared?.({
-            taskId: task.id,
-            roleName: role.name,
-            runId: run.id
-        });
-        failed.push(formatTaskRecordReference(task.id, run.id, "agentRun"));
-        // Compatibility for narrow in-memory/custom ports that predate the
-        // adapter's atomic failure+wake transition. Production returns
-        // "failed" and already enqueued this wake in the same transaction.
-        if (persisted === undefined && task.status === "active") {
-            queueLeaderWakeup(store, task.id, wakeReason(role.name === "leader" ? "leader-run-failed" : "role-run-failed"), now);
+        }
+        try {
+            delivery.forgetPrepared?.({
+                taskId: task.id,
+                roleName: role.name,
+                runId: run.id
+            });
+            const recovered = await delivery.prepareRoleSession({
+                taskId: task.id,
+                roleName: role.name,
+                agentId: run.effective.agentId,
+                adapterId: run.effective.adapterId,
+                effective: run.effective,
+                workspace: run.effective.workspace.root,
+                ...(run.workspace === undefined ? {} : { managedWorkspace: run.workspace }),
+                mode: "resume",
+                runId: run.id,
+                nativeSessionId: session.nativeSessionId
+            });
+            store.saveRoleRunPrepared({
+                task,
+                role,
+                run,
+                session: recovered.session ?? session,
+                ...(recovered.launchId === undefined ? {} : { launchId: recovered.launchId }),
+                now
+            });
+            liveStatuses?.set(`${task.id}\0${role.name}`, "present");
+        }
+        catch {
+            // Absence plus an inconclusive local recovery attempt is still not a
+            // native Session death proof. Keep the exact Run active for the next
+            // bounded recovery pass and expose the blocked axis separately.
+            store.queueTaskProgress(task.id, "host-missing-native-resume-pending", now);
         }
     }
     return failed;
@@ -129,7 +160,7 @@ async function inspectRoleStatuses(delivery, candidates, resourceInputs, targete
             }
             statuses.set(key, await delivery.inspectRole(candidate.inspection));
         }
-        return { statuses, resources: new Map() };
+        return { statuses, resources: new Map(), hostExits: new Map() };
     }
     if (delivery.inspectRoles !== undefined) {
         return exactBatchInventory(await delivery.inspectRoles(candidates.map(({ inspection }) => inspection), resourceInputs), candidates);
@@ -141,12 +172,13 @@ async function inspectRoleStatuses(delivery, candidates, resourceInputs, targete
             await delivery.inspectRole(candidate.inspection)
         ]);
     }
-    return { statuses: new Map(entries), resources: new Map() };
+    return { statuses: new Map(entries), resources: new Map(), hostExits: new Map() };
 }
 function exactBatchInventory(batch, candidates) {
     const expected = new Set(candidates.map(({ task, role }) => `${task.id}\0${role.name}`));
     const statuses = new Map();
     const resources = new Map();
+    const hostExits = new Map();
     for (const entry of batch) {
         const key = `${entry.taskId}\0${entry.roleName}`;
         if (!expected.has(key) || statuses.has(key)) {
@@ -155,11 +187,13 @@ function exactBatchInventory(batch, candidates) {
         statuses.set(key, entry.status);
         if (entry.resource !== undefined)
             resources.set(key, entry.resource);
+        if (entry.hostExit !== undefined)
+            hostExits.set(key, entry.hostExit);
     }
     if (statuses.size !== expected.size) {
         throw new Error("Tmux Role batch liveness snapshot is incomplete.");
     }
-    return { statuses, resources };
+    return { statuses, resources, hostExits };
 }
 function isResourceCandidate(task, run, now) {
     if (task.status !== "active" || run.status !== "active" || run.deliveredAt === undefined) {

package/dist/storage/migration/productionRegistry.js

@@ -35,6 +35,10 @@ const AGENT_RUN_TO_VERSION = 6;
  */
 const AGENT_RUN_OPTIONAL_FIELDS_FROM_VERSION = 6;
 const AGENT_RUN_OPTIONAL_FIELDS_TO_VERSION = 7;
+const AGENT_RUN_CONTEXT_PROTOCOL_FROM_VERSION = 7;
+const AGENT_RUN_CONTEXT_PROTOCOL_TO_VERSION = 8;
+const AGENT_RUN_RETRY_EPISODE_FROM_VERSION = 8;
+const AGENT_RUN_RETRY_EPISODE_TO_VERSION = 9;
 const MESSAGE_WAKE_POLICY_FROM_VERSION = 2;
 const MESSAGE_WAKE_POLICY_TO_VERSION = 3;
 const REVIEW_ROUND_FROM_VERSION = 2;
@@ -55,6 +59,8 @@ const INTEGRATION_ATTEMPT_GATE_IDENTITY_FROM_VERSION = 3;
 const INTEGRATION_ATTEMPT_GATE_IDENTITY_TO_VERSION = 4;
 const INTEGRATION_QUEUE_FROM_VERSION = 0;
 const INTEGRATION_QUEUE_TO_VERSION = 1;
+const CONTEXT_SNAPSHOT_FROM_VERSION = 0;
+const CONTEXT_SNAPSHOT_TO_VERSION = 1;
 const STORED_TASK_DURABLE_JOBS_FROM_VERSION = 14;
 const STORED_TASK_DURABLE_JOBS_TO_VERSION = 15;
 const STORED_TASK_JOB_CALLER_KEY_HASHES_FROM_VERSION = 15;
@@ -130,6 +136,8 @@ export function createProductionStorageRegistry() {
         .registerOfflineMigration(workItemExecutionGroupHistoryStep())
         .registerOfflineMigration(recordFamilyStep("agentRun", AGENT_RUN_FROM_VERSION, AGENT_RUN_TO_VERSION, "agentRuns"))
         .registerOfflineMigration(recordFamilyStep("agentRun", AGENT_RUN_OPTIONAL_FIELDS_FROM_VERSION, AGENT_RUN_OPTIONAL_FIELDS_TO_VERSION, "agentRuns"))
+        .registerOfflineMigration(agentRunContextProtocolStep())
+        .registerOfflineMigration(agentRunRetryEpisodeStep())
         .registerOfflineMigration(messageWakePolicyStep())
         .registerOfflineMigration(recordFamilyStep("reviewRound", REVIEW_ROUND_FROM_VERSION, REVIEW_ROUND_TO_VERSION, "reviewRounds"))
         .registerOfflineMigration(recordFamilyStep("reviewRound", REVIEW_ROUND_GIT_SNAPSHOT_FROM_VERSION, REVIEW_ROUND_GIT_SNAPSHOT_TO_VERSION, "reviewRounds"))
@@ -140,6 +148,7 @@ export function createProductionStorageRegistry() {
         .registerOfflineMigration(integrationAttemptSupersededStep())
         .registerOfflineMigration(recordFamilyStep("integrationAttempt", INTEGRATION_ATTEMPT_GATE_IDENTITY_FROM_VERSION, INTEGRATION_ATTEMPT_GATE_IDENTITY_TO_VERSION, "integrationAttempts"))
         .registerOfflineMigration(integrationQueueIntroductionStep())
+        .registerOfflineMigration(contextSnapshotIntroductionStep())
         .registerCompatible(storedTaskDurableJobsStep())
         .registerCompatible(storedTaskJobCallerKeyHashesStep())
         .registerCompatible(storedTaskWakesAndPublicationReferencesStep())
@@ -725,6 +734,71 @@ function introduceIntegrationQueue(snapshot) {
         state: { ...snapshot.state, tasks: nextTasks }
     };
 }
+/** Introduce the immutable Task-scoped ContextSnapshot record family. */
+function contextSnapshotIntroductionStep() {
+    return {
+        axis: "record",
+        recordKind: "contextSnapshot",
+        fromVersion: CONTEXT_SNAPSHOT_FROM_VERSION,
+        toVersion: CONTEXT_SNAPSHOT_TO_VERSION,
+        introduction: true,
+        preconditions: requireContextSnapshotIntroduction,
+        transform: introduceContextSnapshots,
+        declaredEffects: []
+    };
+}
+function requireContextSnapshotIntroduction(snapshot) {
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const namedVersion = manifestVersions.contextSnapshot;
+    if (namedVersion !== undefined && namedVersion !== CONTEXT_SNAPSHOT_FROM_VERSION) {
+        throw new Error("Record contextSnapshot introduction requires an absent manifest version or 0.");
+    }
+    if (snapshot.state === null)
+        return;
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        if (task.contextSnapshots !== undefined) {
+            const records = asObject(task.contextSnapshots, `contextSnapshot map ${taskId}`);
+            if (Object.keys(records).length > 0) {
+                throw new Error(`Context Snapshot introduction found existing records: ${taskId}.`);
+            }
+        }
+        const marks = asObject(task.idHighWaterMarks ?? {}, `Task id high-water marks ${taskId}`);
+        const mark = marks.contextSnapshot;
+        if (mark !== undefined && mark !== CONTEXT_SNAPSHOT_FROM_VERSION) {
+            throw new Error(`Context Snapshot introduction found a high-water mark: ${taskId}.`);
+        }
+    }
+}
+function introduceContextSnapshots(snapshot) {
+    requireContextSnapshotIntroduction(snapshot);
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: {
+            ...manifestVersions,
+            contextSnapshot: CONTEXT_SNAPSHOT_TO_VERSION
+        }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        const marks = asObject(task.idHighWaterMarks ?? {}, `Task id high-water marks ${taskId}`);
+        nextTasks[taskId] = {
+            ...task,
+            idHighWaterMarks: { ...marks, contextSnapshot: 0 },
+            contextSnapshots: {}
+        };
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, tasks: nextTasks }
+    };
+}
 function legacyLaneKeyParts(key) {
     const match = /^lane:([^:]+):([^:]+)$/u.exec(key);
     if (match === null)
@@ -1411,6 +1485,196 @@ function recordFamilyStep(recordKind, fromVersion, toVersion, taskMapKey) {
         declaredEffects: []
     };
 }
+function agentRunContextProtocolStep() {
+    return {
+        axis: "record",
+        recordKind: "agentRun",
+        fromVersion: AGENT_RUN_CONTEXT_PROTOCOL_FROM_VERSION,
+        toVersion: AGENT_RUN_CONTEXT_PROTOCOL_TO_VERSION,
+        preconditions: (snapshot) => requireRecordFamilyVersion(snapshot, "agentRun", AGENT_RUN_CONTEXT_PROTOCOL_FROM_VERSION, "agentRuns"),
+        transform: migrateAgentRunsToContextProtocol,
+        declaredEffects: []
+    };
+}
+function migrateAgentRunsToContextProtocol(snapshot) {
+    requireRecordFamilyVersion(snapshot, "agentRun", AGENT_RUN_CONTEXT_PROTOCOL_FROM_VERSION, "agentRuns");
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: {
+            ...manifestVersions,
+            agentRun: AGENT_RUN_CONTEXT_PROTOCOL_TO_VERSION
+        }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        const records = asObject(task.agentRuns ?? {}, `agentRun map ${taskId}`);
+        const nextRecords = {};
+        for (const [runId, rawRecord] of Object.entries(records)) {
+            const record = asObject(rawRecord, `agentRun ${taskId}/${runId}`);
+            const { input: rawInput, schemaVersion: _schemaVersion, ...rest } = record;
+            const roleName = requiredMigrationText(record.roleName, "Agent Run roleName");
+            const purpose = record.purpose === "review" ? "review" : "execution";
+            const workItemId = optionalMigrationText(record.workItemId, "Agent Run workItemId");
+            const reviewRoundId = optionalMigrationText(record.reviewRoundId, "Agent Run reviewRoundId");
+            const executionGroupId = optionalMigrationText(record.executionGroupId, "Agent Run executionGroupId");
+            const executionLaneId = optionalMigrationText(record.executionLaneId, "Agent Run executionLaneId");
+            const action = purpose === "review"
+                ? "review-round"
+                : roleName === "leader"
+                    ? "leader-wake"
+                    : workItemId === undefined
+                        ? "lead-task"
+                        : "execute-work-item";
+            const subject = {
+                taskId,
+                ...(workItemId === undefined ? {} : { workItemId }),
+                ...(reviewRoundId === undefined ? {} : { reviewRoundId }),
+                ...(executionGroupId === undefined ? {} : { executionGroupId }),
+                ...(executionLaneId === undefined ? {} : { executionLaneId })
+            };
+            const assignment = {
+                schemaVersion: 1,
+                runId,
+                roleName,
+                purpose,
+                action,
+                subject,
+                ...(typeof rawInput === "string" && rawInput.trim().length > 0
+                    ? { directive: rawInput }
+                    : {}),
+                deltaRefIds: []
+            };
+            nextRecords[runId] = {
+                ...rest,
+                schemaVersion: AGENT_RUN_CONTEXT_PROTOCOL_TO_VERSION,
+                assignment,
+                bootstrapEnvelope: {
+                    protocol: "yui-run/v1",
+                    runId,
+                    roleName,
+                    purpose,
+                    action,
+                    subject,
+                    deltaRefIds: []
+                }
+            };
+        }
+        nextTasks[taskId] = { ...task, agentRuns: nextRecords };
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, tasks: nextTasks }
+    };
+}
+function agentRunRetryEpisodeStep() {
+    return {
+        axis: "record",
+        recordKind: "agentRun",
+        fromVersion: AGENT_RUN_RETRY_EPISODE_FROM_VERSION,
+        toVersion: AGENT_RUN_RETRY_EPISODE_TO_VERSION,
+        preconditions: (snapshot) => requireRecordFamilyVersion(snapshot, "agentRun", AGENT_RUN_RETRY_EPISODE_FROM_VERSION, "agentRuns"),
+        transform: migrateAgentRunsToRetryEpisodes,
+        declaredEffects: []
+    };
+}
+function migrateAgentRunsToRetryEpisodes(snapshot) {
+    requireRecordFamilyVersion(snapshot, "agentRun", AGENT_RUN_RETRY_EPISODE_FROM_VERSION, "agentRuns");
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...manifestVersions, agentRun: AGENT_RUN_RETRY_EPISODE_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        const records = asObject(task.agentRuns ?? {}, `agentRun map ${taskId}`);
+        const nextRecords = {};
+        for (const [runId, rawRecord] of Object.entries(records)) {
+            const record = asObject(rawRecord, `agentRun ${taskId}/${runId}`);
+            const legacyRetry = record.providerRetry === undefined
+                ? undefined
+                : asObject(record.providerRetry, `providerRetry ${taskId}/${runId}`);
+            let providerRetry = undefined;
+            let deliveryReceiptId;
+            if (legacyRetry !== undefined) {
+                const attempt = requiredMigrationPositiveInteger(legacyRetry.attempt, `providerRetry attempt ${taskId}/${runId}`);
+                const firstFailureAt = requiredMigrationTimestamp(legacyRetry.firstFailureAt, `providerRetry firstFailureAt ${taskId}/${runId}`);
+                const lastFailureAt = requiredMigrationTimestamp(legacyRetry.lastFailureAt, `providerRetry lastFailureAt ${taskId}/${runId}`);
+                const nextAttemptAt = optionalMigrationTimestamp(legacyRetry.nextAttemptAt, `providerRetry nextAttemptAt ${taskId}/${runId}`);
+                const policyBlocked = legacyRetry.errorClass === "policy-denied";
+                const deadlineMs = Math.max(Date.parse(firstFailureAt) + 600_000, nextAttemptAt === undefined ? 0 : Date.parse(nextAttemptAt) + 1);
+                deliveryReceiptId = nextAttemptAt !== undefined || policyBlocked
+                    ? undefined
+                    : `legacy-retry-receipt-${runId}-${attempt}`;
+                providerRetry = {
+                    schemaVersion: 2,
+                    episodeId: `legacy-retry-${runId}`,
+                    failureEventId: `legacy-provider-failure-${runId}-${attempt}`,
+                    policyVersion: 1,
+                    state: nextAttemptAt !== undefined
+                        ? "scheduled"
+                        : policyBlocked ? "blocked" : "awaiting-progress",
+                    errorClass: legacyRetry.errorClass,
+                    consecutiveFailures: attempt,
+                    dispatchedRetries: Math.min(3, nextAttemptAt === undefined ? attempt : attempt - 1),
+                    maxRetries: 3,
+                    firstFailureAt,
+                    lastFailureAt,
+                    episodeDeadlineAt: new Date(deadlineMs).toISOString(),
+                    ...(nextAttemptAt === undefined ? {} : { nextAttemptAt }),
+                    ...(deliveryReceiptId === undefined
+                        ? {}
+                        : { lastRetryReceiptId: deliveryReceiptId }),
+                    ...(legacyRetry.launchId === undefined ? {} : { launchId: legacyRetry.launchId }),
+                    ...(legacyRetry.nativeSessionId === undefined
+                        ? {}
+                        : { nativeSessionId: legacyRetry.nativeSessionId }),
+                    lastErrorSummary: legacyRetry.lastErrorSummary
+                };
+            }
+            nextRecords[runId] = {
+                ...record,
+                schemaVersion: AGENT_RUN_RETRY_EPISODE_TO_VERSION,
+                ...(deliveryReceiptId === undefined ? {} : { deliveryReceiptId }),
+                ...(providerRetry === undefined ? {} : { providerRetry })
+            };
+        }
+        nextTasks[taskId] = { ...task, agentRuns: nextRecords };
+    }
+    return { schemaManifest, state: { ...snapshot.state, tasks: nextTasks } };
+}
+function requiredMigrationPositiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`${label} must be a positive integer.`);
+    }
+    return value;
+}
+function requiredMigrationTimestamp(value, label) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+        throw new Error(`${label} must be a timestamp.`);
+    }
+    return value;
+}
+function optionalMigrationTimestamp(value, label) {
+    return value === undefined ? undefined : requiredMigrationTimestamp(value, label);
+}
+function requiredMigrationText(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value.trim();
+}
+function optionalMigrationText(value, label) {
+    return value === undefined ? undefined : requiredMigrationText(value, label);
+}
 /**
  * The snapshot boundary is nested inside WorkItem/ReviewRound ExecutionGroup
  * results.  The parent record versions make that persisted shape explicit;

package/dist/storage/sqliteSchema.js

@@ -27,7 +27,7 @@ export const SQLITE_LAYOUT_VERSION = 7;
 /** The aggregate version of the normalized SQLite schema. */
 export const SQLITE_AGGREGATE_VERSION = 1;
 /** The current schema migration version. */
-export const SQLITE_SCHEMA_VERSION = 16;
+export const SQLITE_SCHEMA_VERSION = 17;
 /** Telemetry retention bounds (§4.4). Open question 3 in §11; defaults from the design. */
 export const TELEMETRY_KEEP_PER_GENERATION = 200;
 export const TELEMETRY_RUN_CAP = 50_000;
@@ -911,6 +911,25 @@ CREATE TABLE IF NOT EXISTS task_wakes (
 );
 CREATE INDEX IF NOT EXISTS idx_task_wakes_seq ON task_wakes(task_id, seq);
 `;
+/** Migration 17: immutable, Task-scoped ContextSnapshot records. */
+const MIGRATION_17_SQL = `
+CREATE TABLE IF NOT EXISTS context_snapshots (
+  task_id     TEXT NOT NULL,
+  snapshot_id TEXT NOT NULL,
+  scope       TEXT NOT NULL CHECK (scope IN ('task','workitem','stage')),
+  scope_ref   TEXT,
+  sequence    INTEGER NOT NULL CHECK (sequence > 0),
+  digest      TEXT NOT NULL CHECK (length(digest) = 64),
+  payload     TEXT NOT NULL,
+  frozen_at   TEXT NOT NULL,
+  PRIMARY KEY (task_id, snapshot_id),
+  FOREIGN KEY (task_id) REFERENCES tasks_catalog(task_id) ON DELETE CASCADE,
+  CHECK ((scope = 'task' AND scope_ref IS NULL) OR (scope <> 'task' AND scope_ref IS NOT NULL))
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_context_snapshots_scope_sequence
+  ON context_snapshots(task_id, scope, COALESCE(scope_ref, ''), sequence);
+`;
 const MIGRATIONS = [
     { version: 1, axis: "layout", sql: MIGRATION_1_SQL },
     { version: 2, axis: "record", recordKind: "durableJob+capability-grant+release-workflow", sql: MIGRATION_2_SQL },
@@ -927,7 +946,8 @@ const MIGRATIONS = [
     { version: 13, axis: "layout", sql: MIGRATION_13_SQL },
     { version: 14, axis: "record", recordKind: "workMailbox", sql: MIGRATION_14_SQL },
     { version: 15, axis: "record", recordKind: "publicationReference", sql: MIGRATION_15_SQL },
-    { version: 16, axis: "record", recordKind: "taskWake", sql: MIGRATION_16_SQL }
+    { version: 16, axis: "record", recordKind: "taskWake", sql: MIGRATION_16_SQL },
+    { version: 17, axis: "record", recordKind: "contextSnapshot", sql: MIGRATION_17_SQL }
 ];
 /** Current hot-path indexes whose absence would invalidate a current Home. */
 const REQUIRED_SCHEMA_INDEXES = [
@@ -1169,6 +1189,7 @@ export const SQLITE_SCHEMA_TABLES = [
     "role_session_sets",
     "work_items",
     "work_item_candidates",
+    "context_snapshots",
     "agent_runs",
     "active_runs",
     "review_rounds",

package/dist/storage/sqliteStore.js

@@ -39,6 +39,7 @@ import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import Database from "better-sqlite3";
 import { consumePendingBatch, mailboxTargetKey, pendingLane, validateWorkMailbox } from "../coordination/workMailbox.js";
+import { validateContextSnapshot } from "../context/contextSnapshot.js";
 import { compareRuntimeSessionCandidates, projectRuntimeSessionCandidate } from "../runtime/runtimeSessionCandidate.js";
 import { validateReviewFinding } from "../review/reviewFinding.js";
 import { reviewFindingLedgerMode } from "../review/reviewFindingLedger.js";
@@ -1418,6 +1419,37 @@ export class SqliteTaskStore {
             return Object.freeze({ retained, deleted: toDelete.length });
         });
     }
+    // -- context snapshots ------------------------------------------------------
+    nextContextSnapshotId(taskId) {
+        return this.#nextTaskRecordId(taskId, "contextSnapshot");
+    }
+    getContextSnapshot(taskId, snapshotId) {
+        return this.#getPayload("context_snapshots", "task_id = ? AND snapshot_id = ?", [taskId, snapshotId]);
+    }
+    listContextSnapshots(taskId) {
+        return this.#sortById(this.#listPayload("context_snapshots", "task_id = ?", [taskId]), (snapshot) => snapshot.id);
+    }
+    saveContextSnapshot(snapshot) {
+        const stored = validateContextSnapshot(snapshot);
+        this.#requireTask(stored.taskId);
+        const existing = this.getContextSnapshot(stored.taskId, stored.id);
+        if (existing !== null) {
+            if (!isDeepStrictEqual(existing, stored)) {
+                throw new StorageRecordError(`Context Snapshot is immutable: ${stored.id}.`);
+            }
+            return;
+        }
+        const duplicate = this.#db.prepare(`SELECT snapshot_id FROM context_snapshots
+       WHERE task_id = ? AND scope = ? AND COALESCE(scope_ref, '') = COALESCE(?, '') AND sequence = ?`).get(stored.taskId, stored.scope, stored.scopeRef ?? null, stored.sequence);
+        if (duplicate !== undefined) {
+            throw new StorageRecordError(`Context Snapshot sequence already exists: ${stored.taskId}/${stored.scope}/${stored.sequence}.`);
+        }
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO context_snapshots
+          (task_id, snapshot_id, scope, scope_ref, sequence, digest, payload, frozen_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(stored.taskId, stored.id, stored.scope, stored.scopeRef ?? null, stored.sequence, stored.digest, this.#json(stored), stored.frozenAt);
+        });
+    }
     // -- agent runs -------------------------------------------------------------
     nextAgentRunId(taskId) { return this.#nextTaskRecordId(taskId, "agentRun"); }
     peekNextAgentRunId(taskId) { return this.#peekTaskRecordId(taskId, "agentRun"); }
@@ -1451,13 +1483,18 @@ export class SqliteTaskStore {
             ? ""
             : ` AND tc.task_id IN (${selectedTaskIds.map(() => "?").join(", ")})`;
         const rows = this.#db.prepare(`SELECT DISTINCT ar.task_id AS taskId, ar.run_id AS runId, ar.role_name AS roleName,
-              json_extract(ar.payload, '$.providerRetry.nextAttemptAt') AS nextAttemptAt
+              json_extract(ar.payload, '$.providerRetry.state') AS state,
+              CASE json_extract(ar.payload, '$.providerRetry.state')
+                WHEN 'scheduled' THEN json_extract(ar.payload, '$.providerRetry.nextAttemptAt')
+                ELSE json_extract(ar.payload, '$.providerRetry.episodeDeadlineAt')
+              END AS dueAt
        FROM tasks_catalog tc INDEXED BY idx_tasks_active
        JOIN active_runs ap ON ap.task_id = tc.task_id
        JOIN agent_runs ar ON ar.task_id = ap.task_id AND ar.run_id = ap.run_id
        WHERE tc.is_active = 1
          AND ar.status = 'active'
-         AND json_extract(ar.payload, '$.providerRetry.nextAttemptAt') IS NOT NULL${taskPredicate}`).all(...(selectedTaskIds ?? []));
+         AND json_extract(ar.payload, '$.providerRetry.state') IN
+           ('scheduled', 'dispatching', 'awaiting-progress')${taskPredicate}`).all(...(selectedTaskIds ?? []));
         return rows.sort((left, right) => (numericCompare(left.taskId, right.taskId)
             || numericCompare(left.roleName, right.roleName)
             || numericCompare(left.runId, right.runId)));
@@ -1886,13 +1923,20 @@ export class SqliteTaskStore {
         return rows.map((row) => this.#rowToMailbox(row));
     }
     saveWorkMailbox(mailbox) {
-        const cols = this.#mailboxCols(mailbox.target);
+        let validated;
+        try {
+            validated = validateWorkMailbox(mailbox);
+        }
+        catch (error) {
+            throw new StorageRecordError(error instanceof Error ? error.message : String(error));
+        }
+        const cols = this.#mailboxCols(validated.target);
         this.#mutate(() => {
             this.#db.prepare(`INSERT INTO mailboxes (target_kind, task_id, role_name, target_key, next_sequence, processing, pending, input_delivery)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT(target_key) DO UPDATE SET next_sequence = excluded.next_sequence,
            processing = excluded.processing, pending = excluded.pending,
-           input_delivery = excluded.input_delivery`).run(cols.targetKind, cols.taskId, cols.roleName, cols.targetKey, mailbox.nextSequence, mailbox.processing === null ? null : this.#json(mailbox.processing), this.#json(mailbox.pending), mailbox.inputDelivery === null ? null : this.#json(mailbox.inputDelivery));
+           input_delivery = excluded.input_delivery`).run(cols.targetKind, cols.taskId, cols.roleName, cols.targetKey, validated.nextSequence, validated.processing === null ? null : this.#json(validated.processing), this.#json(validated.pending), validated.inputDelivery === null ? null : this.#json(validated.inputDelivery));
         });
     }
     removeWorkMailbox(target) {