@llblab/pi-actors 0.43.0 → 0.44.0

package/dist/lib/limits.js

@@ -1,12 +1,14 @@
 /**
- * Shared output and preview size limits.
- * Zones: output governance, Trace previews, inspect defaults
+ * Shared output, preview, and Control envelope limits.
+ * Zones: output governance, Trace previews, Inspect defaults, Control portability
  */
 export const DEFAULT_INSPECT_LINES = 40;
 export const TOOL_OUTPUT_MAX_BYTES = 50 * 1024;
 export const TOOL_OUTPUT_MAX_LINES = 2_000;
 export const COMPACT_PREVIEW_CHARS = 160;
-export const CONTROL_INPUT_MAX_BYTES = 64 * 1024;
+export const CONTROL_ACTION_MAX_LENGTH = 64;
+export const CONTROL_INPUT_MAX_BYTES = 380;
+export const CONTROL_WIRE_MAX_BYTES = 512;
 export const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export const DOCTOR_ACTION_PREVIEW_CHARS = 72;
 export const SESSION_EVIDENCE_MAX_TURNS = 100;
@@ -14,3 +16,13 @@ export const SESSION_EVIDENCE_TEXT_CHARS = 4_000;
 export const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;
 export const TRACE_EVENT_MAX_BYTES = 64 * 1024;
 export const TRACE_EVENT_MAX_READ = 200;
+export const TRACE_JOURNAL_MAX_EVENTS = 2_048;
+export const TRACE_JOURNAL_TARGET_EVENTS = 1_536;
+export const TRACE_JOURNAL_MAX_BYTES = 4 * 1024 * 1024;
+export const TRACE_JOURNAL_TARGET_BYTES = 3 * 1024 * 1024;
+export const RUN_CONTROL_PENDING_LIMIT = 64;
+export const RUN_CONTROL_TERMINAL_LIMIT = 128;
+export const RUN_CONTROL_ERROR_MAX_BYTES = 4 * 1024;
+export const RUN_CONTROL_JOURNAL_MAX_BYTES = 1024 * 1024;
+export const RUN_RETENTION_MAX_RECORDS = 256;
+export const RUN_RETENTION_MAX_BYTES = 1024 * 1024;

package/dist/lib/observability.d.ts

@@ -42,7 +42,7 @@ export interface RunSummary {
 }
 export interface RunUiObservationState {
     attentionEventIds: Map<string, Set<string>>;
-    eventLines: Map<string, number>;
+    legacyEventLines: Map<string, number>;
     frame: number;
     observed: Map<string, RunObservedStatus>;
 }
@@ -62,6 +62,7 @@ export interface RunUiNotificationSink {
     }): void;
 }
 export declare function createRunUiObservationState(): RunUiObservationState;
+export declare function primeRunAttentionState(state: RunUiObservationState, ownerId: string, stateRoot?: string): void;
 export declare function readRunUiSnapshot(state: RunUiObservationState, ownerId: string, options?: {
     includeAttention?: boolean;
     stateRoot?: string;
@@ -74,6 +75,7 @@ export declare function reconcileRunTerminalNotifications(input: {
     sink: RunUiNotificationSink;
     state: RunUiObservationState;
     stateRoot?: string;
+    includeAttention?: boolean;
 }): RunUiSnapshot;
 export declare function deliverRunAttentionNotifications(events: RunAttentionEvent[], sink: RunUiNotificationSink): void;
 export interface RunRetirementCandidate {
@@ -173,7 +175,7 @@ export declare function findRunRetirementCandidates(summary: RunSummary): RunRet
 export declare function executeRunRetirements(summary: RunSummary, options: RunRetirementExecutorOptions): Promise<RunRetirementExecution[]>;
 export declare function detectRunTransitions(previous: Map<string, RunObservedStatus>, summary: RunSummary): RunTransition[];
 export declare function pruneRunObservationState(previousStatuses: Map<string, RunObservedStatus>, previousLineCounts: Map<string, number>, summary: RunSummary, terminalRuns?: Iterable<string>, seenEventIds?: Map<string, Set<string>>): void;
-export declare function detectRunAttentionEvents(previousLineCounts: Map<string, number>, summary: RunSummary, seenEventIds?: Map<string, Set<string>>): RunAttentionEvent[];
+export declare function detectRunAttentionEvents(legacyLineCounts: Map<string, number>, summary: RunSummary, seenEventIds?: Map<string, Set<string>>, prime?: boolean): RunAttentionEvent[];
 export declare function getRunAttentionNotificationType(event: RunAttentionEvent): RunTransitionNotificationType;
 export declare function shouldNotifyRunAttentionEvent(event: RunAttentionEvent): boolean;
 export declare function shouldSendRunAttentionFollowUp(event: RunAttentionEvent): boolean;

package/dist/lib/observability.js

@@ -7,29 +7,33 @@ import { closeSync, existsSync, fstatSync, openSync, readdirSync, readFileSync,
 import { basename, dirname, isAbsolute, join, relative, } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as Paths from "./paths.js";
+import * as RunsTrace from "./runs-trace.js";
 import { readJsonlFileResilient } from "./state-readers.js";
 export function createRunUiObservationState() {
     return {
         attentionEventIds: new Map(),
-        eventLines: new Map(),
+        legacyEventLines: new Map(),
         frame: 0,
         observed: new Map(),
     };
 }
+export function primeRunAttentionState(state, ownerId, stateRoot) {
+    detectRunAttentionEvents(state.legacyEventLines, summarizeRuns(stateRoot, ownerId), state.attentionEventIds, true);
+}
 export function readRunUiSnapshot(state, ownerId, options = {}) {
     const summary = summarizeRuns(options.stateRoot, ownerId);
     const status = renderRunStatus(summary, state.frame++);
     return {
         attentionEvents: options.includeAttention === false
             ? []
-            : detectRunAttentionEvents(state.eventLines, summary, state.attentionEventIds),
+            : detectRunAttentionEvents(state.legacyEventLines, summary, state.attentionEventIds),
         status,
         summary,
         transitions: detectRunTransitions(state.observed, summary),
     };
 }
 export function pruneRunUiObservationState(state, snapshot) {
-    pruneRunObservationState(state.observed, state.eventLines, snapshot.summary, snapshot.transitions.map((transition) => transition.stateDir ?? transition.run), state.attentionEventIds);
+    pruneRunObservationState(state.observed, state.legacyEventLines, snapshot.summary, snapshot.transitions.map((transition) => transition.stateDir ?? transition.run), state.attentionEventIds);
 }
 export function deliverRunTransitionNotifications(transitions, sink, inFlight = new Set()) {
     for (const transition of transitions) {
@@ -68,9 +72,11 @@ export function deliverRunTransitionNotifications(transitions, sink, inFlight =
 }
 export function reconcileRunTerminalNotifications(input) {
     const snapshot = readRunUiSnapshot(input.state, input.ownerId, {
-        includeAttention: false,
+        includeAttention: input.includeAttention,
         stateRoot: input.stateRoot,
     });
+    if (input.includeAttention)
+        deliverRunAttentionNotifications(snapshot.attentionEvents, input.sink);
     deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
     pruneRunUiObservationState(input.state, snapshot);
     return snapshot;
@@ -769,12 +775,13 @@ function parseAttentionRecord(raw, run, index) {
 }
 function readTraceAttentionRecords(run) {
     if (!run.stateDir)
-        return [];
-    const tracePath = join(run.stateDir, "trace.jsonl");
-    if (existsSync(tracePath)) {
-        return readJsonlFileResilient(tracePath).records;
-    }
-    return readJsonlFileResilient(join(run.stateDir, "outbox.jsonl")).records;
+        return { canonical: true, records: [] };
+    if (existsSync(join(run.stateDir, "trace.jsonl")))
+        return {
+            canonical: true,
+            records: RunsTrace.readRunTraceJournal(run.stateDir).events.map(({ event }) => event),
+        };
+    return { canonical: false, records: readJsonlFileResilient(join(run.stateDir, "outbox.jsonl")).records };
 }
 export function pruneRunObservationState(previousStatuses, previousLineCounts, summary, terminalRuns = [], seenEventIds = new Map()) {
     const activeRuns = new Set(summary.runs.map((run) => runObservationKey(run)));
@@ -785,43 +792,43 @@ export function pruneRunObservationState(previousStatuses, previousLineCounts, s
     const activeLineKeys = new Set(summary.runs.map((run) => run.stateDir ?? run.run));
     for (const run of terminalRunSet)
         previousStatuses.delete(run);
-    for (const run of previousStatuses.keys()) {
+    for (const run of previousStatuses.keys())
         if (!activeRuns.has(run))
             previousStatuses.delete(run);
-    }
-    for (const key of previousLineCounts.keys()) {
-        if (terminalLineKeys.has(key) || !activeLineKeys.has(key)) {
+    for (const key of previousLineCounts.keys())
+        if (terminalLineKeys.has(key) || !activeLineKeys.has(key))
             previousLineCounts.delete(key);
-        }
-    }
-    for (const key of seenEventIds.keys()) {
-        if (terminalLineKeys.has(key) || !activeLineKeys.has(key)) {
+    for (const key of seenEventIds.keys())
+        if (terminalLineKeys.has(key) || !activeLineKeys.has(key))
             seenEventIds.delete(key);
-        }
-    }
 }
-export function detectRunAttentionEvents(previousLineCounts, summary, seenEventIds = new Map()) {
+export function detectRunAttentionEvents(legacyLineCounts, summary, seenEventIds = new Map(), prime = false) {
     const events = [];
     for (const run of summary.runs) {
         const key = run.stateDir ?? run.run;
-        const records = readTraceAttentionRecords(run);
-        const previousCount = previousLineCounts.get(key) ?? 0;
-        if (run.notificationPolicy === "silent") {
-            previousLineCounts.set(key, records.length);
-            seenEventIds.set(key, seenEventIds.get(key) ?? new Set());
-            continue;
-        }
-        const start = Math.min(previousCount, records.length);
+        const read = readTraceAttentionRecords(run);
+        const retained = new Set();
         const seen = seenEventIds.get(key) ?? new Set();
-        for (let index = start; index < records.length; index += 1) {
-            const event = parseAttentionRecord(records[index], run, index);
-            if (!event || seen.has(event.id))
+        const start = read.canonical ? 0
+            : Math.min(legacyLineCounts.get(key) ?? 0, read.records.length);
+        for (const [index, record] of read.records.entries()) {
+            const event = parseAttentionRecord(record, run, index);
+            if (!event || !shouldNotifyRunAttentionEvent(event) ||
+                event.kind === "runtime.trace_compacted")
                 continue;
-            events.push(event);
-            seen.add(event.id);
+            retained.add(event.id);
+            if (prime || run.notificationPolicy === "silent")
+                seen.add(event.id);
+            else if (index >= start && !seen.has(event.id)) {
+                events.push(event);
+                seen.add(event.id);
+            }
         }
-        previousLineCounts.set(key, records.length);
-        seenEventIds.set(key, seen);
+        seenEventIds.set(key, new Set([...retained].filter((id) => seen.has(id))));
+        if (read.canonical)
+            legacyLineCounts.delete(key);
+        else
+            legacyLineCounts.set(key, read.records.length);
     }
     return events;
 }

package/dist/lib/prompts.d.ts

@@ -6,7 +6,7 @@
 export declare const REGISTER_TOOL_DESCRIPTION: string;
 export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node\u2192bun\u2192deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";

package/dist/lib/prompts.js

@@ -16,7 +16,7 @@ export const REGISTER_TOOL_GUIDELINES = [
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
 - Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
-- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
+- Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node→bun→deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
 - Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
 - ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
 - Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.

package/dist/lib/recipe-control.js

@@ -3,7 +3,8 @@
  * Zones: actor-local action declarations, normalization, reserved-action fencing
  * Owns pure Recipe control validation; Recipe loading and Run capture stay in recipe/run domains.
  */
-const ACTION_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)*$/;
+import * as Control from "./control.js";
+import * as Limits from "./limits.js";
 const RUNTIME_RUN_ACTIONS = new Set(["archive", "kill", "prune"]);
 export function normalizeRecipeControl(value) {
     if (value === undefined)
@@ -18,9 +19,12 @@ export function normalizeRecipeControl(value) {
             throw new Error("recipe.control actions must be non-empty strings");
         }
         const action = raw.trim();
-        if (!ACTION_PATTERN.test(action)) {
+        if (!Control.isControlAction(action)) {
             throw new Error(`invalid recipe.control action: ${action}`);
         }
+        if (action.length > Limits.CONTROL_ACTION_MAX_LENGTH) {
+            throw new Error(`recipe.control action exceeds ${Limits.CONTROL_ACTION_MAX_LENGTH} ASCII characters: ${action}`);
+        }
         if (RUNTIME_RUN_ACTIONS.has(action)) {
             throw new Error(`recipe.control action is runtime-reserved and must not be declared: ${action}`);
         }

package/dist/lib/review-control.d.ts

@@ -11,4 +11,4 @@ export interface AutomaticReviewControlOptions {
     toolStatePath?: string;
 }
 export declare function controlAutomaticReview(action: AutomaticReviewControlAction, scope: AutomaticReviewScope, options?: AutomaticReviewControlOptions): Record<string, unknown>;
-export declare function parseAutomaticReviewScope(body: unknown): AutomaticReviewScope;
+export declare function parseAutomaticReviewScope(input: unknown): AutomaticReviewScope;

package/dist/lib/review-control.js

@@ -98,14 +98,13 @@ export function controlAutomaticReview(action, scope, options = {}) {
     return {
         ...result,
         next_actions: nextActions,
-        sent: result.changed === true,
     };
 }
-export function parseAutomaticReviewScope(body) {
-    const record = body && typeof body === "object" && !Array.isArray(body)
-        ? body
+export function parseAutomaticReviewScope(input) {
+    const record = input && typeof input === "object" && !Array.isArray(input)
+        ? input
         : {};
     if (record.scope === "draft" || record.scope === "tool")
         return record.scope;
-    throw new Error("review control requires body.scope=draft or body.scope=tool.");
+    throw new Error("review Control requires input.scope=draft or input.scope=tool.");
 }

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-control-delivery.d.ts

@@ -16,6 +16,13 @@ export interface DeliverRunControlRequest {
     input?: unknown;
     run_instance_id: string;
 }
-export declare const FIFO_ATOMIC_CONTROL_MAX_BYTES = 512;
+export declare function encodeRunControlWire(wire: {
+    action: string;
+    id: string;
+    input?: unknown;
+}): {
+    bytes: number;
+    payload: string;
+};
 export declare function readRunControlEndpoint(stateDir: string, runInstanceId: string): RunControlEndpoint | undefined;
 export declare function deliverRunControl(run: string, stateDir: string, request: DeliverRunControlRequest, options?: DeliverRunControlOptions): Promise<Record<string, unknown>>;