@llblab/pi-actors 0.42.3 → 0.43.1

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

@@ -6,22 +6,21 @@ import type { CommandTemplateFailureScope, CommandTemplateValue } from "./comman
 import { type CurrentPolicyProvenance } from "./model-context.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import { type RunArtifactDeclaration } from "./runs-artifacts.ts";
-import { type RunOutboxEvent } from "./runs-outbox.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 ProcessRunInboxResult, type RunInboxMessage, type RunInboxStatus } from "./runs-mailbox.ts";
-import { type SendRunMessageOptions } from "./runs-messages.ts";
+import { type DeliverRunControlOptions, type DeliverRunControlRequest } from "./runs-control-delivery.ts";
 import { type AsyncRunStatus } from "./runs-status.ts";
 export type AsyncRunLaunchSource = "spawn" | "tool";
 export interface AsyncRunControlEndpoint {
     path: string;
-    type: "fifo" | "mailbox" | "named-pipe";
+    type: "fifo" | "named-pipe";
 }
 export declare function normalizeRunTransportContext(value: unknown): Record<string, string | number | boolean> | undefined;
 export interface AsyncRunStartParams {
     async?: boolean;
-    control?: AsyncRunControlEndpoint;
+    control_endpoint?: AsyncRunControlEndpoint;
     file?: string;
     launch_source?: AsyncRunLaunchSource;
     lifecycleHooks?: {
@@ -49,7 +48,7 @@ export interface AsyncRunStartParams {
     accept_output?: "review_evidence";
     output?: string;
     artifacts?: Record<string, RunArtifactDeclaration>;
-    mailbox?: RecipesReferences.TemplateRecipeMailbox;
+    control?: string[];
     notification_policy?: "normal" | "silent";
     retire_when?: "children_terminal";
     retry?: number | string;
@@ -79,13 +78,14 @@ export interface AsyncRunMeta {
     run: string;
     run_instance_id: string;
     state_dir: string;
+    state_schema: typeof RuntimeIdentity.RUN_STATE_SCHEMA;
     status: AsyncRunStatus;
     tool?: string;
     template: CommandTemplateValue;
     values: Record<string, unknown>;
     artifacts?: Record<string, RunArtifactDeclaration>;
-    control?: AsyncRunControlEndpoint;
-    mailbox?: RecipesReferences.TemplateRecipeMailbox;
+    control?: string[];
+    control_endpoint?: AsyncRunControlEndpoint;
     model_policy?: CurrentPolicyProvenance;
     notification_policy?: "normal" | "silent";
     process_identity?: RunProcessIdentity;
@@ -97,8 +97,6 @@ export { safeRunId } from "./runs-identity.ts";
 export { resolveArtifactManifest } from "./runs-artifacts.ts";
 export type { RunArtifactDeclaration, RunArtifactManifestEntry, } from "./runs-artifacts.ts";
 export declare function startRun(params: AsyncRunStartParams, cwd: string): AsyncRunMeta;
-export { parseRunOutboxEventLine } from "./runs-outbox.ts";
-export type { RunOutboxDelivery, RunOutboxEvent, RunOutboxLevel, } from "./runs-outbox.ts";
 export declare function getRunStatus(runOrDir: string): Record<string, unknown>;
 export type { RunStateIndexEntry } from "./runs-index.ts";
 export declare function listRunStateDirs(stateRoot?: string): string[];
@@ -113,32 +111,11 @@ export declare function teardownRunsOwnedByParent(ownerId: string | undefined, s
     trigger?: string;
 }): ParentRunsTeardownSummaryResult;
 export declare function tailRun(runOrDir: string, lines?: number): string;
-export declare function readRunEvents(runOrDir: string, lines?: number): RunOutboxEvent[];
-export type { ProcessRunInboxResult, RunInboxMessage, RunInboxStatus, } from "./runs-mailbox.ts";
-export declare function readRunInboxMessages(runOrDir: string, lines?: number): RunInboxMessage[];
-export declare function updateRunInboxMessageStatus(runOrDir: string, id: string, nextStatus: RunInboxStatus, metadata?: Record<string, unknown>): boolean;
-export declare function claimRunInboxMessage(runOrDir: string, owner?: string, statuses?: string[]): RunInboxMessage | undefined;
-export declare function processRunInboxMessages(runOrDir: string, handler: (message: RunInboxMessage) => Promise<void> | void, options?: {
-    limit?: number;
-    owner?: string;
-    statuses?: string[];
-}): Promise<ProcessRunInboxResult>;
-export declare function appendRunOutboxEvent(runOrDir: string, event: {
-    body?: unknown;
-    correlation_id?: string;
-    data?: unknown;
-    delivery?: string;
-    event?: string;
-    from?: string;
-    level?: string;
-    metadata?: Record<string, unknown>;
-    reply_to?: string;
-    summary?: string;
-    to?: string;
-    type?: string;
-}): Record<string, unknown>;
-export type { SendRunMessageOptions } from "./runs-messages.ts";
-export declare function sendRunMessage(runOrDir: string, message: string, options?: SendRunMessageOptions): Promise<Record<string, unknown>>;
+export type { DeliverRunControlOptions, DeliverRunControlRequest, } from "./runs-control-delivery.ts";
+export interface SendRunControlOptions extends DeliverRunControlOptions {
+    ownerId?: string;
+}
+export declare function sendRunControl(runOrDir: string, request: DeliverRunControlRequest, options?: SendRunControlOptions): Promise<Record<string, unknown>>;
 export { getRunProcessSignalPlan } from "./runs-control.ts";
 export type { RunProcessSignalPlan } from "./runs-control.ts";
 export interface RunControlExpectation {
@@ -149,8 +126,8 @@ export interface RunControlExpectation {
 export declare function markRunTerminalNotificationHandled(stateDir: string, status: string): void;
 export declare function recordRunTerminalDeliveryFailure(stateDir: string, status: string, error: unknown): void;
 export declare function cancelRun(runOrDir: string, expected?: RunControlExpectation): Record<string, unknown>;
-export declare function archiveRun(runOrDir: string): Record<string, unknown>;
+export declare function archiveRun(runOrDir: string, expected?: RunControlExpectation): Record<string, unknown>;
 export declare function pruneRun(runOrDir: string, options?: {
     preserveArtifacts?: boolean;
-}): Record<string, unknown>;
+}, expected?: RunControlExpectation): Record<string, unknown>;
 export declare function killRun(runOrDir: string, expected?: RunControlExpectation): Record<string, unknown>;

package/dist/lib/async-runs.js

@@ -4,7 +4,7 @@
  */
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeJsonAtomic } from "./file-state.js";
@@ -15,16 +15,17 @@ import * as RecipesUsage from "./recipes-usage.js";
 import { resolveArtifactPaths, } from "./runs-artifacts.js";
 import { safeRunId } from "./runs-identity.js";
 import { buildTerminalProgress, markTerminalHandled, signalOwnedRunProcess, } from "./runs-control.js";
-import { buildRunOutboxEventPayload, parseRunOutboxEventLine, } from "./runs-outbox.js";
 import { claimRunStateDirectory } from "./runs-ownership.js";
-import { archiveTerminalRun, pruneTerminalRun } from "./runs-retention.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 { claimRunInboxMessageInStateDir, parseRunInboxLine, processRunInboxMessagesInStateDir, runInboxFile, updateRunInboxMessageStatusInStateDir, } from "./runs-mailbox.js";
-import { deliverRunMessage, } from "./runs-messages.js";
-import { buildRunStatus, tailFile, tailLines, } from "./runs-status.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";
 const RUNNER_IDENTITY_GRACE_MS = 5000;
 export function normalizeRunTransportContext(value) {
@@ -236,13 +237,25 @@ 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 || {}),
-        actor_address: `run:${run}`,
-        communication_file: join(stateDir, "communication.json"),
-        default_room: `room:${run}`,
         run_id: run,
         state_dir: stateDir,
+        trace_file: join(stateDir, "trace.jsonl"),
     };
     const modelPolicy = describeCurrentPolicyProvenance({
         defaults: startParams.defaults,
@@ -261,9 +274,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";
@@ -300,6 +310,7 @@ export function startRun(params, cwd) {
             run,
             run_instance_id: randomUUID(),
             state_dir: stateDir,
+            state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
             status: "running",
             ...(startParams.tool ? { tool: startParams.tool } : {}),
             template: resolved.template,
@@ -307,7 +318,9 @@ export function startRun(params, cwd) {
             model_policy: modelPolicy,
             ...(artifacts ? { artifacts } : {}),
             ...(startParams.control ? { control: startParams.control } : {}),
-            ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
+            ...(startParams.control_endpoint
+                ? { control_endpoint: startParams.control_endpoint }
+                : {}),
             ...(startParams.notification_policy === "silent"
                 ? { notification_policy: "silent" }
                 : {}),
@@ -340,7 +353,14 @@ export function startRun(params, cwd) {
         if (processIdentity)
             meta.process_identity = processIdentity;
         writeJsonAtomic(join(stateDir, "run.json"), meta);
-        writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event: "run.start", run, run_instance_id: meta.run_instance_id, pid: meta.pid, ts: new Date().toISOString() })}\n`, { flag: "a" });
+        appendRunTraceEvent(stateDir, {
+            kind: "run.start",
+            summary: `Run ${run} started`,
+            data: {
+                pid: meta.pid,
+                run_instance_id: meta.run_instance_id,
+            },
+        });
         child.unref();
         return meta;
     }
@@ -348,7 +368,6 @@ export function startRun(params, cwd) {
         releaseStartLock();
     }
 }
-export { parseRunOutboxEventLine } from "./runs-outbox.js";
 function resolveRunStateDir(runOrDir) {
     return resolve(/[\\/]/u.test(runOrDir)
         ? runOrDir
@@ -403,17 +422,19 @@ export function teardownRunsOwnedByParent(ownerId, stateRoot = DEFAULT_STATE_ROO
                 current.run_instance_id !== attempt.runInstanceId) {
                 throw new Error("run generation changed before teardown evidence");
             }
-            writeFileSync(join(attempt.stateDir, "events.jsonl"), `${JSON.stringify({
-                event: "run.parent_teardown",
-                ownerId: attempt.ownerId,
-                outcome: attempt.outcome,
-                reason: attempt.reason,
-                run: attempt.run,
-                run_instance_id: attempt.runInstanceId,
-                type: "control.kill",
-                trigger: options.trigger ?? "parent_shutdown",
-                ts: new Date().toISOString(),
-            })}\n`, { flag: "a" });
+            appendRunTraceEvent(attempt.stateDir, {
+                kind: "run.parent_teardown",
+                summary: `Parent teardown ${attempt.outcome}`,
+                data: {
+                    outcome: attempt.outcome,
+                    owner_id: attempt.ownerId,
+                    reason: attempt.reason,
+                    run: attempt.run,
+                    run_instance_id: attempt.runInstanceId,
+                    trigger: options.trigger ?? "parent_shutdown",
+                },
+                ...(attempt.outcome === "failed" ? { level: "error" } : {}),
+            });
         },
     });
     const summaryPath = join(stateRoot, "teardown", `${Date.now()}-${randomUUID()}.json`);
@@ -437,73 +458,43 @@ export function teardownRunsOwnedByParent(ownerId, stateRoot = DEFAULT_STATE_ROO
 export function tailRun(runOrDir, lines = 40) {
     const status = getRunStatus(runOrDir);
     const stateDir = String(status.state_dir);
-    const events = tailFile(join(stateDir, "events.jsonl"), lines);
-    if (events)
-        return events;
+    const trace = tailFile(join(stateDir, "trace.jsonl"), lines);
+    if (trace)
+        return trace;
     return (tailFile(join(stateDir, "stdout.log"), lines) ||
         tailFile(join(stateDir, "stderr.log"), lines));
 }
-export function readRunEvents(runOrDir, lines = 40) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    const run = String(status.run ?? runOrDir);
-    return tailLines(join(stateDir, "outbox.jsonl"), lines)
-        .map((line, index) => parseRunOutboxEventLine(line, run, stateDir, index))
-        .filter((event) => Boolean(event));
-}
-export function readRunInboxMessages(runOrDir, lines = 40) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    return tailLines(runInboxFile(stateDir), lines)
-        .map(parseRunInboxLine)
-        .filter((message) => Boolean(message));
-}
-export function updateRunInboxMessageStatus(runOrDir, id, nextStatus, metadata = {}) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    return updateRunInboxMessageStatusInStateDir(stateDir, id, nextStatus, metadata);
-}
-export function claimRunInboxMessage(runOrDir, owner = "runtime", statuses = ["queued"]) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    return claimRunInboxMessageInStateDir(stateDir, owner, statuses);
-}
-export async function processRunInboxMessages(runOrDir, handler, options = {}) {
-    const status = getRunStatus(runOrDir);
-    return processRunInboxMessagesInStateDir(String(status.state_dir), handler, options);
-}
-export function appendRunOutboxEvent(runOrDir, event) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    const run = String(status.run ?? runOrDir);
-    const payload = buildRunOutboxEventPayload(run, event);
-    const line = `${JSON.stringify(payload)}\n`;
-    writeFileSync(join(stateDir, "outbox.jsonl"), line, { flag: "a" });
-    return {
-        bytes: Buffer.byteLength(line),
-        outbox: "outbox.jsonl",
-        run,
-        sent: true,
-        state_dir: stateDir,
-    };
-}
-export async function sendRunMessage(runOrDir, message, options = {}) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    const run = String(status.run ?? runOrDir);
-    const pid = Number(status.pid || 0);
-    const identity = verifyRunProcessIdentity(pid, status.process_identity);
-    if (status.status !== "running") {
-        if (identity.status === "owner_mismatch" ||
-            identity.status === "unsupported_proof") {
-            throw new Error(`Run process identity ${identity.status}: ${run}`);
+export async function sendRunControl(runOrDir, request, options = {}) {
+    const stateDir = resolveRunStateDir(runOrDir);
+    const releaseControlLock = RunsStart.acquireStateStartLock(stateDir);
+    try {
+        const status = getRunStatus(stateDir);
+        const run = String(status.run ?? runOrDir);
+        if (options.ownerId !== undefined && status.ownerId !== options.ownerId) {
+            throw Object.assign(new Error(`Run ownership changed: ${run}`), {
+                reason: "owner_mismatch",
+            });
+        }
+        if (status.run_instance_id !== request.run_instance_id) {
+            throw Object.assign(new Error(`Run generation changed: ${run}`), {
+                reason: "generation_mismatch",
+            });
+        }
+        if (status.status !== "running") {
+            throw Object.assign(new Error(`Run is not running: ${run}`), {
+                reason: "terminal_state",
+            });
         }
-        throw new Error(`Run is not running: ${run}`);
+        const pid = Number(status.pid || 0);
+        const identity = verifyRunProcessIdentity(pid, status.process_identity);
+        if (!identity.valid) {
+            throw Object.assign(new Error(`Run process identity ${identity.status}: ${run}`), { reason: `process_identity_${identity.status}` });
+        }
+        return await deliverRunControl(run, stateDir, request, options);
     }
-    if (!identity.valid) {
-        throw new Error(`Run process identity ${identity.status}: ${run}`);
+    finally {
+        releaseControlLock();
     }
-    return deliverRunMessage(status, run, stateDir, message, options);
 }
 export { getRunProcessSignalPlan } from "./runs-control.js";
 function markTerminalProgress(stateDir, phase) {
@@ -513,9 +504,9 @@ function markTerminalProgress(stateDir, phase) {
         : undefined;
     writeJsonAtomic(join(stateDir, "progress.json"), buildTerminalProgress(progress, phase));
 }
-function finalizeInterruptedReviewEvidence(stateDir, phase, signal) {
-    const evidencePath = join(stateDir, "review-evidence.json");
-    const manifest = readJson(evidencePath);
+function finalizeInterruptedExecution(stateDir, phase, signal) {
+    const executionPath = join(stateDir, "execution.json");
+    const manifest = readJson(executionPath);
     if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
         return;
     const record = manifest;
@@ -564,7 +555,7 @@ function finalizeInterruptedReviewEvidence(stateDir, phase, signal) {
                 : {}),
         };
     });
-    writeJsonAtomic(evidencePath, {
+    writeJsonAtomic(executionPath, {
         ...record,
         status: phase,
         commands,
@@ -585,43 +576,80 @@ 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 { stopped: false, reason: "not running", status };
+            return finish({ 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 {
+                return finish({
                     stopped: false,
                     reason: identity.status.replaceAll("_", " "),
                     process_identity_status: identity.status,
                     status,
-                };
+                });
             }
-            return { stopped: false, reason: "not running", status };
+            return finish({ stopped: false, reason: "not running", status });
         }
         if (!identity.valid) {
-            return {
+            return finish({
                 stopped: false,
                 reason: identity.status.replaceAll("_", " "),
                 process_identity_status: identity.status,
                 status,
-            };
+            });
         }
-        const signalResult = signalOwnedRunProcess(pid, signal, status.process_identity);
-        writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event, pid, signal, ...signalResult, ts: new Date().toISOString() })}\n`, { flag: "a" });
+        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, {
+            kind: event,
+            summary: `${event === "run.kill" ? "Killed" : "Cancelled"} Run process`,
+            data: { pid, signal, ...signalResult },
+        });
         markTerminalHandled(stateDir, { event, signal });
         if (event === "run.kill") {
-            finalizeInterruptedReviewEvidence(stateDir, "killed", signal);
+            finalizeInterruptedExecution(stateDir, "killed", signal);
             markTerminalProgress(stateDir, "killed");
         }
         if (event === "run.cancel") {
-            finalizeInterruptedReviewEvidence(stateDir, "cancelled", signal);
+            finalizeInterruptedExecution(stateDir, "cancelled", signal);
             markTerminalProgress(stateDir, "cancelled");
         }
-        return { stopped: true, pid, signal, ...signalResult, state_dir: stateDir };
+        return finish({
+            stopped: true,
+            pid,
+            signal,
+            ...signalResult,
+            state_dir: stateDir,
+        });
     }
     finally {
         releaseControlLock();
@@ -653,18 +681,52 @@ export function cancelRun(runOrDir, expected = {}) {
         ? { cancelled: result.stopped, ...result }
         : result;
 }
-function assertTerminalRun(runOrDir) {
-    const status = getRunStatus(runOrDir);
-    if (status.status === "running") {
-        throw new Error("Only terminal runs can be archived or pruned.");
+function retainRun(runOrDir, action, expected, options = {}) {
+    const stateDir = resolveRunStateDir(runOrDir);
+    const releaseControlLock = RunsStart.acquireStateStartLock(stateDir);
+    let status;
+    let evidenceId;
+    try {
+        expected.onLocked?.();
+        status = getRunStatus(stateDir);
+        if (expected.ownerId !== undefined && status.ownerId !== expected.ownerId) {
+            return { [`${action}d`]: false, reason: "ownership changed", status };
+        }
+        if (expected.runInstanceId !== undefined &&
+            status.run_instance_id !== expected.runInstanceId) {
+            return { [`${action}d`]: false, reason: "run generation changed", status };
+        }
+        if (status.status === "running") {
+            throw new Error("Only terminal runs can be archived or pruned.");
+        }
+        evidenceId = appendRunRetentionEvidence(status, action, "queued");
+        const result = action === "archive"
+            ? archiveTerminalRun(status)
+            : pruneTerminalRun(status, options);
+        appendRunRetentionEvidence(status, action, "handled", {
+            id: evidenceId,
+            result,
+        });
+        return { ...result, retention_id: evidenceId };
+    }
+    catch (error) {
+        if (status && evidenceId) {
+            appendRunRetentionEvidence(status, action, "failed", {
+                error: error instanceof Error ? error.message : String(error),
+                id: evidenceId,
+            });
+        }
+        throw error;
+    }
+    finally {
+        releaseControlLock();
     }
-    return status;
 }
-export function archiveRun(runOrDir) {
-    return archiveTerminalRun(assertTerminalRun(runOrDir));
+export function archiveRun(runOrDir, expected = {}) {
+    return retainRun(runOrDir, "archive", expected);
 }
-export function pruneRun(runOrDir, options = {}) {
-    return pruneTerminalRun(assertTerminalRun(runOrDir), options);
+export function pruneRun(runOrDir, options = {}, expected = {}) {
+    return retainRun(runOrDir, "prune", expected, options);
 }
 export function killRun(runOrDir, expected = {}) {
     const result = stopRun(runOrDir, "SIGKILL", "run.kill", expected);

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 });
 }