@zq-silk/yui 2.16.0 → 2.18.0

package/dist/scheduler/roleRunLiveness.js

@@ -1,3 +1,4 @@
+import { isEnabled } from "../role/availability.js";
 import { runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
 import { formatTaskRecordReference } from "../task/taskRecordReference.js";
 import { selectedActiveSchedulerTasks, selectedSchedulerRoles } from "./ports.js";
@@ -104,6 +105,8 @@ export async function reconcileExitedRoleRuns(store, delivery, now, selection, e
                 observedAt: now
             });
         }
+        if (!isEnabled(role))
+            continue;
         if (session?.nativeSessionId === undefined) {
             store.queueTaskProgress(task.id, "host-missing-native-resume-unproven", now);
             continue;

package/dist/scheduler/roleRunStall.js

@@ -460,9 +460,9 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
     if (stallCandidates.length === 0)
         return [];
     const diagnosticStartedAt = now.toISOString();
-    const finishDiagnostics = (outcome) => {
+    const finishDiagnostics = async (outcome) => {
         for (const { task, role, run } of stallCandidates) {
-            store.recordRoleRunDiagnostic({
+            await store.recordRoleRunDiagnostic({
                 taskId: task.id,
                 roleName: role.name,
                 runId: run.id,
@@ -523,7 +523,7 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
             // Health inspection is advisory. Unknown host state must leave the exact
             // AgentRun/Session fence untouched. Closing this window schedules the next
             // bounded diagnostic thirty minutes later instead of hot-looping.
-            finishDiagnostics("observation-error");
+            await finishDiagnostics("observation-error");
             return [];
         }
     }
@@ -535,7 +535,7 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
         catch {
             // A malformed/partial provider snapshot is not evidence of a stall.
             // Leave all fences untouched and let the next full pass retry.
-            finishDiagnostics("observation-error");
+            await finishDiagnostics("observation-error");
             return [];
         }
     }
@@ -550,7 +550,7 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
         let live;
         try {
             if (liveStatuses !== undefined && !liveStatuses.has(key)) {
-                finishDiagnostics("observation-error");
+                await finishDiagnostics("observation-error");
                 return [];
             }
             live = liveStatuses !== undefined
@@ -571,7 +571,7 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
             // Without a complete live snapshot, especially for downstream AgentRuns,
             // Leader classification would be unsafe. Treat the whole advisory pass
             // as unknown instead of escalating a false stall.
-            finishDiagnostics("observation-error");
+            await finishDiagnostics("observation-error");
             return [];
         }
         // A missing process is handled by the existing fenced liveness pass. This
@@ -669,7 +669,7 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
             // A new semantic progress point closes the previous episode first. It
             // may itself already be older than the window, in which case the same
             // pass records the next AgentRun+progressAt episode below.
-            store.recordRoleRunProgress({
+            await store.recordRoleRunProgress({
                 taskId: candidate.task.id,
                 roleName: candidate.role.name,
                 runId: candidate.run.id,
@@ -702,7 +702,7 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
         // diagnostic context, not duplicated as another Task-level alert.
         if (previous?.progressAt === progressAt)
             continue;
-        const persisted = store.recordRoleRunStall({
+        const persisted = await store.recordRoleRunStall({
             taskId: candidate.task.id,
             roleName: candidate.role.name,
             runId: candidate.run.id,
@@ -738,7 +738,7 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
         const previous = store.getRunProgressFacts(candidate.task.id, candidate.run.id)?.latestStall;
         if (previous !== undefined
             && Date.parse(progressAt) > Date.parse(previous.progressAt)) {
-            store.recordRoleRunProgress({
+            await store.recordRoleRunProgress({
                 taskId: candidate.task.id,
                 roleName: candidate.role.name,
                 runId: candidate.run.id,
@@ -748,7 +748,7 @@ export async function reconcileStalledRoleRuns(store, delivery, now, selection,
             });
         }
     }
-    finishDiagnostics("observed");
+    await finishDiagnostics("observed");
     return raised;
 }
 function isStallCandidate(run, now, windowMs, lastDiagnosticFinishedAt, latestProgressAt) {

package/dist/storage/persistenceWorker.js

@@ -33,6 +33,8 @@
 import { runRpcWorker } from "../core/boundedRpc.js";
 import { SqliteTaskStore } from "./sqliteStore.js";
 import { StorageRecordError } from "./taskStore.js";
+import { randomUUID } from "node:crypto";
+import { ControllerWorkObserver, compactWorkObservation } from "../core/controllerTelemetry.js";
 // -- method invocation -------------------------------------------------------
 function invokeMethod(target, method, args) {
     const fn = target[method];
@@ -41,6 +43,13 @@ function invokeMethod(target, method, args) {
     }
     return fn.apply(target, args);
 }
+const workerInstance = randomUUID();
+const work = new ControllerWorkObserver();
+function observation() {
+    return { instance: workerInstance, work: compactWorkObservation(work),
+        database: state.writer?.storageObservationMetrics() ?? null,
+        reads: state.observer?.compactReadObservationMetrics?.() ?? null };
+}
 /**
  * Sentinel returned by a handler when the durable outbox already records the
  * request's effect (§5.4). The host's `result` builder maps it to an
@@ -80,7 +89,10 @@ async function handleInit(request) {
         state.observer = {
             invoke(method, args) {
                 return invokeMethod(host, method, args);
-            }
+            },
+            ...(host.compactReadObservationMetrics === undefined ? {} : {
+                compactReadObservationMetrics: () => host.compactReadObservationMetrics()
+            })
         };
     }
 }
@@ -162,21 +174,31 @@ runRpcWorker({
     },
     init: (request) => handleInit(request),
     handle: async (request) => {
-        switch (request.kind) {
-            case "call":
-                return handleCall(request);
-            case "transaction":
-                return handleTransaction(request);
-            case "observer":
-                return handleObserver(request);
-            case "telemetry":
-                if (state.writer === undefined)
-                    throw new Error("Worker not initialized.");
-                return state.writer.flushTelemetry(request.entries, request.runCap);
-            case "init":
-            case "cancel":
-            case "shutdown":
-                throw new Error(`Unexpected request kind for handle: ${request.kind}`);
+        const finish = work.start(request.kind, "requestId" in request ? request.requestId : undefined);
+        try {
+            switch (request.kind) {
+                case "call":
+                    return await handleCall(request);
+                case "transaction":
+                    return await handleTransaction(request);
+                case "observer":
+                    return await handleObserver(request);
+                case "telemetry":
+                    if (state.writer === undefined)
+                        throw new Error("Worker not initialized.");
+                    return state.writer.flushTelemetry(request.entries, request.runCap);
+                case "init":
+                case "cancel":
+                case "shutdown":
+                    throw new Error(`Unexpected request kind for handle: ${request.kind}`);
+            }
+        }
+        catch (error) {
+            finish(true);
+            throw error;
+        }
+        finally {
+            finish();
         }
     },
     cancel: (requestId) => {
@@ -196,7 +218,7 @@ runRpcWorker({
     },
     ready: () => ({ kind: "ready" }),
     result: (requestId, value) => (value === ALREADY_APPLIED
-        ? { kind: "already-applied", requestId }
-        : { kind: "result", requestId, result: value }),
-    error: (requestId, error) => ({ kind: "error", requestId, error })
+        ? { kind: "already-applied", requestId, observation: observation() }
+        : { kind: "result", requestId, result: value, observation: observation() }),
+    error: (requestId, error) => ({ kind: "error", requestId, error, observation: observation() })
 });

package/dist/storage/sqliteSchema.js

@@ -5,6 +5,7 @@ import { migrateTaskMainWorkspaces } from "./upgrade/taskMainWorkspaceMigration.
 import { migrateProjectKnowledge } from "./upgrade/projectKnowledgeMigration.js";
 import { JOB_SCHEMA_SQL } from "./jobSchema.js";
 import { AGENT_JOB_SCHEMA_SQL } from "./agentJobSchema.js";
+import { TASK_READ_REVISION_SCHEMA_SQL } from "./taskReadRevisionSchema.js";
 import { SCHEDULE_SCHEMA_SQL } from "./scheduleSchema.js";
 import { GLOBAL_SESSION_TABLE_SQL, SESSION_HISTORY_UPGRADE_SQL } from "./sessionHistorySchema.js";
 import { migrateJobDefinitions } from "./upgrade/jobDefinitionMigration.js";
@@ -13,7 +14,7 @@ import { migrateScheduleDispatch } from "./upgrade/scheduleDispatchMigration.js"
 import { migrateProjectSyncClock } from "./upgrade/projectSyncClockMigration.js";
 import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION, STORAGE_FORMAT, isMinorStorageUpgrade, isStorageVersion, storageVersionParts } from "./storageVersions.js";
 export { BASELINE_SCHEMA_SQL };
-export const SQLITE_SCHEMA_TABLES = [...BASELINE_SCHEMA_TABLES, "job_definitions", "global_job_runs", "schedules", "agent_job_runs"];
+export const SQLITE_SCHEMA_TABLES = [...BASELINE_SCHEMA_TABLES, "job_definitions", "global_job_runs", "schedules", "agent_job_runs", "task_read_revisions"];
 export const TELEMETRY_KEEP_PER_RUN = 200;
 export const TELEMETRY_RUN_CAP = 50_000;
 export const BASELINE_SCHEMA_CHECKSUM = createHash("sha256").update(BASELINE_SCHEMA_SQL).digest("hex");
@@ -23,7 +24,9 @@ export const SCHEDULE_SCHEMA_CHECKSUM = createHash("sha256").update(SCHEDULE_SCH
 // Fresh Homes create the final layout directly; published baseline SQL stays immutable.
 const SESSION_SCHEMA_SQL = SCHEDULE_SCHEMA_SQL_COMPLETE.replace(/CREATE TABLE global_role_session_sets \([\s\S]*?\n\);/, GLOBAL_SESSION_TABLE_SQL);
 const SESSION_SCHEMA_CHECKSUM = createHash("sha256").update(SESSION_SCHEMA_SQL).digest("hex");
-export const CURRENT_SCHEMA_SQL = SESSION_SCHEMA_SQL + AGENT_JOB_SCHEMA_SQL;
+export const PRE_READ_REVISION_SCHEMA_SQL = SESSION_SCHEMA_SQL + AGENT_JOB_SCHEMA_SQL;
+const PRE_READ_REVISION_SCHEMA_CHECKSUM = createHash("sha256").update(PRE_READ_REVISION_SCHEMA_SQL).digest("hex");
+export const CURRENT_SCHEMA_SQL = PRE_READ_REVISION_SCHEMA_SQL + TASK_READ_REVISION_SCHEMA_SQL;
 export const CURRENT_SCHEMA_CHECKSUM = createHash("sha256").update(CURRENT_SCHEMA_SQL).digest("hex");
 export class SqliteSchemaError extends Error {
     code;
@@ -230,7 +233,7 @@ const MINOR_UPGRADES = Object.freeze([{
         name: "job-agent-execution",
         introducedIn: "next",
         sourceChecksum: SESSION_SCHEMA_CHECKSUM,
-        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        targetChecksum: PRE_READ_REVISION_SCHEMA_CHECKSUM,
         // Existing records and immutable artifacts remain byte-for-byte unchanged.
         // Declares Agent definitions/Runs and optional Job ownership of a non-Task Role.
         sql: AGENT_JOB_SCHEMA_SQL
@@ -239,10 +242,40 @@ const MINOR_UPGRADES = Object.freeze([{
         toVersion: "1.21",
         name: "project-sync-clock",
         introducedIn: "next",
-        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
-        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        sourceChecksum: PRE_READ_REVISION_SCHEMA_CHECKSUM,
+        targetChecksum: PRE_READ_REVISION_SCHEMA_CHECKSUM,
         sql: "",
         dataMigration: "project-sync-clock"
+    }, {
+        fromVersion: "1.21",
+        toVersion: "1.22",
+        name: "role-profile-availability",
+        introducedIn: "next",
+        sourceChecksum: PRE_READ_REVISION_SCHEMA_CHECKSUM,
+        targetChecksum: PRE_READ_REVISION_SCHEMA_CHECKSUM,
+        // Optional enabled flag; absence means enabled. Preserve all historical
+        // Role/Profile bytes, frozen contexts and Session snapshots.
+        sql: ""
+    }, {
+        fromVersion: "1.22",
+        toVersion: "1.23",
+        name: "global-shell-scripts",
+        introducedIn: "next",
+        sourceChecksum: PRE_READ_REVISION_SCHEMA_CHECKSUM,
+        targetChecksum: PRE_READ_REVISION_SCHEMA_CHECKSUM,
+        // Additive global Shell definitions with revisioned script text and exact
+        // Run snapshots. Historical definitions/Runs stay byte-for-byte unchanged.
+        sql: ""
+    }, {
+        fromVersion: "1.23",
+        toVersion: "1.24",
+        name: "task-read-revisions",
+        introducedIn: "next",
+        sourceChecksum: PRE_READ_REVISION_SCHEMA_CHECKSUM,
+        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        // No payload rewriting or historical revision invention. A newly opened
+        // reader starts empty; zero is the initial token until the first mutation.
+        sql: TASK_READ_REVISION_SCHEMA_SQL
     }]);
 export function storageMinorUpgradePlan(from) {
     if (from === CURRENT_STORAGE_VERSION)
@@ -272,10 +305,11 @@ export function validateSqliteSchemaObjects(db, version = CURRENT_STORAGE_VERSIO
     const checksum = version === CURRENT_STORAGE_VERSION
         ? CURRENT_SCHEMA_CHECKSUM : storageMinorUpgradePlan(version)?.[0]?.sourceChecksum;
     const sql = checksum === CURRENT_SCHEMA_CHECKSUM ? CURRENT_SCHEMA_SQL
-        : checksum === SESSION_SCHEMA_CHECKSUM ? SESSION_SCHEMA_SQL
-            : checksum === SCHEDULE_SCHEMA_CHECKSUM ? SCHEDULE_SCHEMA_SQL_COMPLETE
-                : checksum === JOB_SCHEMA_CHECKSUM ? BASELINE_SCHEMA_SQL + JOB_SCHEMA_SQL
-                    : checksum === BASELINE_SCHEMA_CHECKSUM ? BASELINE_SCHEMA_SQL : undefined;
+        : checksum === PRE_READ_REVISION_SCHEMA_CHECKSUM ? PRE_READ_REVISION_SCHEMA_SQL
+            : checksum === SESSION_SCHEMA_CHECKSUM ? SESSION_SCHEMA_SQL
+                : checksum === SCHEDULE_SCHEMA_CHECKSUM ? SCHEDULE_SCHEMA_SQL_COMPLETE
+                    : checksum === JOB_SCHEMA_CHECKSUM ? BASELINE_SCHEMA_SQL + JOB_SCHEMA_SQL
+                        : checksum === BASELINE_SCHEMA_CHECKSUM ? BASELINE_SCHEMA_SQL : undefined;
     if (sql === undefined || checksum === undefined)
         throw new SqliteSchemaError(`unsupported schema definition for storage ${version}.`);
     let expectedObjects = schemaObjectsByChecksum.get(checksum);

package/dist/storage/sqliteStore.js

@@ -34,6 +34,7 @@ import { validateAgentJobRun, assertAgentJobRunTransition } from "../job/agentJo
  * in-process contract or deferred validation phase.
  */
 import Database from "../sqlite/driver.js";
+import { ControllerWorkObserver, compactWorkObservation } from "../core/controllerTelemetry.js";
 import { findNativeSessionSets } from "./nativeSessionLookup.js";
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
@@ -141,10 +142,37 @@ function assertRunAdmission(task, run) {
     }
 }
 export class SqliteTaskStore {
+    #payloadReads = new ControllerWorkObserver();
+    #transactions = {
+        "write-lock": new ControllerWorkObserver(),
+        "write-body": new ControllerWorkObserver(),
+        "transaction-commit": new ControllerWorkObserver()
+    };
+    storageObservationMetrics() {
+        return {
+            lock: compactWorkObservation(this.#transactions["write-lock"]),
+            body: compactWorkObservation(this.#transactions["write-body"]),
+            commit: compactWorkObservation(this.#transactions["transaction-commit"]),
+            payloadReads: compactWorkObservation(this.#payloadReads)
+        };
+    }
+    #observeTransaction(phase, action) {
+        const finish = this.#transactions[phase].start(phase);
+        try {
+            const result = action();
+            finish();
+            return result;
+        }
+        catch (error) {
+            finish(true);
+            throw error;
+        }
+    }
     #db;
     #rootDir;
     #openedSchemaHead;
     #inTransaction = false;
+    #writeTransaction = false;
     #dirty = false;
     constructor(rootDir, _options = {}) {
         this.#rootDir = rootDir;
@@ -261,6 +289,13 @@ export class SqliteTaskStore {
     listEventsByType(taskId, types) {
         return this.#sortById(this.#listPayload("events", "task_id = ? AND type IN (SELECT value FROM json_each(?))", [taskId, JSON.stringify(types)]), event => event.id);
     }
+    hasRuntimeObservation(taskId, identity) {
+        const byEvent = "eventId" in identity;
+        return this.#db.prepare(`SELECT 1 FROM events WHERE task_id = ?
+      AND type = 'runtime.observation'
+      AND json_extract(payload, '${byEvent ? "$.payload.eventId" : "$.payload.semanticKey"}') = ?
+      LIMIT 1`).get(taskId, byEvent ? identity.eventId : identity.semanticKey) !== undefined;
+    }
     readTaskUsageFacts(taskId) {
         // Bounded source selection, not a scan/deserialization of Task history.
         // Strip result bodies before they cross the SQLite boundary.
@@ -348,13 +383,15 @@ export class SqliteTaskStore {
         writeTelemetryBatch(this.#db, entries, runCap);
     }
     #begin() {
-        this.#db.exec("BEGIN IMMEDIATE");
+        this.#observeTransaction("write-lock", () => this.#db.exec("BEGIN IMMEDIATE"));
         this.#inTransaction = true;
+        this.#writeTransaction = true;
         this.#dirty = false;
     }
     #commit() {
-        this.#db.exec("COMMIT");
+        this.#observeTransaction("transaction-commit", () => this.#db.exec("COMMIT"));
         this.#inTransaction = false;
+        this.#writeTransaction = false;
         this.#dirty = false;
     }
     #rollback() {
@@ -363,6 +400,7 @@ export class SqliteTaskStore {
         }
         catch { /* already closed */ }
         this.#inTransaction = false;
+        this.#writeTransaction = false;
         this.#dirty = false;
     }
     /** Verify the SQLite schema head at the single write boundary. */
@@ -393,7 +431,7 @@ export class SqliteTaskStore {
         this.#begin();
         try {
             this.#prepareWrite();
-            const result = fn();
+            const result = this.#observeTransaction("write-body", fn);
             this.#bumpRevision();
             this.#commit();
             return result;
@@ -413,7 +451,7 @@ export class SqliteTaskStore {
             // This prevents a long-lived Store from executing SQL after the database
             // schema head has changed underneath it.
             this.#prepareWrite();
-            const result = run(this);
+            const result = this.#observeTransaction("write-body", () => run(this));
             if (this.#dirty) {
                 if (options?.requestId !== undefined) {
                     this.#insertOutbox(options.requestId, options.outboxCommand ?? null);
@@ -438,7 +476,7 @@ export class SqliteTaskStore {
         this.#begin();
         try {
             this.#prepareWrite();
-            const result = await execute(this);
+            const result = await this.#transactions["write-body"].observe("write-body", undefined, () => execute(this));
             if (this.#dirty)
                 this.#bumpRevision();
             this.#commit();
@@ -472,7 +510,7 @@ export class SqliteTaskStore {
             if (current !== expectedRevision) {
                 throw new StorageConflictError(`Storage revision conflict (expected ${expectedRevision}, found ${current}).`, current);
             }
-            const result = execute(this);
+            const result = this.#observeTransaction("write-body", () => execute(this));
             if (this.#dirty) {
                 this.#prepareWrite();
                 if (options?.requestId !== undefined) {
@@ -496,6 +534,13 @@ export class SqliteTaskStore {
         return row.revision;
     }
     getStateRevision() { return this.getRevision(); }
+    getTaskReadRevision(taskId) {
+        // Uncommitted writes have no durable cache identity, even if rolled back.
+        if (this.#writeTransaction)
+            return Number.NaN;
+        return this.#db.prepare("SELECT revision FROM task_read_revisions WHERE task_id = ?")
+            .get(taskId)?.revision ?? 0;
+    }
     /**
      * Run an ordered command batch inside one `BEGIN IMMEDIATE … COMMIT`, yielding
      * to the event loop between commands so a cancellation signal can interrupt
@@ -656,8 +701,19 @@ export class SqliteTaskStore {
         return row === undefined ? null : this.#validateTaskPayload(table, row.payload);
     }
     #listPayload(table, where, params) {
-        const rows = this.#db.prepare(`SELECT payload FROM ${table} WHERE ${where}`).all(...params);
-        return rows.map((row) => this.#validateTaskPayload(table, row.payload));
+        // Table names are fixed internal callers; no SQL, parameters or payload
+        // text enters diagnostics. Include parsing/validation, not only SQLite IO.
+        const finish = this.#payloadReads.start(`list-${table}`);
+        try {
+            const rows = this.#db.prepare(`SELECT payload FROM ${table} WHERE ${where}`).all(...params);
+            const values = rows.map((row) => this.#validateTaskPayload(table, row.payload));
+            finish();
+            return values;
+        }
+        catch (error) {
+            finish(true);
+            throw error;
+        }
     }
     #validateTaskPayload(table, payload) {
         const record = this.#parse(payload);
@@ -1019,6 +1075,17 @@ export class SqliteTaskStore {
         OR json_extract(payload, '$.interruptThen') IS NOT NULL)`);
         if (query.interruptThen)
             where.push("json_extract(payload, '$.interruptThen') IS NOT NULL");
+        if (query.reservedThen !== undefined) {
+            where.push(`json_extract(payload, '$.delivery') IS NULL
+        AND json_extract(payload, '$.notDelivered') IS NULL
+        AND json_extract(payload, '$.interruptThen.targetNativeSessionId') = @thenSession
+        AND json_extract(payload, '$.interruptThen.targetAgentId') = @thenAgent
+        AND json_extract(payload, '$.interruptThen.targetAuthorityEpoch') = @thenEpoch
+        AND json_extract(payload, '$.interruptThen.targetAuthorityHolderId') = @thenHolder`);
+            Object.assign(params, { thenSession: query.reservedThen.nativeSessionId,
+                thenAgent: query.reservedThen.agentId, thenEpoch: query.reservedThen.authorityEpoch,
+                thenHolder: query.reservedThen.holderId });
+        }
         if (query.operatorNotice)
             where.push("json_extract(payload, '$.inputControl.requestId') LIKE 'operator-notice:%'");
         if (query.afterSequence !== undefined) {
@@ -1335,6 +1402,17 @@ export class SqliteTaskStore {
     listJobDefinitions(scope) {
         return this.#listPayload("job_definitions", "scope_key=?", [jobScopeKey(scope)]);
     }
+    listJobScopeSummaries() {
+        const rows = this.#db.prepare(`SELECT scope_key, SUM(definitions) AS definitions, SUM(schedules) AS schedules,
+        SUM(enabled) AS enabled FROM (
+          SELECT scope_key, 1 AS definitions, 0 AS schedules, 0 AS enabled FROM job_definitions
+          UNION ALL SELECT scope_key, 0, 1, CASE WHEN state='enabled' THEN 1 ELSE 0 END FROM schedules)
+      GROUP BY scope_key`).all();
+        return rows.map(row => ({
+            scope: row.scope_key === "global" ? { kind: "global" } : { kind: "task", taskId: row.scope_key },
+            definitions: Number(row.definitions), schedules: Number(row.schedules), enabledSchedules: Number(row.enabled)
+        }));
+    }
     saveGlobalJobRun(run) {
         validateDurableJob(run);
         if ("taskId" in run || run.scope !== "global")

package/dist/storage/storageVersions.js

@@ -1,4 +1,4 @@
-export const CURRENT_STORAGE_VERSION = "1.21";
+export const CURRENT_STORAGE_VERSION = "1.24";
 export const MIN_SUPPORTED_STORAGE_VERSION = "1.0";
 export const STORAGE_FORMAT = "yui-home";
 export function isStorageVersion(value) {

package/dist/storage/storeRpc.js

@@ -20,7 +20,8 @@
  * SQLite is the only product Store. `YUI_STORE_WORKER` selects the observer
  * execution boundary; it does not select another authority.
  */
-import { BoundedRpcClient, nextRequestId } from "../core/boundedRpc.js";
+import { BoundedRpcClient, deserializeError as deserializeRpcError, nextRequestId } from "../core/boundedRpc.js";
+import { ControllerWorkObserver } from "../core/controllerTelemetry.js";
 import { StorageCancelledError, StorageConflictError, StorageRecordError } from "./taskStore.js";
 // -- Read-only classification ------------------------------------------------
 /**
@@ -37,6 +38,8 @@ const READ_ONLY_STORE_METHODS = new Set([
     "getHomeIdentity",
     "getReviewConfig",
     "getRevision",
+    "getStateRevision",
+    "getTaskReadRevision",
     "listConfiguredAgents",
     "getConfiguredAgent",
     "listProjects",
@@ -57,6 +60,7 @@ const READ_ONLY_STORE_METHODS = new Set([
     "queryTaskSearch",
     "latestEventSequence",
     "listEventsByType",
+    "hasRuntimeObservation",
     "readTaskUsageFacts",
     "listTaskRunWorkspaceBases",
     "contextInputReferences",
@@ -72,6 +76,7 @@ const READ_ONLY_STORE_METHODS = new Set([
     "listActiveDurableJobs",
     "getJobDefinition",
     "listJobDefinitions",
+    "listJobScopeSummaries",
     "getGlobalJobRun",
     "getAgentJobRun",
     "listAgentJobRuns",
@@ -137,12 +142,10 @@ function deserializeError(serialized) {
     if (name === "StorageCancelledError" || name === "AbortError") {
         return new StorageCancelledError(message);
     }
-    const error = new Error(message);
-    error.name = name;
-    return error;
+    return deserializeRpcError(serialized);
 }
 // -- Storage protocol adapter -------------------------------------------------
-function storageProtocol(home, options) {
+function storageProtocol(home, options, observe) {
     return {
         initRequest: () => ({
             kind: "init",
@@ -162,6 +165,8 @@ function storageProtocol(home, options) {
             return response.requestId;
         },
         settle: (response, settlement) => {
+            if (response.observation !== undefined)
+                observe(response.observation);
             if (response.kind === "result") {
                 settlement.resolve(response.result);
                 return;
@@ -188,8 +193,17 @@ function storageProtocol(home, options) {
  */
 export class AsyncTaskStoreClient {
     #rpc;
+    #waits = new ControllerWorkObserver();
+    #worker = null;
+    /** Cached observations only: status never waits on a busy persistence worker. */
+    observationMetrics() {
+        return { roundTrips: this.#waits.snapshot(), worker: this.#worker,
+            inFlight: this.inFlight, queueDepth: this.queueDepth };
+    }
     constructor(home, options = {}) {
-        this.#rpc = new BoundedRpcClient(storageProtocol(home, options), {
+        this.#rpc = new BoundedRpcClient(storageProtocol(home, options, observation => {
+            this.#worker = observation;
+        }), {
             maxInFlight: options.maxInFlight,
             maxQueue: options.maxQueue,
             workerScript: options.workerScript ?? new URL("./persistenceWorker.js", import.meta.url)
@@ -198,13 +212,13 @@ export class AsyncTaskStoreClient {
     /** Invoke a TaskStore method over the RPC (used by the Proxy). */
     callStore(method, args, options) {
         const requestId = options?.requestId ?? nextRequestId();
-        return this.#rpc.send(requestId, {
+        return this.#waits.observe("store-call", requestId, () => this.#rpc.send(requestId, {
             kind: "call",
             requestId,
             method,
             args,
             readOnly: isReadOnlyMethod(method)
-        }, { signal: options?.signal });
+        }, { signal: options?.signal }));
     }
     /** Run a command batch atomically in the worker (§3.2). */
     transactionAsync(commands, options) {
@@ -213,12 +227,12 @@ export class AsyncTaskStoreClient {
             op: command.op,
             args: command.args
         }));
-        return this.#rpc.send(requestId, {
+        return this.#waits.observe("store-transaction", requestId, () => this.#rpc.send(requestId, {
             kind: "transaction",
             requestId,
             commands: wireCommands,
             ...(options?.expectedRevision === undefined ? {} : { expectedRevision: options.expectedRevision })
-        }, { signal: options?.signal });
+        }, { signal: options?.signal }));
     }
     /**
      * Invoke a controller observer method hosted by the worker (the
@@ -227,7 +241,7 @@ export class AsyncTaskStoreClient {
      */
     invokeObserver(method, args, options) {
         const requestId = options?.requestId ?? nextRequestId();
-        return this.#rpc.send(requestId, { kind: "observer", requestId, method, args }, { signal: options?.signal });
+        return this.#waits.observe("store-observer", requestId, () => this.#rpc.send(requestId, { kind: "observer", requestId, method, args }, { signal: options?.signal }));
     }
     /** Close the worker and release its connections. */
     close() {

package/dist/storage/taskReadRevisionSchema.js

@@ -0,0 +1,39 @@
+/** Storage 1.24 definition: immutable once published. These are cache tokens,
+ * not a second Task state or a CAS/authorization source. Triggers cover every
+ * source family, including direct SQL, deletions and rolled-back transactions.
+ */
+export const TASK_READ_REVISION_SOURCES = [
+    "events", "turns", "work_items", "review_rounds", "change_sets",
+    "integration_attempts", "input_requests", "durable_jobs", "messages"
+];
+export const TASK_READ_REVISION_SCHEMA_SQL = `
+CREATE TABLE task_read_revisions (
+  task_id TEXT PRIMARY KEY,
+  revision INTEGER NOT NULL
+);
+CREATE INDEX idx_runtime_observation_semantic
+  ON events(task_id, json_extract(payload, '$.payload.semanticKey'))
+  WHERE type = 'runtime.observation';
+CREATE INDEX idx_runtime_observation_event
+  ON events(task_id, json_extract(payload, '$.payload.eventId'))
+  WHERE type = 'runtime.observation';
+${TASK_READ_REVISION_SOURCES.map(table => `
+CREATE TRIGGER ${table}_read_ai AFTER INSERT ON ${table}
+BEGIN
+  INSERT INTO task_read_revisions VALUES (NEW.task_id, 1)
+  ON CONFLICT(task_id) DO UPDATE SET revision = revision + 1;
+END;
+CREATE TRIGGER ${table}_read_ad AFTER DELETE ON ${table}
+BEGIN
+  INSERT INTO task_read_revisions VALUES (OLD.task_id, 1)
+  ON CONFLICT(task_id) DO UPDATE SET revision = revision + 1;
+END;
+CREATE TRIGGER ${table}_read_au AFTER UPDATE ON ${table}
+BEGIN
+  INSERT INTO task_read_revisions VALUES (NEW.task_id, 1)
+  ON CONFLICT(task_id) DO UPDATE SET revision = revision + 1;
+  INSERT INTO task_read_revisions
+    SELECT OLD.task_id, 1 WHERE OLD.task_id != NEW.task_id
+  ON CONFLICT(task_id) DO UPDATE SET revision = revision + 1;
+END;
+`).join("")}`;