@llblab/pi-actors 0.43.0 → 0.43.1

package/dist/lib/inspector-overlay.d.ts

@@ -41,6 +41,7 @@ export declare class ActorInspectorOverlay {
     private killDialogChoice;
     private rowIndex;
     private runCache?;
+    private selectedTraceId?;
     private runIndex;
     private selectorIndex;
     private selectorMode?;
@@ -81,6 +82,7 @@ export declare class ActorInspectorOverlay {
     private readRunMeta;
     private documentProjection;
     private inlineDocumentValue;
+    private labeledDocumentLines;
     private labeledScalarLines;
     private document;
     private wrapDocument;

package/dist/lib/inspector-overlay.js

@@ -7,6 +7,7 @@ import { readFileSync } from "node:fs";
 import * as path from "node:path";
 import { matchesKey, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
 import * as ActorInspector from "./inspector.js";
+import * as ControlProjection from "./control-projection.js";
 import * as RunsControls from "./runs-controls.js";
 import * as RunControlDelivery from "./runs-control-delivery.js";
 import * as TraceProjection from "./trace-projection.js";
@@ -20,6 +21,9 @@ const TRACE_SOURCES = [
     "artifact",
     "runtime",
 ];
+function newestTraceItems(items) {
+    return [...items].sort((left, right) => right.ts.localeCompare(left.ts) || right.id.localeCompare(left.id));
+}
 export class ActorInspectorOverlay {
     done;
     killRun;
@@ -39,6 +43,7 @@ export class ActorInspectorOverlay {
     killDialogChoice = "cancel";
     rowIndex = 0;
     runCache;
+    selectedTraceId;
     runIndex = 0;
     selectorIndex = 0;
     selectorMode;
@@ -56,9 +61,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?.();
@@ -66,7 +69,10 @@ export class ActorInspectorOverlay {
     dispose() {
         clearInterval(this.refreshTimer);
     }
-    invalidate() { }
+    invalidate() {
+        this.runCache = undefined;
+        this.traceCache = undefined;
+    }
     handleInput(data) {
         const runs = this.runs();
         this.runIndex = Math.min(this.runIndex, Math.max(0, runs.length - 1));
@@ -90,11 +96,14 @@ export class ActorInspectorOverlay {
                 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 {
@@ -146,9 +155,12 @@ export class ActorInspectorOverlay {
                 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")
@@ -158,12 +170,17 @@ export class ActorInspectorOverlay {
             }
         }
         else if (this.focus === "list") {
-            const count = this.traceItems(runs[this.runIndex]).length;
-            if (matchesKey(data, "left"))
+            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)
+                if (this.rowIndex === 0) {
+                    this.selectedTraceId = undefined;
                     this.focus = "tabs";
+                }
                 else
                     this.rowIndex -= 1;
             }
@@ -177,13 +194,15 @@ export class ActorInspectorOverlay {
                 this.rowIndex = Math.min(Math.max(0, count - 1), 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]);
@@ -239,6 +258,7 @@ export class ActorInspectorOverlay {
         this.documentScroll = 0;
         this.detailScroll = 0;
         this.rowIndex = 0;
+        this.selectedTraceId = undefined;
         this.traceDetail = undefined;
     }
     cycleRun(runs, direction) {
@@ -260,6 +280,7 @@ export class ActorInspectorOverlay {
             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";
@@ -361,7 +382,10 @@ export class ActorInspectorOverlay {
         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);
@@ -387,7 +411,6 @@ export class ActorInspectorOverlay {
             `${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."),
             "",
             `${cancel}    ${kill}`,
             "",
@@ -480,7 +503,17 @@ export class ActorInspectorOverlay {
         const items = this.traceItems(run);
         if (items.length === 0)
             return [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));
@@ -495,12 +528,12 @@ 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;
@@ -526,7 +559,10 @@ export class ActorInspectorOverlay {
             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: RunsControls.readRunControlsFromStateDir(stateDir)
+                .slice(-20)
+                .reverse()
+                .map(ControlProjection.projectRunControl),
         };
     }
     allTraceItems(run) {
@@ -536,10 +572,10 @@ export class ActorInspectorOverlay {
             this.traceCache.runInstanceId === run.runInstanceId) {
             return this.traceCache.items;
         }
-        const items = this.readTrace(path.join(this.stateRoot, run.run), {
+        const items = newestTraceItems(this.readTrace(path.join(this.stateRoot, run.run), {
             limit: 100,
             source: "all",
-        });
+        }));
         this.traceCache = { run: run.run, runInstanceId: run.runInstanceId, items };
         return items;
     }
@@ -567,14 +603,7 @@ export class ActorInspectorOverlay {
     }
     documentProjection(value, width) {
         const sections = value && typeof value === "object" && !Array.isArray(value)
-            ? Object.entries(value).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).map(([key, item]) => this.labeledDocumentLines(key, item))
             : [this.document(value)];
         const lines = [];
         const stripes = [];
@@ -596,19 +625,22 @@ export class ActorInspectorOverlay {
             return undefined;
         }
         if (value && typeof value === "object") {
-            const entries = Object.entries(value);
-            if (entries.length === 0)
+            if (Object.keys(value).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(", ")} }`;
-            }
         }
         return undefined;
     }
+    labeledDocumentLines(key, value, depth = 0) {
+        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);
+    }
     labeledScalarLines(key, value, depth = 0) {
         const indent = "  ".repeat(depth);
         const [first = "", ...rest] = String(value ?? "none").split(/\r?\n/u);
@@ -624,25 +656,32 @@ export class ActorInspectorOverlay {
         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).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);
+            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/dist/lib/limits.d.ts

@@ -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 declare const DEFAULT_INSPECT_LINES = 40;
 export declare const TOOL_OUTPUT_MAX_BYTES: number;
 export declare const TOOL_OUTPUT_MAX_LINES = 2000;
 export declare const COMPACT_PREVIEW_CHARS = 160;
-export declare const CONTROL_INPUT_MAX_BYTES: number;
+export declare const CONTROL_ACTION_MAX_LENGTH = 64;
+export declare const CONTROL_INPUT_MAX_BYTES = 380;
+export declare const CONTROL_WIRE_MAX_BYTES = 512;
 export declare const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export declare const DOCTOR_ACTION_PREVIEW_CHARS = 72;
 export declare const SESSION_EVIDENCE_MAX_TURNS = 100;

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;

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/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>>;

package/dist/lib/runs-control-delivery.js

@@ -6,9 +6,23 @@
 import { closeSync, constants, existsSync, openSync, statSync, writeSync, } from "node:fs";
 import { createConnection } from "node:net";
 import { join } from "node:path";
+import * as Control from "./control.js";
+import * as Limits from "./limits.js";
 import { appendRunControlInStateDir, updateRunControlStatusInStateDir, } from "./runs-controls.js";
 import { readJsonFileResilient } from "./state-readers.js";
-export const FIFO_ATOMIC_CONTROL_MAX_BYTES = 512;
+const PREFLIGHT_CONTROL_ID = "00000000-0000-4000-8000-000000000000";
+export function encodeRunControlWire(wire) {
+    const payload = `${JSON.stringify({
+        id: wire.id,
+        action: wire.action,
+        ...(wire.input !== undefined ? { input: wire.input } : {}),
+    })}\n`;
+    const bytes = Buffer.byteLength(payload);
+    if (bytes > Limits.CONTROL_WIRE_MAX_BYTES) {
+        throw new Error(`Run Control wire record exceeds the ${Limits.CONTROL_WIRE_MAX_BYTES}-byte portable bound`);
+    }
+    return { bytes, payload };
+}
 export function readRunControlEndpoint(stateDir, runInstanceId) {
     const endpoint = readJsonFileResilient(join(stateDir, "control-endpoint.json"), {}).value;
     if (endpoint.run_instance_id !== runInstanceId)
@@ -65,34 +79,43 @@ function sendToNamedPipe(endpoint, payload, send) {
     });
 }
 export async function deliverRunControl(run, stateDir, request, options = {}) {
-    const control = appendRunControlInStateDir(stateDir, request);
+    const action = Control.normalizeControlAction(request.action);
+    const input = request.input === undefined
+        ? undefined
+        : Control.normalizeControlInput(request.input);
+    const normalizedRequest = {
+        action,
+        ...(input !== undefined ? { input } : {}),
+        run_instance_id: request.run_instance_id,
+    };
+    encodeRunControlWire({
+        id: PREFLIGHT_CONTROL_ID,
+        action,
+        ...(input !== undefined ? { input } : {}),
+    });
+    const control = appendRunControlInStateDir(stateDir, normalizedRequest);
     const endpoint = readRunControlEndpoint(stateDir, request.run_instance_id);
     if (!endpoint) {
         updateRunControlStatusInStateDir(stateDir, control.id, "failed", { error: "control endpoint is not ready for this Run generation" }, ["queued", "delivered"]);
         throw Object.assign(new Error("Run Control endpoint is not ready."), {
-            action: request.action,
+            action,
             control_id: control.id,
             reason: "endpoint_not_ready",
             run,
             run_instance_id: request.run_instance_id,
         });
     }
-    const wire = {
-        id: control.id,
-        action: request.action,
-        ...(request.input !== undefined ? { input: request.input } : {}),
-    };
-    const payload = `${JSON.stringify(wire)}\n`;
-    const bytes = Buffer.byteLength(payload);
     try {
+        const { bytes, payload } = encodeRunControlWire({
+            id: control.id,
+            action,
+            ...(input !== undefined ? { input } : {}),
+        });
         let written;
         if (endpoint.type === "fifo") {
             if ((options.platform ?? process.platform) === "win32") {
                 throw new Error("FIFO Control delivery is unsupported on native Windows");
             }
-            if (bytes > FIFO_ATOMIC_CONTROL_MAX_BYTES) {
-                throw new Error(`FIFO Control payload exceeds the ${FIFO_ATOMIC_CONTROL_MAX_BYTES}-byte portable atomic-write bound`);
-            }
             written = sendToFifo(endpoint, payload);
         }
         else {
@@ -103,7 +126,7 @@ export async function deliverRunControl(run, stateDir, request, options = {}) {
         }
         updateRunControlStatusInStateDir(stateDir, control.id, "delivered");
         return {
-            action: request.action,
+            action,
             bytes,
             control_id: control.id,
             delivery: "delivered",
@@ -116,7 +139,7 @@ export async function deliverRunControl(run, stateDir, request, options = {}) {
         const reason = error instanceof Error ? error.message : String(error);
         updateRunControlStatusInStateDir(stateDir, control.id, "failed", { error: reason }, ["queued", "delivered"]);
         throw Object.assign(new Error(`Run Control delivery failed: ${reason}`), {
-            action: request.action,
+            action,
             control_id: control.id,
             endpoint_type: endpoint.type,
             reason: "delivery_failed",

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

@@ -3,6 +3,7 @@
  * 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.
  */
+import { type JsonlReadResult } from "./state-readers.ts";
 export declare const RUN_CONTROL_TERMINAL_LIMIT = 128;
 export type RunControlStatus = "queued" | "delivered" | "claimed" | "handled" | "failed";
 export interface RunControlRecord {
@@ -24,6 +25,7 @@ export interface ProcessRunControlsResult {
     handled: number;
 }
 export declare function runControlsFile(stateDir: string): string;
+export declare function readRunControlJournalFromStateDir(stateDir: string): JsonlReadResult<unknown>;
 export declare function readRunControlsFromStateDir(stateDir: string): RunControlRecord[];
 export declare function appendRunControlInStateDir(stateDir: string, request: {
     run_instance_id: string;

package/dist/lib/runs-controls.js

@@ -7,15 +7,17 @@ import { randomUUID } from "node:crypto";
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { acquireFileMutationLock, writeTextAtomic } from "./file-state.js";
-import { readJsonlFileResilient } from "./state-readers.js";
+import { readJsonlFileResilient, } from "./state-readers.js";
 export const RUN_CONTROL_TERMINAL_LIMIT = 128;
 const TERMINAL_STATUSES = new Set(["handled", "failed"]);
 export function runControlsFile(stateDir) {
     return join(stateDir, "controls.jsonl");
 }
+export function readRunControlJournalFromStateDir(stateDir) {
+    return readJsonlFileResilient(runControlsFile(stateDir));
+}
 export function readRunControlsFromStateDir(stateDir) {
-    return readJsonlFileResilient(runControlsFile(stateDir))
-        .records;
+    return readRunControlJournalFromStateDir(stateDir).records;
 }
 function acquireRunControlsLock(stateDir) {
     return acquireFileMutationLock(runControlsFile(stateDir));

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

@@ -1,7 +1,7 @@
 /**
  * Run Trace event journal.
- * Zones: structured event validation, bounded append, resilient bounded reads
- * Owns Run-local semantic Trace events; lifecycle projection and owner attention delivery stay in adapters.
+ * Zones: structured event validation, token-locked append-only writes, resilient bounded reads
+ * Owns canonical Run-local Trace persistence; lifecycle projection and owner attention delivery stay in adapters.
  */
 export interface TraceEvent {
     id: string;