@llblab/pi-actors 0.43.1 → 0.44.0

package/dist/lib/run-evidence-policy.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Pure bounded Run-evidence policy.
+ * Zones: Trace retention, compaction accounting, Control capacity and admission
+ * Owns deterministic limits policy; journal I/O, locks, lifecycle authorization, and projection stay in adapters.
+ * Trace keeps the newest physical suffix because semantic priority would silently
+ * redefine causal history. Admitted Controls never expire: only a real terminal
+ * transition or generation replacement proves that durable work is finished.
+ */
+export declare const TRACE_COMPACTION_KIND = "runtime.trace_compacted";
+export declare const TRACE_COMPACTION_VERSION = 1;
+export type TraceJournalUsage = {
+    bytes: number;
+    events: number;
+};
+export type TraceRetentionCandidate<T> = {
+    encodedBytes: number;
+    value: T;
+};
+export type TraceRetentionSelection<T> = {
+    droppedEvents: number;
+    retained: TraceRetentionCandidate<T>[];
+    retainedBytes: number;
+    retainedEvents: number;
+};
+export interface TraceCompactionData {
+    version: typeof TRACE_COMPACTION_VERSION;
+    compactions_total: number;
+    dropped_valid_events_total: number;
+    dropped_malformed_lines_total: number;
+    dropped_bytes_total: number;
+    dropped_event_count_exact: boolean;
+    retained_events: number;
+    retained_bytes: number;
+    history_complete: false;
+}
+export interface TraceCompactionDelta {
+    dropped_valid_events: number;
+    dropped_malformed_lines: number;
+    dropped_bytes: number;
+    dropped_event_count_exact: boolean;
+    retained_events: number;
+    retained_bytes: number;
+}
+export type RunControlStatus = "queued" | "delivered" | "claimed" | "handled" | "failed";
+export type RunControlCapacity = {
+    available: number;
+    backpressured: boolean;
+    limit: number;
+    oldest_pending_at?: string;
+    pending: number;
+};
+export type RunControlAdmissionIntegrity = "valid" | "unreadable" | "malformed" | "noncanonical" | "invalid_record" | "invalid_status_timestamp" | "generation_mismatch" | "journal_bytes";
+export interface RunControlAdmissionErrorDetails {
+    reason: "control_backpressure" | "control_journal_integrity";
+    pending: number;
+    limit: number;
+    journal_bytes: number;
+    journal_limit: number;
+    oldest_pending_at?: string;
+    run_instance_id: string;
+    next_actions: string[];
+    integrity_reason?: string;
+}
+export type RunControlAdmissionDecision = {
+    admitted: true;
+    capacity: RunControlCapacity;
+} | {
+    admitted: false;
+    capacity: RunControlCapacity;
+    error: RunControlAdmissionErrorDetails;
+};
+export type RunControlAdmissionInput = {
+    integrity: RunControlAdmissionIntegrity;
+    journalBytes: number;
+    newRecordBytes: number;
+    records: readonly unknown[];
+    retainedJournalBytes: number;
+    runInstanceId: string;
+    capacity?: RunControlCapacity;
+};
+export declare function traceAppendFits(usage: TraceJournalUsage, encodedEventBytes: number): boolean;
+export declare function selectNewestTraceSuffix<T>(candidates: readonly TraceRetentionCandidate<T>[], reserve?: {
+    bytes?: number;
+    events?: number;
+}): TraceRetentionSelection<T>;
+export declare function accumulateTraceCompactionStatistics(previous: TraceCompactionData | undefined, delta: TraceCompactionDelta): TraceCompactionData;
+export declare function traceCompactionMarkerInput(data: TraceCompactionData): {
+    data: TraceCompactionData;
+    kind: typeof TRACE_COMPACTION_KIND;
+    level: "warning";
+};
+export declare function classifyRunControlRecord(value: unknown): "pending" | "terminal" | undefined;
+export declare function runControlStatusTimestamp(record: Record<string, unknown>, status: RunControlStatus): unknown;
+export declare function computeRunControlCapacity(records: readonly unknown[]): RunControlCapacity;
+export declare function decideRunControlAdmission(input: RunControlAdmissionInput): RunControlAdmissionDecision;

package/dist/lib/run-evidence-policy.js

@@ -0,0 +1,177 @@
+/**
+ * Pure bounded Run-evidence policy.
+ * Zones: Trace retention, compaction accounting, Control capacity and admission
+ * Owns deterministic limits policy; journal I/O, locks, lifecycle authorization, and projection stay in adapters.
+ * Trace keeps the newest physical suffix because semantic priority would silently
+ * redefine causal history. Admitted Controls never expire: only a real terminal
+ * transition or generation replacement proves that durable work is finished.
+ */
+import * as Limits from "./limits.js";
+export const TRACE_COMPACTION_KIND = "runtime.trace_compacted";
+export const TRACE_COMPACTION_VERSION = 1;
+const PENDING_CONTROL_STATUSES = new Set(["queued", "delivered", "claimed"]);
+const TERMINAL_CONTROL_STATUSES = new Set(["handled", "failed"]);
+const CONTROL_ADMISSION_NEXT_ACTIONS = [
+    "inspect target=run:<id> view=control",
+    "inspect target=runtime view=triage",
+];
+function isCount(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function assertCount(value, name) {
+    if (!isCount(value))
+        throw new RangeError(`${name} must be a non-negative safe integer`);
+}
+function boundedAdd(left, right) {
+    return Math.min(Number.MAX_SAFE_INTEGER, left + right);
+}
+export function traceAppendFits(usage, encodedEventBytes) {
+    if (!isCount(usage.events) || !isCount(usage.bytes) || !isCount(encodedEventBytes))
+        return false;
+    return usage.events + 1 <= Limits.TRACE_JOURNAL_MAX_EVENTS &&
+        usage.bytes + encodedEventBytes <= Limits.TRACE_JOURNAL_MAX_BYTES;
+}
+export function selectNewestTraceSuffix(candidates, reserve = {}) {
+    const reservedBytes = reserve.bytes ?? 0;
+    const reservedEvents = reserve.events ?? 0;
+    assertCount(reservedBytes, "reserved Trace bytes");
+    assertCount(reservedEvents, "reserved Trace events");
+    const byteBudget = Math.max(0, Limits.TRACE_JOURNAL_TARGET_BYTES - reservedBytes);
+    const eventBudget = Math.max(0, Limits.TRACE_JOURNAL_TARGET_EVENTS - reservedEvents);
+    let retainedBytes = 0;
+    let start = candidates.length;
+    while (start > 0 && candidates.length - start < eventBudget) {
+        const candidate = candidates[start - 1];
+        assertCount(candidate.encodedBytes, "encoded Trace bytes");
+        if (retainedBytes + candidate.encodedBytes > byteBudget)
+            break;
+        retainedBytes += candidate.encodedBytes;
+        start -= 1;
+    }
+    const retained = candidates.slice(start);
+    return {
+        droppedEvents: candidates.length - retained.length,
+        retained,
+        retainedBytes,
+        retainedEvents: retained.length,
+    };
+}
+export function accumulateTraceCompactionStatistics(previous, delta) {
+    for (const [name, value] of Object.entries(delta)) {
+        if (name !== "dropped_event_count_exact")
+            assertCount(value, name);
+    }
+    const prior = previous ?? {
+        compactions_total: 0,
+        dropped_bytes_total: 0,
+        dropped_event_count_exact: true,
+        dropped_malformed_lines_total: 0,
+        dropped_valid_events_total: 0,
+    };
+    const eventCountOverflow = prior.dropped_valid_events_total +
+        delta.dropped_valid_events > Number.MAX_SAFE_INTEGER;
+    return {
+        version: TRACE_COMPACTION_VERSION,
+        compactions_total: boundedAdd(prior.compactions_total, 1),
+        dropped_valid_events_total: boundedAdd(prior.dropped_valid_events_total, delta.dropped_valid_events),
+        dropped_malformed_lines_total: boundedAdd(prior.dropped_malformed_lines_total, delta.dropped_malformed_lines),
+        dropped_bytes_total: boundedAdd(prior.dropped_bytes_total, delta.dropped_bytes),
+        dropped_event_count_exact: prior.dropped_event_count_exact &&
+            delta.dropped_event_count_exact && !eventCountOverflow,
+        retained_events: delta.retained_events,
+        retained_bytes: delta.retained_bytes,
+        history_complete: false,
+    };
+}
+export function traceCompactionMarkerInput(data) {
+    return { data, kind: TRACE_COMPACTION_KIND, level: "warning" };
+}
+export function classifyRunControlRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const status = value.status;
+    if (PENDING_CONTROL_STATUSES.has(status))
+        return "pending";
+    if (TERMINAL_CONTROL_STATUSES.has(status))
+        return "terminal";
+    return undefined;
+}
+export function runControlStatusTimestamp(record, status) {
+    if (status === "failed")
+        return record.failed_at;
+    if (status === "handled")
+        return record.handled_at;
+    if (status === "claimed")
+        return record.claimed_at;
+    if (status === "delivered")
+        return record.delivered_at;
+    return record.queued_at;
+}
+export function computeRunControlCapacity(records) {
+    let oldest;
+    let pending = 0;
+    for (const value of records) {
+        if (classifyRunControlRecord(value) !== "pending")
+            continue;
+        pending += 1;
+        const record = value;
+        const timestamp = runControlStatusTimestamp(record, record.status);
+        const timestampMs = typeof timestamp === "string" ? Date.parse(timestamp) : Number.NaN;
+        if (typeof timestamp === "string" && Number.isFinite(timestampMs) &&
+            (!oldest || timestampMs < oldest.timestampMs)) {
+            oldest = { timestamp, timestampMs };
+        }
+    }
+    return {
+        available: Math.max(0, Limits.RUN_CONTROL_PENDING_LIMIT - pending),
+        backpressured: pending >= Limits.RUN_CONTROL_PENDING_LIMIT,
+        limit: Limits.RUN_CONTROL_PENDING_LIMIT,
+        ...(oldest ? { oldest_pending_at: oldest.timestamp } : {}),
+        pending,
+    };
+}
+export function decideRunControlAdmission(input) {
+    const capacity = input.capacity ?? computeRunControlCapacity(input.records);
+    const reject = (reason, integrityReason) => ({
+        admitted: false,
+        capacity,
+        error: {
+            reason,
+            pending: capacity.pending,
+            limit: capacity.limit,
+            journal_bytes: input.journalBytes,
+            journal_limit: Limits.RUN_CONTROL_JOURNAL_MAX_BYTES,
+            ...(capacity.oldest_pending_at ? { oldest_pending_at: capacity.oldest_pending_at } : {}),
+            run_instance_id: input.runInstanceId,
+            next_actions: [...CONTROL_ADMISSION_NEXT_ACTIONS],
+            ...(integrityReason ? { integrity_reason: integrityReason } : {}),
+        },
+    });
+    if (input.integrity !== "valid")
+        return reject("control_journal_integrity", input.integrity);
+    if (!isCount(input.journalBytes) || !isCount(input.retainedJournalBytes) ||
+        !isCount(input.newRecordBytes) ||
+        input.journalBytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+        return reject("control_journal_integrity", "journal_bytes");
+    }
+    for (const value of input.records) {
+        const classification = classifyRunControlRecord(value);
+        if (!classification)
+            return reject("control_journal_integrity", "invalid_record");
+        if (classification !== "pending")
+            continue;
+        const record = value;
+        const timestamp = runControlStatusTimestamp(record, record.status);
+        if (typeof timestamp !== "string" || !Number.isFinite(Date.parse(timestamp))) {
+            return reject("control_journal_integrity", "invalid_status_timestamp");
+        }
+        if (record.run_instance_id !== input.runInstanceId) {
+            return reject("control_journal_integrity", "generation_mismatch");
+        }
+    }
+    if (capacity.backpressured ||
+        input.retainedJournalBytes + input.newRecordBytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+        return reject("control_backpressure");
+    }
+    return { admitted: true, capacity };
+}

package/dist/lib/run-ui-runtime.js

@@ -79,6 +79,7 @@ export function createRunUiRuntime(deps) {
                 ownerId: deps.getRunOwnerId(ctx),
                 sink: Pi.createNotificationSink(deps.pi, ctx),
                 state: observation,
+                includeAttention: true,
             });
             reportDiagnostics(ctx);
         },
@@ -110,6 +111,7 @@ export function createRunUiRuntime(deps) {
         },
         start(ctx) {
             close();
+            Observability.primeRunAttentionState(observation, deps.getRunOwnerId(ctx));
             update(ctx, true, true);
             watcher.refresh();
             reconciliation.start();

package/dist/lib/runs-controls.d.ts

@@ -1,11 +1,12 @@
 /**
  * Run Control journal.
- * Zones: durable Control records, claim locks, status transitions, bounded compaction
- * Owns Run-local Control persistence; owner/generation authorization and transport delivery stay in lifecycle adapters.
+ * Zones: durable records, atomic admission, claims, transitions, compaction
+ * Owns Run-local Control persistence; lifecycle authorization and transport stay in adapters.
  */
-import { type JsonlReadResult } from "./state-readers.ts";
-export declare const RUN_CONTROL_TERMINAL_LIMIT = 128;
-export type RunControlStatus = "queued" | "delivered" | "claimed" | "handled" | "failed";
+import { type RunControlStatus } from "./run-evidence-policy.ts";
+import type { JsonlReadResult } from "./state-readers.ts";
+export { RUN_CONTROL_TERMINAL_LIMIT } from "./limits.ts";
+export type { RunControlStatus } from "./run-evidence-policy.ts";
 export interface RunControlRecord {
     id: string;
     run_instance_id: string;
@@ -34,4 +35,5 @@ export declare function appendRunControlInStateDir(stateDir: string, request: {
 }): RunControlRecord;
 export declare function updateRunControlStatusInStateDir(stateDir: string, id: string, nextStatus: RunControlStatus, metadata?: Pick<RunControlRecord, "error">, expectedStatuses?: readonly RunControlStatus[]): boolean;
 export declare function claimRunControlInStateDir(stateDir: string, runInstanceId: string): RunControlRecord | undefined;
+export declare function claimRunControlByIdInStateDir(stateDir: string, runInstanceId: string, controlId: string): RunControlRecord | undefined;
 export declare function processRunControlsInStateDir(stateDir: string, runInstanceId: string, handler: (control: RunControlRecord) => Promise<void> | void, limit?: number): Promise<ProcessRunControlsResult>;

package/dist/lib/runs-controls.js

@@ -1,20 +1,73 @@
 /**
  * Run Control journal.
- * Zones: durable Control records, claim locks, status transitions, bounded compaction
- * Owns Run-local Control persistence; owner/generation authorization and transport delivery stay in lifecycle adapters.
+ * Zones: durable records, atomic admission, claims, transitions, compaction
+ * Owns Run-local Control persistence; lifecycle authorization and transport stay in adapters.
  */
 import { randomUUID } from "node:crypto";
-import { writeFileSync } from "node:fs";
+import { closeSync, fstatSync, openSync, readSync, statSync } from "node:fs";
 import { join } from "node:path";
+import * as Control from "./control.js";
 import { acquireFileMutationLock, writeTextAtomic } from "./file-state.js";
-import { readJsonlFileResilient, } from "./state-readers.js";
-export const RUN_CONTROL_TERMINAL_LIMIT = 128;
-const TERMINAL_STATUSES = new Set(["handled", "failed"]);
+import * as Limits from "./limits.js";
+import { classifyRunControlRecord, computeRunControlCapacity, decideRunControlAdmission, runControlStatusTimestamp, } from "./run-evidence-policy.js";
+export { RUN_CONTROL_TERMINAL_LIMIT } from "./limits.js";
+function admissionError(details) {
+    return Object.assign(new Error(details.reason === "control_backpressure"
+        ? `Run Control admission backpressured: pending=${details.pending}/${details.limit}`
+        : `Run Control journal integrity failed: ${details.integrity_reason ?? "unknown"}`), details);
+}
+const STATUSES = new Set([
+    "queued", "delivered", "claimed", "handled", "failed",
+]);
 export function runControlsFile(stateDir) {
     return join(stateDir, "controls.jsonl");
 }
 export function readRunControlJournalFromStateDir(stateDir) {
-    return readJsonlFileResilient(runControlsFile(stateDir));
+    const path = runControlsFile(stateDir);
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { diagnostics: [], records: [] };
+        return { diagnostics: [{ message: String(error), path }], records: [] };
+    }
+    try {
+        const bytes = fstatSync(fd).size;
+        if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+            return { diagnostics: [{ message: "Run Control journal exceeds bounded read limit", path }], records: [] };
+        }
+        const buffer = Buffer.allocUnsafe(bytes);
+        let consumed = 0;
+        while (consumed < bytes) {
+            const count = readSync(fd, buffer, consumed, bytes - consumed, consumed);
+            if (count === 0)
+                return { diagnostics: [{ message: "Run Control journal changed during bounded read", path }], records: [] };
+            consumed += count;
+        }
+        if (fstatSync(fd).size !== bytes)
+            return { diagnostics: [{ message: "Run Control journal changed during bounded read", path }], records: [] };
+        const records = [];
+        const diagnostics = [];
+        for (const [index, line] of buffer.toString("utf8").split("\n").entries()) {
+            if (!line.trim())
+                continue;
+            try {
+                records.push(JSON.parse(line));
+            }
+            catch (error) {
+                diagnostics.push({ line: index + 1, message: String(error), path });
+            }
+        }
+        return { diagnostics, records };
+    }
+    catch (error) {
+        return { diagnostics: [{ message: String(error), path }], records: [] };
+    }
+    finally {
+        closeSync(fd);
+    }
 }
 export function readRunControlsFromStateDir(stateDir) {
     return readRunControlJournalFromStateDir(stateDir).records;
@@ -23,47 +76,135 @@ function acquireRunControlsLock(stateDir) {
     return acquireFileMutationLock(runControlsFile(stateDir));
 }
 function compactRunControls(records) {
-    const active = records.filter((record) => !TERMINAL_STATUSES.has(record.status));
-    const terminal = records
-        .filter((record) => TERMINAL_STATUSES.has(record.status))
-        .slice(-RUN_CONTROL_TERMINAL_LIMIT);
+    const active = records.filter((record) => classifyRunControlRecord(record) !== "terminal");
+    const terminal = records.filter((record) => classifyRunControlRecord(record) === "terminal")
+        .slice(-Limits.RUN_CONTROL_TERMINAL_LIMIT);
     const retained = new Set([...active, ...terminal]);
-    return records.filter((record) => retained.has(record));
+    return records.filter((record) => retained.has(record)).map((record) => typeof record.error === "string" && Buffer.byteLength(record.error) > Limits.RUN_CONTROL_ERROR_MAX_BYTES
+        ? { ...record, error: boundedControlError(record.error) } : record);
+}
+function encodeRunControls(records) {
+    return records.length ? `${records.map((record) => JSON.stringify(record)).join("\n")}\n` : "";
+}
+function boundedControlError(value) {
+    if (Buffer.byteLength(value) <= Limits.RUN_CONTROL_ERROR_MAX_BYTES)
+        return value;
+    const suffix = "… [truncated]";
+    const limit = Limits.RUN_CONTROL_ERROR_MAX_BYTES - Buffer.byteLength(suffix);
+    const bytes = Buffer.from(value);
+    let end = limit;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return `${bytes.subarray(0, end).toString("utf8")}${suffix}`;
 }
 function writeRunControls(stateDir, records) {
-    const compacted = compactRunControls(records);
-    writeTextAtomic(runControlsFile(stateDir), compacted.length
-        ? `${compacted.map((record) => JSON.stringify(record)).join("\n")}\n`
-        : "");
+    const encoded = encodeRunControls(compactRunControls(records));
+    if (Buffer.byteLength(encoded) > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+        throw new Error("Run Control journal transition exceeds bounded byte limit");
+    }
+    writeTextAtomic(runControlsFile(stateDir), encoded);
+}
+function readMutableRunControls(stateDir, runInstanceId) {
+    const journal = readRunControlJournalFromStateDir(stateDir);
+    if (journal.diagnostics.length)
+        return undefined;
+    const records = journal.records;
+    if (runInstanceId && records.some((record) => controlIntegrity(record, runInstanceId) !== "valid"))
+        return undefined;
+    return records;
+}
+function controlIntegrity(value, runInstanceId) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return "invalid_record";
+    const record = value;
+    if (typeof record.id !== "string" || !record.id ||
+        typeof record.run_instance_id !== "string" || !record.run_instance_id ||
+        typeof record.status !== "string" || !STATUSES.has(record.status) ||
+        (record.error !== undefined && typeof record.error !== "string"))
+        return "invalid_record";
+    try {
+        Control.normalizeControlAction(record.action);
+        if (record.input !== undefined)
+            Control.normalizeControlInput(record.input);
+    }
+    catch {
+        return "invalid_record";
+    }
+    const timestamp = runControlStatusTimestamp(record, record.status);
+    if (typeof timestamp !== "string" || !Number.isFinite(Date.parse(timestamp)))
+        return "invalid_status_timestamp";
+    if (classifyRunControlRecord(record) === "pending" &&
+        record.run_instance_id !== runInstanceId)
+        return "generation_mismatch";
+    return "valid";
 }
 export function appendRunControlInStateDir(stateDir, request) {
+    const action = Control.normalizeControlAction(request.action);
+    const input = request.input === undefined ? undefined : Control.normalizeControlInput(request.input);
     const record = {
         id: randomUUID(),
         run_instance_id: request.run_instance_id,
-        action: request.action,
-        ...(request.input !== undefined ? { input: request.input } : {}),
+        action,
+        ...(input !== undefined ? { input } : {}),
         status: "queued",
         queued_at: new Date().toISOString(),
     };
+    const encodedRecordBytes = Buffer.byteLength(`${JSON.stringify(record)}\n`);
     const releaseLock = acquireRunControlsLock(stateDir);
     try {
-        writeFileSync(runControlsFile(stateDir), `${JSON.stringify(record)}\n`, {
-            flag: "a",
+        const path = runControlsFile(stateDir);
+        let bytes = 0;
+        try {
+            bytes = statSync(path).size;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                bytes = Number.MAX_SAFE_INTEGER;
+        }
+        const journal = bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES
+            ? { diagnostics: [], records: [] } : readRunControlJournalFromStateDir(stateDir);
+        let integrity = bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES
+            ? "journal_bytes"
+            : journal.diagnostics.some((item) => item.line !== undefined)
+                ? "malformed"
+                : journal.diagnostics.length ? "unreadable" : "valid";
+        for (const value of journal.records) {
+            if (integrity !== "valid")
+                break;
+            integrity = controlIntegrity(value, request.run_instance_id);
+        }
+        const records = journal.records;
+        const retained = encodeRunControls(compactRunControls(records));
+        const decision = decideRunControlAdmission({
+            integrity,
+            journalBytes: bytes,
+            newRecordBytes: encodedRecordBytes,
+            records,
+            retainedJournalBytes: Buffer.byteLength(retained),
+            runInstanceId: request.run_instance_id,
+            capacity: computeRunControlCapacity(records),
         });
+        if (!decision.admitted)
+            throw admissionError(decision.error);
+        writeTextAtomic(path, `${retained}${JSON.stringify(record)}\n`);
+        return record;
     }
     finally {
         releaseLock();
     }
-    return record;
 }
 export function updateRunControlStatusInStateDir(stateDir, id, nextStatus, metadata = {}, expectedStatuses) {
     const releaseLock = acquireRunControlsLock(stateDir);
     try {
-        const records = readRunControlsFromStateDir(stateDir);
+        const records = readMutableRunControls(stateDir);
+        if (!records)
+            return false;
         const index = records.findIndex((record) => record.id === id);
         if (index < 0)
             return false;
         const record = records[index];
+        if (records.some((value) => controlIntegrity(value, record.run_instance_id) !== "valid"))
+            return false;
         if (expectedStatuses && !expectedStatuses.includes(record.status))
             return false;
         if (record.status === nextStatus)
@@ -72,28 +213,19 @@ export function updateRunControlStatusInStateDir(stateDir, id, nextStatus, metad
         if (nextStatus === "delivered") {
             if (record.delivered_at)
                 return false;
-            records[index] = {
-                ...record,
-                delivered_at: timestamp,
-                ...(record.status === "queued" ? { status: "delivered" } : {}),
-            };
+            records[index] = { ...record, delivered_at: timestamp,
+                ...(record.status === "queued" ? { status: "delivered" } : {}) };
         }
         else {
-            if (TERMINAL_STATUSES.has(record.status) || nextStatus === "queued")
+            if (classifyRunControlRecord(record) === "terminal" || nextStatus === "queued")
                 return false;
-            if ((nextStatus === "claimed" &&
-                record.status !== "queued" &&
+            if ((nextStatus === "claimed" && record.status !== "queued" &&
                 record.status !== "delivered") ||
-                (nextStatus === "handled" && record.status !== "claimed")) {
+                (nextStatus === "handled" && record.status !== "claimed"))
                 return false;
-            }
-            const timestampKey = `${nextStatus}_at`;
-            records[index] = {
-                ...record,
-                ...metadata,
-                [timestampKey]: timestamp,
-                status: nextStatus,
-            };
+            records[index] = { ...record,
+                ...(metadata.error !== undefined ? { error: boundedControlError(metadata.error) } : {}),
+                [`${nextStatus}_at`]: timestamp, status: nextStatus };
         }
         writeRunControls(stateDir, records);
         return true;
@@ -102,18 +234,19 @@ export function updateRunControlStatusInStateDir(stateDir, id, nextStatus, metad
         releaseLock();
     }
 }
-export function claimRunControlInStateDir(stateDir, runInstanceId) {
+function claimRunControl(stateDir, runInstanceId, controlId) {
     const releaseLock = acquireRunControlsLock(stateDir);
     try {
-        const records = readRunControlsFromStateDir(stateDir);
-        const index = records.findIndex((record) => record.run_instance_id === runInstanceId &&
+        const records = readMutableRunControls(stateDir, runInstanceId);
+        if (!records)
+            return undefined;
+        const index = records.findIndex((record) => (controlId === undefined || record.id === controlId) &&
+            record.run_instance_id === runInstanceId &&
             (record.status === "queued" || record.status === "delivered"));
         if (index < 0)
             return undefined;
         const claimed = {
-            ...records[index],
-            claimed_at: new Date().toISOString(),
-            status: "claimed",
+            ...records[index], claimed_at: new Date().toISOString(), status: "claimed"
         };
         records[index] = claimed;
         writeRunControls(stateDir, records);
@@ -123,6 +256,12 @@ export function claimRunControlInStateDir(stateDir, runInstanceId) {
         releaseLock();
     }
 }
+export function claimRunControlInStateDir(stateDir, runInstanceId) {
+    return claimRunControl(stateDir, runInstanceId);
+}
+export function claimRunControlByIdInStateDir(stateDir, runInstanceId, controlId) {
+    return claimRunControl(stateDir, runInstanceId, controlId);
+}
 export async function processRunControlsInStateDir(stateDir, runInstanceId, handler, limit = 1) {
     const result = { claimed: 0, failed: 0, handled: 0 };
     for (let index = 0; index < Math.max(1, limit); index += 1) {
@@ -132,14 +271,12 @@ export async function processRunControlsInStateDir(stateDir, runInstanceId, hand
         result.claimed += 1;
         try {
             await handler(control);
-            if (updateRunControlStatusInStateDir(stateDir, control.id, "handled", {}, ["claimed"])) {
+            if (updateRunControlStatusInStateDir(stateDir, control.id, "handled", {}, ["claimed"]))
                 result.handled += 1;
-            }
         }
         catch (error) {
-            if (updateRunControlStatusInStateDir(stateDir, control.id, "failed", { error: error instanceof Error ? error.message : String(error) }, ["claimed"])) {
+            if (updateRunControlStatusInStateDir(stateDir, control.id, "failed", { error: error instanceof Error ? error.message : String(error) }, ["claimed"]))
                 result.failed += 1;
-            }
         }
     }
     return result;