@llblab/pi-actors 0.43.0 → 0.44.0

package/lib/inspector-overlay.ts

@@ -4,7 +4,7 @@
  * Owns manual kernel navigation; evidence parsing and lifecycle mutation stay in ports.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import * as path from "node:path";
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
@@ -16,8 +16,13 @@ import {
 } from "@earendil-works/pi-tui";
 
 import * as ActorInspector from "./inspector.ts";
+import * as ControlProjection from "./control-projection.ts";
 import * as RunsControls from "./runs-controls.ts";
 import * as RunControlDelivery from "./runs-control-delivery.ts";
+import * as RunsTrace from "./runs-trace.ts";
+import * as Limits from "./limits.ts";
+import { computeRunControlCapacity } from "./run-evidence-policy.ts";
+import * as RuntimeTriage from "./runtime-triage.ts";
 import * as TraceProjection from "./trace-projection.ts";
 
 export type ActorInspectorTab = "recipe" | "trace" | "control";
@@ -77,6 +82,7 @@ export class ActorInspectorOverlay {
   private killDialogChoice: "cancel" | "kill" = "cancel";
   private rowIndex = 0;
   private runCache?: ActorInspector.ActorInspectorRunItem[];
+  private selectedTraceId?: string;
   private runIndex = 0;
   private selectorIndex = 0;
   private selectorMode?: SelectorMode;
@@ -99,8 +105,7 @@ export class ActorInspectorOverlay {
     this.theme = options.theme;
     this.tui = options.tui;
     this.refreshTimer = setInterval(() => {
-      this.runCache = undefined;
-      if (this.focus !== "list" && this.focus !== "detail") this.traceCache = undefined;
+      this.invalidate();
       this.tui.requestRender();
     }, 1_000);
     this.refreshTimer.unref?.();
@@ -110,7 +115,10 @@ export class ActorInspectorOverlay {
     clearInterval(this.refreshTimer);
   }
 
-  invalidate(): void {}
+  invalidate(): void {
+    this.runCache = undefined;
+    this.traceCache = undefined;
+  }
 
   handleInput(data: string): void {
     const runs = this.runs();
@@ -134,10 +142,12 @@ export class ActorInspectorOverlay {
         this.selectorMode = undefined;
         this.focus = this.tab === "trace" ? "tabs" : "runs";
       } else if (this.focus === "detail") {
+        this.selectedTraceId = this.traceDetail?.id;
         this.traceDetail = undefined;
         this.detailScroll = 0;
         this.focus = "list";
       } else if (this.focus === "document" || this.focus === "list") {
+        if (this.focus === "list") this.selectedTraceId = undefined;
         this.focus = "tabs";
       } else {
         this.done();
@@ -179,19 +189,27 @@ export class ActorInspectorOverlay {
       } else if (matchesKey(data, "up")) {
         this.focus = "runs";
       } else if (matchesKey(data, "down")) {
-        this.focus = this.tab === "trace" && this.traceItems(runs[this.runIndex]).length > 0
-          ? "list"
-          : "document";
+        const items = this.tab === "trace" ? this.traceItems(runs[this.runIndex]) : [];
+        this.focus = items.length > 0 ? "list" : "document";
+        if (this.focus === "list") {
+          this.rowIndex = 0;
+          this.selectedTraceId = items[0]?.id;
+        }
       } else if (matchesKey(data, "return")) {
         if (this.tab === "trace") this.openSourceSelector(runs[this.runIndex]);
         else this.focus = "document";
       }
     } else if (this.focus === "list") {
-      const count = this.traceItems(runs[this.runIndex]).length;
-      if (matchesKey(data, "left")) this.focus = "tabs";
-      else if (matchesKey(data, "up")) {
-        if (this.rowIndex === 0) this.focus = "tabs";
-        else this.rowIndex -= 1;
+      const items = this.traceItems(runs[this.runIndex]);
+      const count = items.length;
+      if (matchesKey(data, "left")) {
+        this.selectedTraceId = undefined;
+        this.focus = "tabs";
+      } else if (matchesKey(data, "up")) {
+        if (this.rowIndex === 0) {
+          this.selectedTraceId = undefined;
+          this.focus = "tabs";
+        } else this.rowIndex -= 1;
       } else if (matchesKey(data, "down")) {
         this.rowIndex = Math.min(Math.max(0, count - 1), this.rowIndex + 1);
       } else if (matchesKey(data, "pageUp")) {
@@ -202,13 +220,14 @@ export class ActorInspectorOverlay {
           this.rowIndex + this.contentViewportRows(),
         );
       } else if (matchesKey(data, "return") || matchesKey(data, "right")) {
-        const item = this.traceItems(runs[this.runIndex])[this.rowIndex];
+        const item = items[this.rowIndex];
         if (item) {
           this.traceDetail = item;
           this.detailScroll = 0;
           this.focus = "detail";
         }
       }
+      if (this.focus === "list") this.selectedTraceId = items[this.rowIndex]?.id;
     }
     if (data.toLowerCase() === "f" && this.tab === "trace") {
       this.cycleTraceSource(runs[this.runIndex]);
@@ -273,6 +292,7 @@ export class ActorInspectorOverlay {
     this.documentScroll = 0;
     this.detailScroll = 0;
     this.rowIndex = 0;
+    this.selectedTraceId = undefined;
     this.traceDetail = undefined;
   }
 
@@ -291,6 +311,7 @@ export class ActorInspectorOverlay {
     } else if (matchesKey(data, "pageDown")) {
       this[key] += this.contentViewportRows();
     } else if (matchesKey(data, "left") && target === "detail") {
+      this.selectedTraceId = this.traceDetail?.id;
       this.traceDetail = undefined;
       this.detailScroll = 0;
       this.focus = "list";
@@ -392,7 +413,9 @@ export class ActorInspectorOverlay {
     this.killDialogChoice = "cancel";
     if (!confirmation || !this.killRun) return;
     try {
-      this.feedback = this.killRun(confirmation.run, confirmation.runInstanceId);
+      const result = this.killRun(confirmation.run, confirmation.runInstanceId);
+      this.feedback = result.ok ? undefined : result;
+      if (result.ok) this.invalidate();
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       this.feedback = {
@@ -417,8 +440,7 @@ export class ActorInspectorOverlay {
       `${this.theme.fg("muted", "Run:")} ${this.theme.fg("accent", `run:${confirmation.run}`)}`,
       `${this.theme.fg("muted", "Current status:")} ${this.theme.fg("warning", confirmation.status)}`,
       "",
-      this.theme.fg("text", "This sends canonical kill Control."),
-      this.theme.fg("error", "The action is destructive and cannot be undone."),
+      this.theme.fg("text", "This invokes generation-fenced runtime kill."),
       "",
       `${cancel}    ${kill}`,
       "",
@@ -520,15 +542,27 @@ export class ActorInspectorOverlay {
 
   private renderTraceList(run: ActorInspector.ActorInspectorRunItem): string[] {
     const items = this.traceItems(run);
-    if (items.length === 0) return [this.theme.fg("muted", " No Trace evidence")];
+    const summary = RunsTrace.summarizeRunTraceJournal(
+      RunsTrace.readRunTraceJournal(path.join(this.stateRoot, run.run)));
+    const banner = summary.history_complete ? [] : [this.theme.fg("warning",
+      ` ! Trace history incomplete: ${summary.compacted ? `${summary.compactions_total} compaction(s), ` : ""}${summary.dropped_event_count_exact ? summary.dropped_events : "unknown"} dropped event(s), ${summary.dropped_bytes} bytes`)];
+    if (items.length === 0) return [...banner, this.theme.fg("muted", " No Trace evidence")];
+    if (this.selectedTraceId) {
+      const selectedIndex = items.findIndex((item) => item.id === this.selectedTraceId);
+      if (selectedIndex >= 0) this.rowIndex = selectedIndex;
+      else this.selectedTraceId = undefined;
+    }
     this.rowIndex = Math.min(this.rowIndex, items.length - 1);
+    if (this.focus === "list" && !this.selectedTraceId) {
+      this.selectedTraceId = items[this.rowIndex]?.id;
+    }
     const viewportRows = this.contentViewportRows();
     const maxStart = Math.max(0, items.length - viewportRows);
     const start = Math.max(0, Math.min(this.rowIndex - Math.floor(viewportRows / 2), maxStart));
     this.contentStripeIndices = items
       .slice(start, start + viewportRows)
       .map((_item, offset) => start + offset);
-    return items.slice(start, start + viewportRows).map((item, offset) => {
+    return [...banner, ...items.slice(start, start + viewportRows - banner.length).map((item, offset) => {
       const index = start + offset;
       const detail = item.detail && typeof item.detail === "object"
         ? item.detail as Record<string, unknown>
@@ -536,16 +570,16 @@ export class ActorInspectorOverlay {
       const marker = item.level === "error"
         ? this.theme.fg("error", "!")
         : detail.attention
-          ? this.theme.fg("warning", "•")
-          : this.theme.fg("muted", "·");
+          ? this.theme.fg("warning", "A")
+          : " ";
       const prefix = this.focus === "list" && index === this.rowIndex
         ? this.theme.fg("accent", " ▶ ")
         : "   ";
-      const row = `${prefix}${this.theme.fg("text", `#${index + 1}`)} ${marker} ${this.theme.fg("muted", item.source)}/${this.theme.fg(item.level === "error" ? "error" : "accent", item.kind)}  ${this.theme.fg("text", item.summary)}`;
+      const row = `${prefix}${this.theme.fg("text", `#${items.length - index}`)} ${marker} ${this.theme.fg("muted", item.source)}/${this.theme.fg(item.level === "error" ? "error" : "accent", item.kind)}  ${this.theme.fg("text", item.summary)}`;
       return this.focus === "list" && index === this.rowIndex
         ? this.theme.fg("accent", row)
         : row;
-    });
+    })];
   }
 
   private renderTraceDetail(width: number): string[] {
@@ -571,13 +605,26 @@ export class ActorInspectorOverlay {
       ? RunControlDelivery.readRunControlEndpoint(stateDir, run.runInstanceId)
       : undefined;
     const meta = this.readRunMeta(stateDir);
+    const journal = RunsControls.readRunControlJournalFromStateDir(stateDir);
+    const capacity = computeRunControlCapacity(journal.records);
+    const stalePending = journal.records.reduce<number>((count, control) => count + Number(Boolean(
+      RuntimeTriage.classifyRuntimeControl({ run: run.run,
+        runInstanceId: run.runInstanceId, status: run.status }, control, Date.now()).stale)), 0);
     return {
       status: run.status,
       run_instance_id: run.runInstanceId,
+      pending: capacity.pending, pending_limit: capacity.limit,
+      available: capacity.available, backpressured: capacity.backpressured,
+      journal_bytes: (() => { try { return statSync(RunsControls.runControlsFile(stateDir)).size; } catch { return 0; } })(),
+      journal_limit: Limits.RUN_CONTROL_JOURNAL_MAX_BYTES,
+      stale_pending: stalePending,
+      diagnostics: journal.diagnostics.map((item) => item.line === undefined
+        ? { reason: "unreadable_control_journal" } : { line: item.line, reason: "invalid_control_json" }),
       actor_actions: Array.isArray(meta.control) ? meta.control : [],
       runtime_actions: run.status === "running" ? ["kill"] : ["archive", "prune"],
       endpoint,
-      recent_controls: RunsControls.readRunControlsFromStateDir(stateDir).slice(-20).reverse(),
+      recent_controls: journal.records.slice(-20).reverse().map((control) =>
+        ControlProjection.projectRunControl(control as RunsControls.RunControlRecord)),
     };
   }
 
@@ -627,14 +674,9 @@ export class ActorInspectorOverlay {
     width: number,
   ): { lines: string[]; stripes: number[] } {
     const sections = value && typeof value === "object" && !Array.isArray(value)
-      ? Object.entries(value as Record<string, unknown>).map(([key, item]) => {
-          const inline = this.inlineDocumentValue(item);
-          return inline !== undefined
-            ? [`${key}: ${inline}`]
-            : item && typeof item === "object"
-              ? [`${key}:`, ...this.document(item, 1)]
-              : this.labeledScalarLines(key, item);
-        })
+      ? Object.entries(value as Record<string, unknown>).map(([key, item]) =>
+          this.labeledDocumentLines(key, item)
+        )
       : [this.document(value)];
     const lines: string[] = [];
     const stripes: number[] = [];
@@ -658,23 +700,22 @@ export class ActorInspectorOverlay {
       return undefined;
     }
     if (value && typeof value === "object") {
-      const entries = Object.entries(value as Record<string, unknown>);
-      if (entries.length === 0) return "{}";
-      if (
-        entries.length <= 3 &&
-        entries.every(([, item]) =>
-          (item === null || typeof item !== "object") &&
-          !(typeof item === "string" && /[\r\n]/u.test(item))
-        )
-      ) {
-        return `{ ${entries
-          .map(([key, item]) => `${key}: ${String(item ?? "none")}`)
-          .join(", ")} }`;
-      }
+      if (Object.keys(value as Record<string, unknown>).length === 0) return "{}";
     }
     return undefined;
   }
 
+  private labeledDocumentLines(key: string, value: unknown, depth = 0): string[] {
+    const inline = this.inlineDocumentValue(value);
+    if (inline !== undefined) return [`${"  ".repeat(depth)}${key}: ${inline}`];
+    if (value && typeof value === "object") {
+      const indent = "  ".repeat(depth);
+      const nested = this.document(value, depth);
+      return [`${indent}${key}: ${nested[0]!.slice(indent.length)}`, ...nested.slice(1)];
+    }
+    return this.labeledScalarLines(key, value, depth);
+  }
+
   private labeledScalarLines(key: string, value: unknown, depth = 0): string[] {
     const indent = "  ".repeat(depth);
     const [first = "", ...rest] = String(value ?? "none").split(/\r?\n/u);
@@ -689,25 +730,31 @@ export class ActorInspectorOverlay {
     const inline = this.inlineDocumentValue(value);
     if (inline !== undefined) return [`${"  ".repeat(depth)}${inline}`];
     if (Array.isArray(value)) {
-      return value.flatMap((item, index) => {
-        const marker = `${"  ".repeat(depth)}- #${index + 1}`;
-        const itemInline = this.inlineDocumentValue(item);
-        return itemInline !== undefined
-          ? [`${marker}: ${itemInline}`]
-          : [marker, ...this.document(item, depth + 1)];
-      });
+      const indent = "  ".repeat(depth);
+      return [
+        `${indent}[`,
+        ...value.flatMap((item, index) => {
+          const marker = `${indent}  - #${index + 1}`;
+          const itemInline = this.inlineDocumentValue(item);
+          return itemInline !== undefined
+            ? [`${marker}: ${itemInline}`]
+            : [marker, ...this.document(item, depth + 2)];
+        }),
+        `${indent}]`,
+      ];
     }
     if (typeof value === "object") {
-      return Object.entries(value as Record<string, unknown>).flatMap(([key, item]) => {
-        const itemInline = this.inlineDocumentValue(item);
-        if (itemInline !== undefined) {
-          return [`${"  ".repeat(depth)}${key}: ${itemInline}`];
-        }
-        if (item && typeof item === "object") {
-          return [`${"  ".repeat(depth)}${key}:`, ...this.document(item, depth + 1)];
-        }
-        return this.labeledScalarLines(key, item, depth);
-      });
+      const indent = "  ".repeat(depth);
+      const entries = Object.entries(value as Record<string, unknown>);
+      return [
+        `${indent}{`,
+        ...entries.flatMap(([key, item], index) => {
+          const lines = this.labeledDocumentLines(key, item, depth + 1);
+          if (index < entries.length - 1) lines[lines.length - 1] += ",";
+          return lines;
+        }),
+        `${indent}}`,
+      ];
     }
     return String(value)
       .split(/\r?\n/u)

package/lib/limits.ts

@@ -1,13 +1,15 @@
 /**
- * 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;
@@ -15,3 +17,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/lib/observability.ts

@@ -25,6 +25,7 @@ import {
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as Paths from "./paths.ts";
+import * as RunsTrace from "./runs-trace.ts";
 import { readJsonlFileResilient } from "./state-readers.ts";
 
 export type RunObservedStatus =
@@ -73,7 +74,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>;
 }
@@ -98,12 +99,19 @@ export interface RunUiNotificationSink {
 export function createRunUiObservationState(): RunUiObservationState {
   return {
     attentionEventIds: new Map<string, Set<string>>(),
-    eventLines: new Map<string, number>(),
+    legacyEventLines: new Map<string, number>(),
     frame: 0,
     observed: new Map<string, RunObservedStatus>(),
   };
 }
 
+export function primeRunAttentionState(
+  state: RunUiObservationState, ownerId: string, stateRoot?: string,
+): void {
+  detectRunAttentionEvents(state.legacyEventLines, summarizeRuns(stateRoot, ownerId),
+    state.attentionEventIds, true);
+}
+
 export function readRunUiSnapshot(
   state: RunUiObservationState,
   ownerId: string,
@@ -116,7 +124,7 @@ export function readRunUiSnapshot(
       options.includeAttention === false
         ? []
         : detectRunAttentionEvents(
-            state.eventLines,
+            state.legacyEventLines,
             summary,
             state.attentionEventIds,
           ),
@@ -132,7 +140,7 @@ export function pruneRunUiObservationState(
 ): void {
   pruneRunObservationState(
     state.observed,
-    state.eventLines,
+    state.legacyEventLines,
     snapshot.summary,
     snapshot.transitions.map(
       (transition) => transition.stateDir ?? transition.run,
@@ -192,16 +200,15 @@ export function reconcileRunTerminalNotifications(input: {
   sink: RunUiNotificationSink;
   state: RunUiObservationState;
   stateRoot?: string;
+  includeAttention?: boolean;
 }): RunUiSnapshot {
   const snapshot = readRunUiSnapshot(input.state, input.ownerId, {
-    includeAttention: false,
+    includeAttention: input.includeAttention,
     stateRoot: input.stateRoot,
   });
-  deliverRunTransitionNotifications(
-    snapshot.transitions,
-    input.sink,
-    input.inFlight,
-  );
+  if (input.includeAttention)
+    deliverRunAttentionNotifications(snapshot.attentionEvents, input.sink);
+  deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
   pruneRunUiObservationState(input.state, snapshot);
   return snapshot;
 }
@@ -1114,15 +1121,17 @@ function parseAttentionRecord(
   };
 }
 
-function readTraceAttentionRecords(run: RunObservation): Record<string, unknown>[] {
-  if (!run.stateDir) return [];
-  const tracePath = join(run.stateDir, "trace.jsonl");
-  if (existsSync(tracePath)) {
-    return readJsonlFileResilient<Record<string, unknown>>(tracePath).records;
-  }
-  return readJsonlFileResilient<Record<string, unknown>>(
-    join(run.stateDir, "outbox.jsonl"),
-  ).records;
+function readTraceAttentionRecords(run: RunObservation): {
+  canonical: boolean; records: Record<string, unknown>[];
+} {
+  if (!run.stateDir) return { canonical: true, records: [] };
+  if (existsSync(join(run.stateDir, "trace.jsonl"))) return {
+    canonical: true,
+    records: RunsTrace.readRunTraceJournal(run.stateDir).events.map(
+      ({ event }) => event as unknown as Record<string, unknown>),
+  };
+  return { canonical: false, records: readJsonlFileResilient<Record<string, unknown>>(
+    join(run.stateDir, "outbox.jsonl")).records };
 }
 
 export function pruneRunObservationState(
@@ -1134,55 +1143,44 @@ export function pruneRunObservationState(
 ): void {
   const activeRuns = new Set(summary.runs.map((run) => runObservationKey(run)));
   const terminalRunSet = new Set(terminalRuns);
-  const terminalLineKeys = new Set(
-    summary.runs
-      .filter((run) => terminalRunSet.has(runObservationKey(run)))
-      .map((run) => runObservationKey(run)),
-  );
-  const activeLineKeys = new Set(
-    summary.runs.map((run) => run.stateDir ?? run.run),
-  );
+  const terminalLineKeys = new Set(summary.runs
+    .filter((run) => terminalRunSet.has(runObservationKey(run)))
+    .map((run) => runObservationKey(run)));
+  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)) {
-      previousLineCounts.delete(key);
-    }
-  }
-  for (const key of seenEventIds.keys()) {
-    if (terminalLineKeys.has(key) || !activeLineKeys.has(key)) {
-      seenEventIds.delete(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)) seenEventIds.delete(key);
 }
 
 export function detectRunAttentionEvents(
-  previousLineCounts: Map<string, number>,
-  summary: RunSummary,
-  seenEventIds: Map<string, Set<string>> = new Map(),
+  legacyLineCounts: Map<string, number>, summary: RunSummary,
+  seenEventIds: Map<string, Set<string>> = new Map(), prime = false,
 ): RunAttentionEvent[] {
   const events: RunAttentionEvent[] = [];
   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<string>());
-      continue;
-    }
-    const start = Math.min(previousCount, records.length);
+    const read = readTraceAttentionRecords(run);
+    const retained = new Set<string>();
     const seen = seenEventIds.get(key) ?? new Set<string>();
-    for (let index = start; index < records.length; index += 1) {
-      const event = parseAttentionRecord(records[index], run, index);
-      if (!event || seen.has(event.id)) continue;
-      events.push(event);
-      seen.add(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;
+      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/lib/prompts.ts

@@ -22,7 +22,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/lib/recipe-control.ts

@@ -4,7 +4,9 @@
  * 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.ts";
+import * as Limits from "./limits.ts";
+
 const RUNTIME_RUN_ACTIONS = new Set(["archive", "kill", "prune"]);
 
 export function normalizeRecipeControl(value: unknown): string[] | undefined {
@@ -19,9 +21,14 @@ export function normalizeRecipeControl(value: unknown): string[] | undefined {
       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/lib/review-control.ts

@@ -124,14 +124,13 @@ export function controlAutomaticReview(
   return {
     ...result,
     next_actions: nextActions,
-    sent: result.changed === true,
   };
 }
 
-export function parseAutomaticReviewScope(body: unknown): AutomaticReviewScope {
-  const record = body && typeof body === "object" && !Array.isArray(body)
-    ? body as Record<string, unknown>
+export function parseAutomaticReviewScope(input: unknown): AutomaticReviewScope {
+  const record = input && typeof input === "object" && !Array.isArray(input)
+    ? input as Record<string, unknown>
     : {};
   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.");
 }