@llblab/pi-actors 0.43.0 → 0.44.0

package/README.md

@@ -53,8 +53,10 @@ Send one exact Control:
 Run targets accept only actions declared by the captured Recipe. Runtime targets accept only reserved review actions:
 
 ```text
-message target=runtime action=review.retry
-message target=runtime action=review.reset
+message target=runtime action=review.retry input={"scope":"draft"}
+message target=runtime action=review.retry input={"scope":"tool"}
+message target=runtime action=review.reset input={"scope":"draft"}
+message target=runtime action=review.reset input={"scope":"tool"}
 ```
 
 Lifecycle `kill` remains runtime-owned rather than Recipe-declared.
@@ -67,9 +69,9 @@ Inspect one exact management target:
 inspect target=run:test view=recipe
 inspect target=run:test view=trace source=lifecycle lines=40
 inspect target=run:test view=control
-inspect target=runtime
-inspect target=recipes
-inspect target=tool:my_tool
+inspect target=runtime view=status
+inspect target=recipes view=status
+inspect target=tool:my_tool view=status
 ```
 
 A Run exposes exactly `recipe`, `trace`, and `control` views.
@@ -119,13 +121,13 @@ String command-template leaves execute directly without shell interpretation. Us
 }
 ```
 
-Trace fields are exact: `id`, `ts`, `kind`, and optional `summary`, `data`, `level`, `attention`. Address, sender, recipient, reply, and routing fields fail validation.
+Trace fields are exact: `id`, `ts`, `kind`, and optional `summary`, `data`, `level`, `attention`. Address, sender, recipient, reply, and routing fields fail validation. Trace is a bounded retained suffix, not an audit archive: the canonical authority appends within 2,048 events and 4 MiB or atomically keeps the newest suffix plus one warning-only `runtime.trace_compacted` marker. That marker means older history was discarded; `result.json`, `execution.json`, terminal state, and declared artifacts retain their own authority. `inspect view=trace` reports whether retained history is complete. Reads are newline-safe and deterministic; first-party scripts never write this file directly.
 
-Use `attention: "notify"` for visible status and `attention: "followup"` only when the coordinator needs semantic follow-up context. Store large evidence in artifacts or bounded execution captures.
+Attention is a live wake hint, not a durable queue: persist recovery state or an artifact first. Use `attention: "notify"` for visible status and `attention: "followup"` only when the coordinator needs semantic follow-up context; compaction may discard older hints. Store large evidence in artifacts or bounded execution captures.
 
 ## Control
 
-Controls persist to `controls.jsonl` before transport. Token-owned dead-process-reclaiming locks serialize atomic journal replacements. Every record carries the immutable `run_instance_id`; expected-status fencing advances outcomes monotonically through queued/delivered/claimed/handled/failed evidence, while a fast consumer may claim or handle before the sender adds independent delivery-time evidence.
+Controls persist to `controls.jsonl` before transport. One token-owned lock rejects a 65th pending Control or 1 MiB rewrite before admission, fails closed on malformed or stale-generation evidence, and atomically admits one record. Canonical transitions retain a 128-terminal tail, expected-state fencing, and 4 KiB errors. Admitted nonterminal Controls never expire automatically. Every record carries immutable `run_instance_id`. `inspect view=control` reports pending capacity, saturation, stale work, journal bytes, and bounded diagnostics. If a stuck Run is saturated, use runtime-owned `kill`; it bypasses actor-local capacity and creates no synthetic Control.
 
 Long-lived services publish `control-endpoint.json` only when ready:
 
@@ -138,7 +140,7 @@ Long-lived services publish `control-endpoint.json` only when ready:
 }
 ```
 
-Supported transports are Unix FIFO and Windows named pipe. FIFO wire documents must fit the portable 512-byte atomic-write bound; larger Control input remains available to named-pipe services. Delivery revalidates owner, generation, state, and process identity under the canonical lifecycle lock.
+Supported transports are Unix FIFO and Windows named pipe. Every actor-local Control uses the same portable envelope: action is at most 64 lowercase ASCII characters, serialized JSON input is at most 380 bytes, and the newline-terminated wire record is at most 512 bytes. Put larger data in a declared artifact/path and send only its bounded reference or instruction through Control. Delivery revalidates owner, generation, state, and process identity under the canonical lifecycle lock.
 
 ## Run State
 
@@ -157,7 +159,7 @@ Core files:
 - `execution.json` — command/session provenance and complete-capture references;
 - `result.json`, command logs, progress, and declared artifacts.
 
-The runtime preserves owner filtering, process-identity verification, lifecycle locking, shutdown kill, terminal reconciliation, bounded captures, owned Pi sessions, path containment, and redaction.
+The runtime preserves owner filtering, process-identity verification, lifecycle locking, shutdown kill independent of actor-local Control capacity, terminal reconciliation, bounded captures, owned Pi sessions, path containment, and redaction. Trace/Control quotas do not constrain user-declared artifacts, repositories, media sources, complete captures, or actor-owned workload state. Restart clears generation-local Trace, Control, endpoint, execution, and terminal evidence; archive preserves the bounded tree, while prune preserves only requested artifacts.
 
 ## Actor Inspector
 
@@ -195,7 +197,7 @@ npm run validate
 npm run test:preservation
 ```
 
-See the [documentation index](./docs/README.md), [Run lifecycle](./docs/async-runs.md), [Recipe library](./docs/recipe-library.md), and [0.43 baseline](./docs/0.43-baseline.md).
+See the [documentation index](./docs/README.md), [Run lifecycle](./docs/async-runs.md), and [Recipe library](./docs/recipe-library.md).
 
 Project context: [AGENTS.md](./AGENTS.md) · [BACKLOG.md](./BACKLOG.md) · [CHANGELOG.md](./CHANGELOG.md).
 

package/dist/index.js

@@ -106,7 +106,7 @@ export default function toolRegistryExtension(pi) {
         configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
         getActiveTools: () => pi.getActiveTools(),
         getRuntimeTool: (name) => Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) => actorToolDefinitions.get(activeName)),
-        handleRuntimeMessage: automaticReview.handleMessage,
+        handleRuntimeControl: automaticReview.handleControl,
         registryRuntime: runtime,
         setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
     }).map(withCurrentThinkingContext));

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

@@ -7,6 +7,7 @@ import { type CurrentPolicyProvenance } from "./model-context.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import { type RunArtifactDeclaration } from "./runs-artifacts.ts";
 import { type RunProcessIdentity } from "./runs-process.ts";
+import * as RuntimeIdentity from "./runtime-identity.ts";
 import * as RunsIndex from "./runs-index.ts";
 import * as RunsParentTeardown from "./runs-parent-teardown.ts";
 import { type DeliverRunControlOptions, type DeliverRunControlRequest } from "./runs-control-delivery.ts";
@@ -77,7 +78,7 @@ export interface AsyncRunMeta {
     run: string;
     run_instance_id: string;
     state_dir: string;
-    state_schema: "run-kernel-v1";
+    state_schema: typeof RuntimeIdentity.RUN_STATE_SCHEMA;
     status: AsyncRunStatus;
     tool?: string;
     template: CommandTemplateValue;

package/dist/lib/async-runs.js

@@ -18,11 +18,11 @@ import { buildTerminalProgress, markTerminalHandled, signalOwnedRunProcess, } fr
 import { claimRunStateDirectory } from "./runs-ownership.js";
 import { appendRunRetentionEvidence, archiveTerminalRun, pruneTerminalRun, } from "./runs-retention.js";
 import { captureRunProcessIdentity, verifyRunProcessIdentity, } from "./runs-process.js";
+import * as RuntimeIdentity from "./runtime-identity.js";
 import * as RunsStart from "./runs-start.js";
 import { appendRunTraceEvent } from "./runs-trace.js";
 import * as RunsIndex from "./runs-index.js";
 import * as RunsParentTeardown from "./runs-parent-teardown.js";
-import { appendRunControlInStateDir, updateRunControlStatusInStateDir, } from "./runs-controls.js";
 import { deliverRunControl, } from "./runs-control-delivery.js";
 import { buildRunStatus, tailFile, } from "./runs-status.js";
 import { readJsonFileResilient } from "./state-readers.js";
@@ -236,7 +236,21 @@ export function startRun(params, cwd) {
     const resolved = resolveRunTemplate(startParams);
     const run = safeRunId(startParams.run_id);
     const stateDir = resolveStateDir(startParams, run);
+    const recipeFile = startParams.file
+        ? resolveRecipeFile(startParams.file)
+        : undefined;
+    const packagedRecipeRoot = resolve(Paths.getPackagedRecipeRoot());
+    const recipeRelation = recipeFile
+        ? relative(packagedRecipeRoot, recipeFile)
+        : undefined;
+    const packagedRepo = startParams.defaults?.repo === "~/.pi/agent/extensions/pi-actors" &&
+        recipeRelation &&
+        !recipeRelation.startsWith("..") &&
+        !isAbsolute(recipeRelation)
+        ? dirname(packagedRecipeRoot)
+        : undefined;
     const values = {
+        ...(packagedRepo ? { repo: packagedRepo } : {}),
         ...(startParams.values || {}),
         run_id: run,
         state_dir: stateDir,
@@ -259,9 +273,6 @@ export function startRun(params, cwd) {
         prepareStateDirForStart(stateDir);
         const stdout = join(stateDir, "stdout.log");
         const stderr = join(stateDir, "stderr.log");
-        const recipeFile = startParams.file
-            ? resolveRecipeFile(startParams.file)
-            : undefined;
         const recipe = startParams.name || getRunIdFromFile(recipeFile);
         const includeActorRecipeContext = startParams.actor_context !== false &&
             startParams.actor_context !== "off";
@@ -298,7 +309,7 @@ export function startRun(params, cwd) {
             run,
             run_instance_id: randomUUID(),
             state_dir: stateDir,
-            state_schema: "run-kernel-v1",
+            state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
             status: "running",
             ...(startParams.tool ? { tool: startParams.tool } : {}),
             template: resolved.template,
@@ -564,57 +575,36 @@ function stopRun(runOrDir, signal, event, expected = {}) {
             status.run_instance_id !== expected.runInstanceId) {
             return { stopped: false, reason: "run generation changed", status };
         }
-        const control = event === "run.kill" && typeof status.run_instance_id === "string"
-            ? appendRunControlInStateDir(stateDir, {
-                action: "kill",
-                run_instance_id: status.run_instance_id,
-            })
-            : undefined;
-        if (control) {
-            updateRunControlStatusInStateDir(stateDir, control.id, "claimed", {}, ["queued"]);
-        }
-        const finish = (result) => {
-            if (!control)
-                return result;
-            const handled = result.stopped === true;
-            updateRunControlStatusInStateDir(stateDir, control.id, handled ? "handled" : "failed", handled ? {} : { error: String(result.reason ?? "kill rejected") }, ["claimed"]);
-            return { ...result, control_id: control.id };
-        };
         const pid = Number(status.pid || 0);
         if (status.status !== "running" && status.status !== "exited") {
-            return finish({ stopped: false, reason: "not running", status });
+            return { stopped: false, reason: "not running", status };
         }
         const identity = verifyRunProcessIdentity(pid, status.process_identity);
         if (status.status === "exited") {
             if (identity.status === "owner_mismatch" ||
                 identity.status === "unsupported_proof") {
-                return finish({
+                return {
                     stopped: false,
                     reason: identity.status.replaceAll("_", " "),
                     process_identity_status: identity.status,
                     status,
-                });
+                };
             }
-            return finish({ stopped: false, reason: "not running", status });
+            return { stopped: false, reason: "not running", status };
         }
         if (!identity.valid) {
-            return finish({
+            return {
                 stopped: false,
                 reason: identity.status.replaceAll("_", " "),
                 process_identity_status: identity.status,
                 status,
-            });
+            };
         }
         let signalResult;
         try {
             signalResult = signalOwnedRunProcess(pid, signal, status.process_identity);
         }
         catch (error) {
-            if (control) {
-                updateRunControlStatusInStateDir(stateDir, control.id, "failed", {
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
             throw error;
         }
         appendRunTraceEvent(stateDir, {
@@ -631,13 +621,13 @@ function stopRun(runOrDir, signal, event, expected = {}) {
             finalizeInterruptedExecution(stateDir, "cancelled", signal);
             markTerminalProgress(stateDir, "cancelled");
         }
-        return finish({
+        return {
             stopped: true,
             pid,
             signal,
             ...signalResult,
             state_dir: stateDir,
-        });
+        };
     }
     finally {
         releaseControlLock();

package/dist/lib/automatic-review-runtime.d.ts

@@ -6,7 +6,7 @@
 import type * as Pi from "./pi.ts";
 export interface AutomaticReviewRuntime {
     close(): void;
-    handleMessage(type: string, body: unknown): Record<string, unknown>;
+    handleControl(action: string, input: unknown): Record<string, unknown>;
     schedule(): void;
     start(ctx: Pi.ExtensionContext): void;
 }

package/dist/lib/automatic-review-runtime.js

@@ -26,14 +26,14 @@ export function createAutomaticReviewRuntime(deps) {
     });
     return {
         close,
-        handleMessage(type, body) {
-            if (type !== "review.retry" && type !== "review.reset") {
-                throw new Error("tool:pi-actors accepts review.retry or review.reset messages.");
+        handleControl(action, input) {
+            if (action !== "review.retry" && action !== "review.reset") {
+                throw new Error("runtime accepts review.retry or review.reset Controls.");
             }
-            if (type === "review.retry" && !Paths.isAutomaticRecipeReviewEnabled()) {
+            if (action === "review.retry" && !Paths.isAutomaticRecipeReviewEnabled()) {
                 throw new Error("Automatic recipe review is disabled by PI_ACTORS_AUTOMATIC_REVIEW.");
             }
-            return ReviewControl.controlAutomaticReview(type, ReviewControl.parseAutomaticReviewScope(body), {
+            return ReviewControl.controlAutomaticReview(action, ReviewControl.parseAutomaticReviewScope(input), {
                 scheduleDraft: () => draftScheduler?.schedule(),
                 scheduleTool: () => toolScheduler?.schedule(),
             });

package/dist/lib/command-templates.d.ts

@@ -74,6 +74,8 @@ export declare function getCommandTemplateRiskLabels(config: CommandTemplateConf
 export declare function getCommandTemplateDefaults(config: CommandTemplateConfig | undefined): Record<string, string>;
 export declare function splitCommandTemplate(input: string): string[];
 export declare function expandCommandTemplateExecutable(command: string, cwd: string): string;
+export type CommandTemplateExecutableResolver = (name: string) => string | undefined;
+export declare function resolveCommandTemplateScriptInvocation(invocation: CommandTemplateInvocation, resolveExecutable?: CommandTemplateExecutableResolver): CommandTemplateInvocation;
 export declare function shouldRunCommandTemplateNode(value: boolean | string | undefined, values: Record<string, unknown>): boolean;
 export declare function substituteCommandTemplateToken(token: string, values: Record<string, unknown>, missingLabel?: string, depth?: number): string;
 export declare function execCommandTemplate(command: string, args: string[], options?: CommandTemplateExecOptions): Promise<CommandTemplateExecResult>;

package/dist/lib/command-templates.js

@@ -4,9 +4,9 @@
  * Owns portable command-template parsing, expansion, risk checks, retries, timeouts, and direct execution.
  */
 import { spawn } from "node:child_process";
-import { appendFileSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { accessSync, appendFileSync, constants, mkdirSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { isAbsolute, join, resolve as resolvePath } from "node:path";
+import { basename, delimiter, extname, isAbsolute, join, resolve as resolvePath } from "node:path";
 const DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES = 1024 * 1024;
 const COMMAND_TEMPLATE_RISK_LABEL_ORDER = [
     "risk.shell",
@@ -135,7 +135,7 @@ function getLeafCommandTemplateRiskLabels(config) {
     const command = getExecutableName(parts[0]);
     const args = parts.slice(1);
     const labels = new Set();
-    if (["bash", "sh", "zsh", "fish"].includes(command)) {
+    if (["bash", "sh", "zsh", "fish"].includes(command) || command.endsWith(".sh")) {
         labels.add("risk.shell");
         if (hasAnyFlag(args, ["-c"]))
             labels.add("risk.eval");
@@ -393,6 +393,40 @@ export function expandCommandTemplateExecutable(command, cwd) {
         return resolvePath(cwd, command);
     return command;
 }
+function resolveExecutableOnPath(name) {
+    if (name === "node" && /^node(?:\.exe)?$/i.test(basename(process.execPath)))
+        return process.execPath;
+    const pathValue = Object.entries(process.env)
+        .find(([key]) => key.toLowerCase() === "path")?.[1] ?? "";
+    const suffixes = process.platform === "win32" ? [".exe", ".com"] : [""];
+    for (const entry of pathValue.split(delimiter).filter(Boolean)) {
+        const directory = entry.replace(/^"|"$/g, "");
+        for (const suffix of suffixes) {
+            const candidate = join(directory, `${name}${suffix}`);
+            try {
+                accessSync(candidate, constants.X_OK);
+                if (statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch { }
+        }
+    }
+    return undefined;
+}
+export function resolveCommandTemplateScriptInvocation(invocation, resolveExecutable = resolveExecutableOnPath) {
+    const extension = extname(invocation.command).toLowerCase();
+    const interpreters = extension === ".js" || extension === ".mjs"
+        ? [["node"], ["bun"], ["deno", "run"]]
+        : extension === ".sh" ? [["bash"]] : [];
+    if (interpreters.length === 0)
+        return invocation;
+    for (const [name, ...prefix] of interpreters) {
+        const executable = resolveExecutable(name);
+        if (executable)
+            return { command: executable, args: [...prefix, invocation.command, ...invocation.args] };
+    }
+    throw new Error(`No interpreter available for command-template ${extension} script; tried ${interpreters.map(([name]) => name).join(", ")}.`);
+}
 function evaluateCommandTemplateExpression(expression, values) {
     let index = 0;
     const source = expression.replace(/\s+/g, "");
@@ -766,5 +800,5 @@ export function buildCommandTemplateInvocation(config, values, cwd, options = {}
         .slice(1)
         .map((part) => substituteCommandTemplateToken(part, resolvedValues, options.missingLabel))
         .filter((part) => part !== "");
-    return { command, args };
+    return resolveCommandTemplateScriptInvocation({ command, args });
 }

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

@@ -0,0 +1,20 @@
+/**
+ * Model-facing Run Control projection.
+ * Zones: structured redaction, bounded Control input/error, decision-useful evidence
+ * Owns safe Control reads; durable journals and lifecycle transitions remain in runs-controls.
+ */
+import type { RunControlRecord, RunControlStatus } from "./runs-controls.ts";
+export interface ProjectedRunControl {
+    action: string;
+    claimed_at?: string;
+    delivered_at?: string;
+    error?: string;
+    failed_at?: string;
+    handled_at?: string;
+    id: string;
+    input?: unknown;
+    queued_at: string;
+    run_instance_id: string;
+    status: RunControlStatus;
+}
+export declare function projectRunControl(control: RunControlRecord): ProjectedRunControl;

package/dist/lib/control-projection.js

@@ -0,0 +1,66 @@
+/**
+ * Model-facing Run Control projection.
+ * Zones: structured redaction, bounded Control input/error, decision-useful evidence
+ * Owns safe Control reads; durable journals and lifecycle transitions remain in runs-controls.
+ */
+import * as Limits from "./limits.js";
+import * as SessionEvidence from "./session-evidence.js";
+const OPTIONAL_TIMESTAMP_FIELDS = [
+    "claimed_at",
+    "delivered_at",
+    "failed_at",
+    "handled_at",
+];
+function boundedRedactedString(value, maxChars) {
+    const redacted = SessionEvidence.redactSessionEvidenceValue(value, maxChars);
+    return typeof redacted === "string"
+        ? redacted
+        : String(redacted).slice(0, maxChars);
+}
+function boundedRedactedValue(value) {
+    const redacted = SessionEvidence.redactSessionEvidenceValue(value, Limits.INSPECTOR_BODY_PREVIEW_CHARS);
+    let serialized;
+    try {
+        serialized = JSON.stringify(redacted);
+    }
+    catch {
+        return "[UNSERIALIZABLE]";
+    }
+    if (serialized === undefined)
+        return "[UNSERIALIZABLE]";
+    if (serialized.length <= Limits.INSPECTOR_BODY_PREVIEW_CHARS)
+        return redacted;
+    let preview = serialized.slice(0, Limits.INSPECTOR_BODY_PREVIEW_CHARS);
+    let bounded = { preview: `${preview}…`, truncated: true };
+    while (preview &&
+        JSON.stringify(bounded).length > Limits.INSPECTOR_BODY_PREVIEW_CHARS) {
+        const excess = JSON.stringify(bounded).length - Limits.INSPECTOR_BODY_PREVIEW_CHARS;
+        preview = preview.slice(0, Math.max(0, preview.length - Math.max(1, excess)));
+        bounded = { preview: `${preview}…`, truncated: true };
+    }
+    return bounded;
+}
+export function projectRunControl(control) {
+    const timestamps = Object.fromEntries(OPTIONAL_TIMESTAMP_FIELDS.flatMap((field) => {
+        const value = control[field];
+        return typeof value === "string"
+            ? [[field, boundedRedactedString(value, Limits.COMPACT_PREVIEW_CHARS)]]
+            : [];
+    }));
+    return {
+        action: boundedRedactedString(control.action, Limits.COMPACT_PREVIEW_CHARS),
+        ...timestamps,
+        ...(typeof control.error === "string"
+            ? {
+                error: boundedRedactedString(control.error, Limits.INSPECTOR_BODY_PREVIEW_CHARS),
+            }
+            : {}),
+        id: boundedRedactedString(control.id, Limits.COMPACT_PREVIEW_CHARS),
+        ...(control.input !== undefined
+            ? { input: boundedRedactedValue(control.input) }
+            : {}),
+        queued_at: boundedRedactedString(control.queued_at, Limits.COMPACT_PREVIEW_CHARS),
+        run_instance_id: boundedRedactedString(control.run_instance_id, Limits.COMPACT_PREVIEW_CHARS),
+        status: boundedRedactedString(control.status, Limits.COMPACT_PREVIEW_CHARS),
+    };
+}

package/dist/lib/control.d.ts

@@ -9,4 +9,7 @@ export interface ControlRequest {
     input?: unknown;
     verbose?: boolean;
 }
+export declare function isControlAction(value: string): boolean;
+export declare function normalizeControlAction(value: unknown): string;
+export declare function normalizeControlInput(input: unknown): unknown;
 export declare function normalizeControlRequest(input: unknown): ControlRequest;

package/dist/lib/control.js

@@ -17,7 +17,23 @@ const REMOVED_FIELDS = new Set([
     "to",
     "type",
 ]);
-function serializedInputBytes(input) {
+export function isControlAction(value) {
+    return ACTION_PATTERN.test(value);
+}
+export function normalizeControlAction(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error("control.action is required");
+    }
+    const action = value.trim();
+    if (!isControlAction(action)) {
+        throw new Error(`invalid control action: ${action}`);
+    }
+    if (action.length > Limits.CONTROL_ACTION_MAX_LENGTH) {
+        throw new Error(`control.action exceeds ${Limits.CONTROL_ACTION_MAX_LENGTH} ASCII characters`);
+    }
+    return action;
+}
+export function normalizeControlInput(input) {
     let serialized;
     try {
         serialized = JSON.stringify(input);
@@ -28,7 +44,11 @@ function serializedInputBytes(input) {
     if (serialized === undefined) {
         throw new Error("control.input must be JSON-serializable");
     }
-    return Buffer.byteLength(serialized);
+    const bytes = Buffer.byteLength(serialized);
+    if (bytes > Limits.CONTROL_INPUT_MAX_BYTES) {
+        throw new Error(`control.input exceeds ${Limits.CONTROL_INPUT_MAX_BYTES} serialized bytes`);
+    }
+    return JSON.parse(serialized);
 }
 function normalizeTarget(value) {
     if (typeof value !== "string" || !value.trim()) {
@@ -61,24 +81,17 @@ export function normalizeControlRequest(input) {
         throw new Error(`unsupported control fields: ${unknown.sort().join(", ")}`);
     }
     const target = normalizeTarget(record.target);
-    if (typeof record.action !== "string" || !record.action.trim()) {
-        throw new Error("control.action is required");
-    }
-    const action = record.action.trim();
-    if (!ACTION_PATTERN.test(action)) {
-        throw new Error(`invalid control action: ${action}`);
-    }
+    const action = normalizeControlAction(record.action);
     if (record.verbose !== undefined && typeof record.verbose !== "boolean") {
         throw new Error("control.verbose must be a boolean");
     }
-    if (record.input !== undefined &&
-        serializedInputBytes(record.input) > Limits.CONTROL_INPUT_MAX_BYTES) {
-        throw new Error(`control.input exceeds ${Limits.CONTROL_INPUT_MAX_BYTES} bytes`);
-    }
+    const normalizedInput = record.input === undefined
+        ? undefined
+        : normalizeControlInput(record.input);
     return {
         target,
         action,
-        ...(record.input !== undefined ? { input: record.input } : {}),
+        ...(normalizedInput !== undefined ? { input: normalizedInput } : {}),
         ...(record.verbose !== undefined ? { verbose: record.verbose } : {}),
     };
 }

package/dist/lib/draft-sleep.js

@@ -391,7 +391,7 @@ export function createDraftSleepScheduler(deps) {
                                 ...existing,
                                 failedStage: processed.stage ?? "result_processing",
                                 lastError: processed.error ?? "automatic draft review processing failed",
-                                nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+                                nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
                                 phase: "processing_failed",
                                 processingAttempts: (existing.processingAttempts ?? 0) + 1,
                                 updatedAt: now().toISOString(),
@@ -402,7 +402,7 @@ export function createDraftSleepScheduler(deps) {
                             ...existing,
                             failedStage: processed.stage ?? "review_result",
                             lastError: processed.error ?? "automatic draft reviewer failed",
-                            nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+                            nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
                             phase: "failed",
                             runId: undefined,
                             updatedAt: now().toISOString(),
@@ -444,7 +444,7 @@ export function createDraftSleepScheduler(deps) {
                             attempts: (prior?.batchId === batch.batchId ? prior.attempts : 0) + 1,
                             failedStage: "review_launch",
                             lastError: error instanceof Error ? error.message : String(error),
-                            nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+                            nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
                             batchId: batch.batchId,
                             inputPath: batch.inputPath,
                             phase: "failed",

package/dist/lib/file-state.d.ts

@@ -5,11 +5,14 @@
  */
 export declare function mutationLockPath(path: string): string;
 export interface FileMutationLockOptions {
+    onBeforeLockPublish?(): void;
     onBeforeReclaimRemove?(): void;
     onContention?(): void;
     onRemovalContention?(): void;
 }
 export declare function acquireFileMutationLock(path: string, options?: FileMutationLockOptions): () => void;
 export declare function withFileMutationLock<T>(path: string, mutate: () => T, options?: FileMutationLockOptions): T;
-export declare function writeTextAtomic(path: string, content: string): void;
+export declare function writeTextAtomic(path: string, content: string, options?: {
+    onBeforeReplace?(): void;
+}): void;
 export declare function writeJsonAtomic(path: string, value: unknown): void;