@llblab/pi-actors 0.43.1 → 0.45.0

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;

package/dist/lib/runs-retention.js

@@ -3,9 +3,11 @@
  * Owns: terminal-run archive and prune filesystem behavior.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { acquireFileMutationLock, writeJsonAtomic } from "./file-state.js";
+import { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } from "./file-state.js";
+import * as Limits from "./limits.js";
+import { readJsonlFileResilient } from "./state-readers.js";
 import { resolveArtifactManifest, } from "./runs-artifacts.js";
 import { safeRunId } from "./runs-identity.js";
 import { assertOwnedRunStateDirectory } from "./runs-ownership.js";
@@ -13,26 +15,37 @@ export function appendRunRetentionEvidence(status, action, outcome, options = {}
     const stateDir = String(status.state_dir);
     const path = join(dirname(stateDir), "retention.jsonl");
     const id = options.id ?? randomUUID();
+    const record = {
+        action,
+        ...(options.error ? { error: options.error } : {}),
+        id,
+        outcome,
+        ...(options.result ? { result: options.result } : {}),
+        run: String(status.run ?? basename(stateDir)),
+        ...(typeof status.run_instance_id === "string" ? { run_instance_id: status.run_instance_id } : {}),
+        ts: new Date().toISOString(),
+    };
     const release = acquireFileMutationLock(path);
     try {
-        appendFileSync(path, `${JSON.stringify({
-            action,
-            ...(options.error ? { error: options.error } : {}),
-            id,
-            outcome,
-            ...(options.result ? { result: options.result } : {}),
-            run: String(status.run ?? basename(stateDir)),
-            ...(typeof status.run_instance_id === "string"
-                ? { run_instance_id: status.run_instance_id }
-                : {}),
-            ts: new Date().toISOString(),
-        })}\n`);
+        const records = [...readJsonlFileResilient(path).records, record]
+            .slice(-Limits.RUN_RETENTION_MAX_RECORDS);
+        let content = encodeRecords(records);
+        while (records.length && Buffer.byteLength(content) > Limits.RUN_RETENTION_MAX_BYTES) {
+            records.shift();
+            content = encodeRecords(records);
+        }
+        if (!records.includes(record))
+            throw new Error("Run retention record exceeds journal byte limit");
+        writeTextAtomic(path, content);
     }
     finally {
         release();
     }
     return id;
 }
+function encodeRecords(records) {
+    return records.length ? `${records.map((value) => JSON.stringify(value)).join("\n")}\n` : "";
+}
 function retainedArtifactFilename(name, path) {
     const readableName = name.replace(/[^A-Za-z0-9_.-]+/g, "_") || "artifact";
     const identity = createHash("sha256")

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

@@ -1,8 +1,9 @@
 /**
  * Run Trace event journal.
- * Zones: structured event validation, token-locked append-only writes, resilient bounded reads
+ * Zones: structured event validation, bounded atomic retention, resilient reads
  * Owns canonical Run-local Trace persistence; lifecycle projection and owner attention delivery stay in adapters.
  */
+import type { StateReadDiagnostic } from "./state-readers.ts";
 export interface TraceEvent {
     id: string;
     ts: string;
@@ -19,6 +20,29 @@ export interface AppendTraceEventInput {
     level?: TraceEvent["level"];
     attention?: TraceEvent["attention"];
 }
+export interface RunTraceReadEvent {
+    event: TraceEvent;
+    ordinal: number;
+}
+export interface RunTraceJournalRead {
+    diagnostics: StateReadDiagnostic[];
+    events: RunTraceReadEvent[];
+    fileBytes: number;
+    omittedPrefixBytes: number;
+    readBytes: number;
+}
+export interface RunTraceSummary {
+    compacted: boolean;
+    compactions_total: number;
+    dropped_bytes: number;
+    dropped_event_count_exact: boolean;
+    dropped_events: number;
+    history_complete: boolean;
+    retained_bytes: number;
+    retained_events: number;
+}
 export declare function runTraceFile(stateDir: string): string;
 export declare function appendRunTraceEvent(stateDir: string, input: AppendTraceEventInput): TraceEvent;
+export declare function readRunTraceJournal(stateDir: string): RunTraceJournalRead;
+export declare function summarizeRunTraceJournal(read: RunTraceJournalRead): RunTraceSummary;
 export declare function readRunTraceEvents(stateDir: string, limit?: number): TraceEvent[];