@zq-silk/yui 2.17.0 → 2.19.0

package/dist/controller/workerSchedulerStore.js

@@ -0,0 +1,24 @@
+/**
+ * Keep maintenance read/check/write closures together on the persistence
+ * worker. These operations recheck their exact durable condition in one
+ * transaction and are idempotent under the worker's existing replay contract.
+ * Do not add admission/claim operations here: their result and unknown-effect
+ * contracts need a separate audit before moving across this boundary.
+ */
+const WORKER_MAINTENANCE = new Set([
+    "resolveExpiredInputRecommendations",
+    "recordRoleRunProgress",
+    "recordRoleRunDiagnostic",
+    "recordRoleRunStall"
+]);
+export function workerSchedulerStore(store, client) {
+    return new Proxy(store, {
+        get(target, property) {
+            if (WORKER_MAINTENANCE.has(property)) {
+                return (...args) => client.invokeObserver(String(property), args);
+            }
+            const value = Reflect.get(target, property);
+            return typeof value === "function" ? value.bind(target) : value;
+        }
+    });
+}

package/dist/core/boundedRpc.js

@@ -48,6 +48,10 @@ export function serializeError(error) {
 export function deserializeError(serialized) {
     const error = new Error(serialized.message);
     error.name = serialized.name;
+    if (serialized.code !== undefined)
+        Object.assign(error, { code: serialized.code });
+    if (serialized.stack !== undefined)
+        error.stack = serialized.stack;
     return error;
 }
 // -- Bounded slot pool (backpressure) ----------------------------------------

package/dist/core/controllerServer.js

@@ -311,7 +311,7 @@ async function routeRequest(socket, line, token, dispatcher, stop, status, telem
     // observation completes when the response is handed to the socket, so a
     // later status snapshot sees prior built-in completions and the dispatcher
     // service-time metric stays a distinct observation.
-    const observation = telemetry.commandObserver.start();
+    const observation = telemetry.commandObserver.start(request.method, request.id);
     const send = (response, onFlushed) => {
         observation.complete(isBuiltinControllerMethod(request.method) ? "builtin" : "dispatched", response.ok ? "success" : "failure");
         sendResponse(socket, response, onFlushed);

package/dist/core/controllerTelemetry.js

@@ -1,13 +1,69 @@
-/**
- * Pure-memory, fixed-space command observation for the Controller socket.
- *
- * The core server owns route/built-in command observation: every authenticated
- * request is counted once at the routing layer, and a bounded unrefed scheduler
- * samples event-loop delay so an already-written request's pre-dispatch wait is
- * observable even when the loop is saturated by scheduler projections. The
- * FileTaskController composes these snapshots into its runtime status metric;
- * nothing here is persisted and every snapshot is O(1).
- */
+import { createHash } from "node:crypto";
+/** Fixed-size retained diagnostics; live bookkeeping follows in-flight work.
+ * Not a log or scheduling authority. No params,
+ * prompts, paths, failure text or credentials are retained. Target/request
+ * hashes correlate an observation without publishing arbitrary input. */
+export class ControllerWorkObserver {
+    clock;
+    #active = new Map();
+    #recent = [];
+    #completed = 0;
+    #maximumMs = 0;
+    #slowest = null;
+    constructor(clock = monotonicMilliseconds) {
+        this.clock = clock;
+    }
+    start(phase, target) {
+        const token = {};
+        const entry = { phase, target: target === undefined ? null
+                : createHash("sha256").update(target).digest("hex").slice(0, 16), startedAt: this.clock() };
+        this.#active.set(token, entry);
+        return (failed = false) => {
+            if (!this.#active.delete(token))
+                return;
+            const elapsedMs = Math.max(0, this.clock() - entry.startedAt);
+            this.#completed++;
+            this.#maximumMs = Math.max(this.#maximumMs, elapsedMs);
+            const completed = { phase, target: entry.target, startedAtMs: entry.startedAt, elapsedMs, failed };
+            if (this.#slowest === null || elapsedMs > this.#slowest.elapsedMs)
+                this.#slowest = completed;
+            this.#recent.push(completed);
+            if (this.#recent.length > 16)
+                this.#recent.shift();
+        };
+    }
+    async observe(phase, target, action) {
+        const finish = this.start(phase, target);
+        try {
+            const value = await action();
+            finish();
+            return value;
+        }
+        catch (error) {
+            finish(true);
+            throw error;
+        }
+    }
+    snapshot() {
+        const active = [];
+        for (const entry of this.#active.values()) {
+            active.push({ phase: entry.phase, target: entry.target, startedAtMs: entry.startedAt,
+                ageMs: Math.max(0, this.clock() - entry.startedAt) });
+            if (active.length === 16)
+                break;
+        }
+        return {
+            completed: this.#completed, maximumMs: this.#maximumMs, inFlight: this.#active.size,
+            active, slowest: this.#slowest,
+            recent: [...this.#recent]
+        };
+    }
+}
+/** Small worker-response observation; no historical arrays on the RPC wire. */
+export function compactWorkObservation(observer) {
+    const { completed, maximumMs, slowest, recent } = observer.snapshot();
+    return { completed, maximumMs, slowest, latest: recent.at(-1) ?? null };
+}
 const CONTROLLER_DELAY_BUCKETS_MS = [10, 50, 100, 250, 500, 1_000, 3_000];
 const DEFAULT_EVENT_LOOP_DELAY_INTERVAL_MS = 50;
 const BUILTIN_METHODS = new Set([
@@ -19,6 +75,12 @@ const BUILTIN_METHODS = new Set([
     "controller.rollback-handover",
     "controller.handover-state"
 ]);
+const OBSERVED_METHODS = new Set([...BUILTIN_METHODS,
+    "scheduler.signal", "scheduler.scan", "scheduler.configure",
+    "runtime.ensure-role-session", "runtime.stop-role-session",
+    "capability.search", "capability.describe", "capability.call",
+    "schedule.control", "job.definition", "job.start", "job.get", "job.cancel", "job.acknowledge"
+]);
 export function isBuiltinControllerMethod(method) {
     return BUILTIN_METHODS.has(method);
 }
@@ -47,19 +109,23 @@ export class ControllerCommandObserver {
     #completed = 0;
     #failed = 0;
     #inFlight = 0;
-    /** Monotonic arrival timestamps of in-flight observations (FIFO). */
-    #inFlightStarted = [];
+    /** Insertion order preserves arrival order; completion removes its own token. */
+    #inFlightStarted = new Map();
     #builtinCompleted = 0;
     #builtinFailed = 0;
     #dispatchedCompleted = 0;
     #dispatchedFailed = 0;
+    #observations;
     constructor(clock = monotonicMilliseconds) {
         this.#clock = clock;
+        this.#observations = new ControllerWorkObserver(clock);
     }
-    start() {
+    start(method = "unknown", requestId) {
         this.#received += 1;
         this.#inFlight += 1;
-        this.#inFlightStarted.push(this.#clock());
+        const token = {};
+        this.#inFlightStarted.set(token, this.#clock());
+        const finish = this.#observations.start(OBSERVED_METHODS.has(method) ? method : "other", requestId);
         let completed = false;
         return {
             complete: (kind, outcome) => {
@@ -67,7 +133,8 @@ export class ControllerCommandObserver {
                     return;
                 completed = true;
                 this.#inFlight = Math.max(0, this.#inFlight - 1);
-                this.#inFlightStarted.shift();
+                this.#inFlightStarted.delete(token);
+                finish(outcome === "failure");
                 this.#completed += 1;
                 if (outcome === "failure")
                     this.#failed += 1;
@@ -87,9 +154,9 @@ export class ControllerCommandObserver {
         };
     }
     snapshot() {
-        const oldest = this.#inFlightStarted.length === 0
+        const oldest = this.#inFlightStarted.size === 0
             ? null
-            : Math.max(0, this.#clock() - this.#inFlightStarted[0]);
+            : Math.max(0, this.#clock() - this.#inFlightStarted.values().next().value);
         return {
             received: this.#received,
             completed: this.#completed,
@@ -103,7 +170,8 @@ export class ControllerCommandObserver {
             dispatched: {
                 completed: this.#dispatchedCompleted,
                 failed: this.#dispatchedFailed
-            }
+            },
+            observations: this.#observations.snapshot()
         };
     }
 }
@@ -122,6 +190,7 @@ export class ControllerEventLoopDelay {
     #expectedAt = 0;
     #samples = 0;
     #maximumLagMs = 0;
+    #maximumObservedAtMs = null;
     #buckets = new Map(CONTROLLER_DELAY_BUCKETS_MS.map((threshold) => [threshold, 0]));
     #stopped = false;
     constructor(clock = monotonicMilliseconds, scheduler = productionTelemetryScheduler, intervalMs = DEFAULT_EVENT_LOOP_DELAY_INTERVAL_MS) {
@@ -142,7 +211,10 @@ export class ControllerEventLoopDelay {
         this.#expectedAt = this.#clock() + this.#intervalMs;
         this.#samples += 1;
         const bounded = Math.ceil(lag);
-        this.#maximumLagMs = Math.max(this.#maximumLagMs, bounded);
+        if (this.#maximumObservedAtMs === null || bounded > this.#maximumLagMs) {
+            this.#maximumLagMs = bounded;
+            this.#maximumObservedAtMs = this.#clock();
+        }
         for (const threshold of CONTROLLER_DELAY_BUCKETS_MS) {
             if (bounded <= threshold) {
                 this.#buckets.set(threshold, (this.#buckets.get(threshold) ?? 0) + 1);
@@ -158,6 +230,7 @@ export class ControllerEventLoopDelay {
         return {
             samples: this.#samples,
             maximumLagMs: this.#maximumLagMs,
+            maximumObservedAtMs: this.#maximumObservedAtMs,
             lagBuckets: Object.fromEntries(CONTROLLER_DELAY_BUCKETS_MS.map((threshold) => [
                 `le${threshold}ms`,
                 this.#buckets.get(threshold) ?? 0

package/dist/job/globalShell.js

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { requireKnownFields } from "../domain/validation.js";
+import { validateJobExecutionConfiguration } from "./durableJob.js";
+export function validateJobScriptFiles(files) {
+    if (!Array.isArray(files) || files.length > 64)
+        throw new Error("Job supports at most 64 script files.");
+    const paths = new Set();
+    let bytes = 0;
+    for (const file of files) {
+        requireKnownFields(file, ["path", "content"], "Job script file");
+        if (typeof file.path !== "string" || file.path.length > 240
+            || !/^[a-zA-Z0-9_-][a-zA-Z0-9._/-]*$/u.test(file.path)
+            || file.path.split("/").some((part) => !part || part === "." || part === "..")) {
+            throw new Error("Script paths must be safe relative paths, for example scripts/check.sh.");
+        }
+        if (paths.has(file.path) || [...paths].some(path => path.startsWith(file.path + "/") || file.path.startsWith(path + "/"))) {
+            throw new Error("Script paths must be unique and cannot overlap directories.");
+        }
+        if (typeof file.content !== "string" || file.content.includes("\0"))
+            throw new Error("Scripts must be UTF-8 text without NUL.");
+        bytes += Buffer.byteLength(file.content);
+        if (bytes > 512 * 1024)
+            throw new Error("Job scripts exceed 512 KiB.");
+        paths.add(file.path);
+    }
+}
+export function prepareGlobalShell(configuration, workspace) {
+    requireKnownFields(configuration, ["kind", "env", "steps", "files"], "Global Shell Job");
+    if (configuration.kind !== "shell")
+        throw new Error("Not a Shell Job.");
+    validateJobScriptFiles(configuration.files);
+    // No repository applies. This hash identifies executable configuration,
+    // never a Project commit or an Integration candidate.
+    const head = createHash("sha1").update(JSON.stringify(configuration)).digest("hex");
+    const spec = { workspace, env: configuration.env, steps: configuration.steps, head };
+    validateJobExecutionConfiguration(spec);
+    return spec;
+}
+/** A fresh per-Run directory; never overwrite another run's files or follow
+ * a pre-existing workspace. The runner's exclusive ready receipt fences replay. */
+export function materializeJobScripts(workspace, files) {
+    validateJobScriptFiles(files);
+    mkdirSync(workspace, { mode: 0o700 });
+    for (const file of files) {
+        const path = join(workspace, file.path);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, file.content, { flag: "wx", mode: 0o700 });
+    }
+}

package/dist/job/jobBusinessResult.js

@@ -62,9 +62,10 @@ export function jobRunSnapshot(run) {
         ...runReference(run), definitionId: run.definitionId, definitionRevision: run.definitionRevision,
         owner: "owner" in run ? run.owner : null,
         trigger: run.trigger, retryOf: run.retryOf ?? null,
-        executor: run.delegation ? { kind: "task", delegation: run.delegation } : "taskId" in run ? { kind: "shell" } : {
-            kind: "builtin", action: run.action, input: run.actionInput
-        },
+        executor: run.delegation ? { kind: "task", delegation: run.delegation } : "taskId" in run ? { kind: "shell" }
+            : run.action === "shell.exec" ? { kind: "shell", configuration: run.actionInput } : {
+                kind: "builtin", action: run.action, input: run.actionInput
+            },
         target: run.delegation ? { taskId: run.delegation.taskId, workItemId: run.delegation.workItemId ?? null }
             : { projectId: run.projectId ?? null, workspace: run.workspace, head: run.head },
         execution: run.delegation ? null : { env: run.env, steps: run.steps, implementation: run.operation.implementation }

package/dist/job/jobDefinition.js

@@ -2,6 +2,7 @@ import { requireIdentity, requireKnownFields, requirePositiveInteger, requireTex
 import { validateJobExecutionConfiguration, validateDurableJobOwner } from "./durableJob.js";
 import { validateAgentJobConfiguration } from "./agentJob.js";
 import { validateTaskJobConfiguration } from "./taskDelegation.js";
+import { prepareGlobalShell } from "./globalShell.js";
 export function jobScopeKey(scope) {
     if (scope.kind === "global")
         return "global";
@@ -44,6 +45,10 @@ export function validateJobDefinition(job) {
         validateTaskJobConfiguration(config);
     }
     else if (job.scope.kind === "global") {
+        if (config.kind === "shell") {
+            prepareGlobalShell(config, "/job-validation");
+            return job;
+        }
         if (config.kind !== "builtin")
             throw new Error("Global Jobs require a controlled builtin action.");
         requireKnownFields(config, ["kind", "action", "projectId", "input"], "Builtin Job");
@@ -54,7 +59,7 @@ export function validateJobDefinition(job) {
             throw new Error("Builtin Job input is required.");
     }
     else {
-        if (config.kind !== "shell")
+        if (config.kind !== "shell" || !("owner" in config))
             throw new Error("Task Jobs require a managed shell configuration.");
         requireKnownFields(config, ["kind", "owner", "projectId", "head", "workspace", "env", "steps"], "Task Job");
         requireIdentity(config.projectId, "Job Project id");

package/dist/job/jobRunner.js

@@ -13,6 +13,7 @@ import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { jobStepDirectory } from "./stepDirectory.js";
 import { prepareHttpPreview, isHttpPreview } from "./httpPreview.js";
+import { materializeJobScripts, validateJobScriptFiles } from "./globalShell.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { currentProcessStartIdentity } from "../core/fileLockOwner.js";
 const DEFAULT_STEP_TIMEOUT_MS = 30 * 60_000;
@@ -112,6 +113,8 @@ export async function runDurableJobRunner(specPath) {
     let failedStep;
     let preview;
     try {
+        if (spec.files !== undefined)
+            materializeJobScripts(spec.workspace, spec.files);
         for (let index = 0; index < spec.steps.length; index += 1) {
             if (cancelled || existsSync(cancelPath)) {
                 cancelled = true;
@@ -278,6 +281,12 @@ function readSpec(specPath) {
     if (typeof spec.artifactDir !== "string" || !spec.artifactDir.startsWith("/")) {
         throw new Error("DurableJob spec artifactDir must be an absolute path.");
     }
+    if (spec.files !== undefined) {
+        if (spec.scope !== "global" || spec.workspace !== join(spec.artifactDir, "workspace")) {
+            throw new Error("Job script snapshots require their own global Run workspace.");
+        }
+        validateJobScriptFiles(spec.files);
+    }
     if (typeof spec.head !== "string" || spec.head.length === 0) {
         throw new Error("DurableJob spec is missing head.");
     }

package/dist/job/scheduleService.js

@@ -4,6 +4,8 @@ import { requireProjectSyncTarget } from "./projectSync.js";
 /** Internal compiled registration, not a caller identity accepted by RPC. */
 const actions = new Set(["system.noop", "project.refresh"]);
 export function requireServiceTarget(job) {
+    if (job.scope.kind === "global" && job.configuration.kind === "shell")
+        return;
     if (job.scope.kind !== "global" || job.configuration.kind !== "builtin"
         || !actions.has(job.configuration.action))
         throw new Error("Schedule service is not registered for this scope/action.");

package/dist/message/globalInboxRecovery.js

@@ -4,28 +4,39 @@ import { hasRuntimeCleanupObligation, runtimeLifecycleTarget } from "../runtime/
 import { currentProviderConversation } from "../runtime/providerRuntimeIdentity.js";
 import { INBOX_CHECK_PREFIX } from "./inboxTurn.js";
 const requestId = (agentId, nativeSessionId) => `${INBOX_CHECK_PREFIX}recovery:${createHash("sha256").update(JSON.stringify([agentId, nativeSessionId])).digest("hex")}`;
+function recoveryCandidate(store, roleName) {
+    const sessions = store.getGlobalRoleSessionSet(roleName);
+    const session = sessions?.sessions[sessions.activeAgentId];
+    const binding = sessions?.providerBinding;
+    if (!session || session.status !== "active" || !session.nativeSessionId || !binding
+        || binding.authority.owner !== "controller"
+        || currentProviderConversation(binding).conversationId !== session.nativeSessionId
+        || binding.run && ["submitting", "accepted", "delivery-unknown"].includes(binding.run.status)
+        || hasRuntimeCleanupObligation(store.getWorkMailbox(runtimeLifecycleTarget({ scope: "global", roleName }))))
+        return;
+    if (store.queryGlobalRoleMessages(roleName, { handling: true, handlingExceptSession: {
+            agentId: session.agentId, nativeSessionId: session.nativeSessionId
+        }, limit: 0 }).count === 0)
+        return;
+    const id = requestId(session.agentId, session.nativeSessionId);
+    return { id, agentId: session.agentId, nativeSessionId: session.nativeSessionId,
+        existing: store.queryGlobalRoleMessages(roleName, { requestId: id, limit: 1 }).messages[0] };
+}
 /** Derive a single initialization notice from existing retained claims. New
  * Sessions are created only by the existing authorized lifecycle path. A
  * restart can finish notice creation, but cannot select or replace a Session. */
 export function globalInboxRecovery(store, roleName, now) {
+    // The common idle/already-notified path must not reserve SQLite's writer.
+    // This snapshot is only a preflight; creation rechecks all authority, cleanup
+    // and retained-claim facts in the original atomic transaction.
+    const candidate = store.readTransaction(tx => recoveryCandidate(tx, roleName));
+    if (!candidate || candidate.existing)
+        return candidate?.existing;
     return store.transaction(tx => {
-        const sessions = tx.getGlobalRoleSessionSet(roleName);
-        const session = sessions?.sessions[sessions.activeAgentId];
-        const binding = sessions?.providerBinding;
-        if (!session || session.status !== "active" || !session.nativeSessionId || !binding
-            || binding.authority.owner !== "controller"
-            || currentProviderConversation(binding).conversationId !== session.nativeSessionId
-            || binding.run && ["submitting", "accepted", "delivery-unknown"].includes(binding.run.status)
-            || hasRuntimeCleanupObligation(tx.getWorkMailbox(runtimeLifecycleTarget({ scope: "global", roleName }))))
-            return;
-        if (tx.queryGlobalRoleMessages(roleName, { handling: true, handlingExceptSession: {
-                agentId: session.agentId, nativeSessionId: session.nativeSessionId
-            }, limit: 0 }).count === 0)
-            return;
-        const id = requestId(session.agentId, session.nativeSessionId);
-        const existing = tx.queryGlobalRoleMessages(roleName, { requestId: id, limit: 1 }).messages[0];
-        if (existing)
-            return existing;
+        const latest = recoveryCandidate(tx, roleName);
+        if (!latest || latest.existing)
+            return latest?.existing;
+        const { id, agentId, nativeSessionId } = latest;
         const notice = {
             ...createGlobalRoleMessage(tx.nextGlobalRoleMessageId(), roleName, [
                 "Yui-Summary: This successor has retained inbox handling obligations; inspect original evidence before settlement.",
@@ -34,9 +45,9 @@ export function globalInboxRecovery(store, roleName, now) {
                 "After handling under current authority, explicitly acknowledge the original entry without replacing its claim.",
                 "Uncertain external effects require verification or a real user decision. New queued input remains separate."
             ].join("\n"), "system", { type: "system" }, now, {
-                inputControl: { action: "queue", requestId: id, expectedSessionId: session.nativeSessionId }
+                inputControl: { action: "queue", requestId: id, expectedSessionId: nativeSessionId }
             }),
-            deliveryTarget: { agentId: session.agentId, nativeSessionId: session.nativeSessionId }
+            deliveryTarget: { agentId, nativeSessionId }
         };
         tx.saveGlobalRoleMessage(notice);
         return notice;

package/dist/message/globalProviderRetry.js

@@ -2,6 +2,12 @@ import { markGlobalRoleMessageNotDelivered } from "./message.js";
 /** Settle the original queue entry when recovery ends with exact nondelivery.
  * Cancellation of a submitted/unknown request is not negative Provider proof. */
 export function settleGlobalRetryInput(store, roleName, binding, now) {
+    const settlement = globalRetryInputSettlement(store, roleName, binding, now);
+    if (settlement !== undefined)
+        store.updateGlobalRoleMessage(settlement);
+}
+/** Read-only proposal; callers applying it must recheck under their transaction. */
+export function globalRetryInputSettlement(store, roleName, binding, now) {
     const retry = binding?.retry;
     if (retry === undefined || retry.input.kind !== "message" || retry.input.roleName !== roleName
         || !["cancelled", "exhausted", "needs-attention"].includes(retry.status)
@@ -11,5 +17,5 @@ export function settleGlobalRetryInput(store, roleName, binding, now) {
     const message = store.listGlobalRoleMessages(roleName).find(m => m.id === messageId);
     if (message === undefined || message.delivery !== undefined || message.notDelivered !== undefined)
         return;
-    store.updateGlobalRoleMessage(markGlobalRoleMessageNotDelivered(message, `provider-retry-${retry.status}: ${retry.reason ?? retry.failureRef}`, now));
+    return markGlobalRoleMessageNotDelivered(message, `provider-retry-${retry.status}: ${retry.reason ?? retry.failureRef}`, now);
 }

package/dist/runtime/builtinAgentErrorMappers.js

@@ -30,6 +30,10 @@ export function mapCodexAgentError(input) {
 }
 function mapCodexDisplayError(input) {
     const text = `${input.message}\n${input.raw}`;
+    if (/Codex Session availability is systemError; no input was submitted\./u.test(text)) {
+        return { category: "session", code: "provider.session-system-error",
+            inputDisposition: "not-accepted", sessionDisposition: "unknown" };
+    }
     if (/^server_error$/iu.test(input.message)) {
         return recoverable("availability", "provider.server-error");
     }

package/dist/runtime/globalSessionHealth.js

@@ -0,0 +1,39 @@
+import { currentProviderConversation } from "./providerRuntimeIdentity.js";
+import { providerRetrySummary } from "./providerRetry.js";
+/** Read-only provenance. Writer selection is not live Host/transport health. */
+export function globalSessionHealth(role, sessions) {
+    const session = sessions?.sessions[role.activeAgentId];
+    const binding = sessions?.providerBinding;
+    const matches = session !== undefined && binding != null
+        && sessions?.activeAgentId === role.activeAgentId
+        && currentProviderConversation(binding).conversationId === session.nativeSessionId;
+    // Conversation replacement retains the terminal Turn as audit evidence while
+    // advancing writer authority. Matching the new conversation alone is insufficient.
+    const turnMatches = matches && binding.run?.authorityEpoch === binding.authority.epoch;
+    const turn = turnMatches ? binding.run : null;
+    const retry = matches && binding.retry?.nativeSessionId === session?.nativeSessionId
+        && binding.retry?.authorityEpoch === binding.authority.epoch
+        ? providerRetrySummary(binding) : null;
+    const failure = turn?.status === "failed" || turn?.status === "rejected" ? turn.failure : undefined;
+    return {
+        desiredRevision: role.launchRevision,
+        effectiveRevision: session?.effective.sourceDesiredRevision ?? null,
+        configurationDrift: session === undefined ? null
+            : session.effective.sourceDesiredRevision !== role.launchRevision,
+        nativeSessionId: session?.nativeSessionId ?? null,
+        nativeTurn: turn == null ? null : {
+            attemptId: turn.attemptId, nativeTurnId: turn.nativeTurnId, status: turn.status
+        },
+        currentFailure: failure === undefined ? null : {
+            ref: failure.ref, source: failure.error.source, phase: failure.error.phase,
+            category: failure.error.category, code: failure.error.code,
+            inputDisposition: failure.error.inputDisposition,
+            sessionDisposition: failure.error.sessionDisposition
+        },
+        retry,
+        historicalBinding: binding != null && (!matches || (binding.run !== null && !turnMatches)),
+        hostObservation: "unobserved",
+        note: "Selected/active writer state is not delivery or terminal-observation health. "
+            + "Inspect exact Host capabilities and runtime diagnostics; Controller restart does not refresh a live Host."
+    };
+}

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/contextRecords.js

@@ -54,6 +54,22 @@ export function queryContextRecords(db, taskId, query) {
     const from = `${table} r${candidate ? ", json_each(r.payload, '$.candidates') candidate" : ""}`;
     const where = ["r.task_id = @taskId"];
     const params = { taskId };
+    if (query.eventAttemptId !== undefined) {
+        if (query.family !== "task-event")
+            throw new Error("Attempt selection requires Events.");
+        where.push("json_extract(r.payload, '$.payload.attemptId') = @eventAttemptId");
+        params.eventAttemptId = query.eventAttemptId;
+    }
+    if (query.queuedForRole !== undefined) {
+        if (query.family !== "task-message")
+            throw new Error("Queued Role selection requires Messages.");
+        where.push(`json_extract(r.payload, '$.recipient.roleName') = @queuedRole
+      AND json_extract(r.payload, '$.recipient.ownerRunId') IS NOT NULL
+      AND json_extract(r.payload, '$.inbox') IS NULL
+      AND json_extract(r.payload, '$.continuation.runId') IS NULL
+      AND COALESCE(json_extract(r.payload, '$.inputControl.action'), '') != 'steer'`);
+        params.queuedRole = query.queuedForRole;
+    }
     if (query.ids !== undefined) {
         where.push(`${id} IN (SELECT value FROM json_each(@ids))`);
         params.ids = JSON.stringify(query.ids);