@llblab/pi-actors 0.39.0 → 0.40.1

package/dist/lib/command-templates.js

@@ -4,8 +4,10 @@
  * Owns portable command-template parsing, expansion, risk checks, retries, timeouts, and direct execution.
  */
 import { spawn } from "node:child_process";
-import { homedir } from "node:os";
-import { isAbsolute, resolve } from "node:path";
+import { appendFileSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join, resolve as resolvePath } from "node:path";
+const DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES = 1024 * 1024;
 const COMMAND_TEMPLATE_RISK_LABEL_ORDER = [
     "risk.shell",
     "risk.eval",
@@ -386,9 +388,9 @@ export function expandCommandTemplateExecutable(command, cwd) {
     if (command === "~")
         return homedir();
     if (command.startsWith("~/"))
-        return resolve(homedir(), command.slice(2));
+        return resolvePath(homedir(), command.slice(2));
     if (command.includes("/") && !isAbsolute(command))
-        return resolve(cwd, command);
+        return resolvePath(cwd, command);
     return command;
 }
 function evaluateCommandTemplateExpression(expression, values) {
@@ -592,13 +594,67 @@ export async function execCommandTemplate(command, args, options = {}) {
         killed: false,
     };
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        const result = await execCommandTemplateOnce(command, args, options);
+        const attemptOptions = options.captureDir
+            ? {
+                ...options,
+                captureDir: join(options.captureDir, `attempt-${String(attempt).padStart(3, "0")}`),
+            }
+            : options;
+        const result = await execCommandTemplateOnce(command, args, attemptOptions);
         if (result.code === 0)
             return result;
         lastResult = result;
     }
     return lastResult;
 }
+function trimCaptureTail(value, limit) {
+    if (value.length <= limit)
+        return value;
+    let start = value.length - limit;
+    while (start < value.length && (value[start] & 0xc0) === 0x80)
+        start += 1;
+    return value.subarray(start);
+}
+function createBoundedCommandCapture(stream, limit, getCaptureDir, persistCompleteStream) {
+    let bytes = 0;
+    let content = Buffer.alloc(0);
+    let file = persistCompleteStream
+        ? join(getCaptureDir(), `${stream}.log`)
+        : undefined;
+    if (file)
+        writeFileSync(file, Buffer.alloc(0));
+    let truncated = false;
+    return {
+        append(value) {
+            const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            bytes += chunk.length;
+            if (bytes > limit)
+                truncated = true;
+            if (!file && bytes <= limit) {
+                content = Buffer.concat([content, chunk]);
+                return;
+            }
+            if (!file) {
+                file = join(getCaptureDir(), `${stream}.log`);
+                writeFileSync(file, content);
+            }
+            appendFileSync(file, chunk);
+            content = trimCaptureTail(Buffer.concat([content, chunk]), limit);
+        },
+        result() {
+            if (!file && persistCompleteStream) {
+                file = join(getCaptureDir(), `${stream}.log`);
+                writeFileSync(file, content);
+            }
+            return {
+                bytes,
+                content: content.toString("utf8"),
+                ...(file ? { file } : {}),
+                truncated,
+            };
+        },
+    };
+}
 function execCommandTemplateOnce(command, args, options = {}) {
     return new Promise((resolve) => {
         const proc = spawn(command, args, {
@@ -606,8 +662,20 @@ function execCommandTemplateOnce(command, args, options = {}) {
             shell: false,
             stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
         });
-        let stdout = "";
-        let stderr = "";
+        const captureLimit = Math.max(1, options.captureLimitBytes ?? DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES);
+        let captureDir;
+        const getCaptureDir = () => {
+            if (captureDir)
+                return captureDir;
+            captureDir = options.captureDir
+                ? resolvePath(options.captureDir)
+                : mkdtempSync(join(tmpdir(), "pi-actors-command-"));
+            mkdirSync(captureDir, { recursive: true });
+            return captureDir;
+        };
+        const persistCompleteStreams = options.captureDir !== undefined;
+        const stdoutCapture = createBoundedCommandCapture("stdout", captureLimit, getCaptureDir, persistCompleteStreams);
+        const stderrCapture = createBoundedCommandCapture("stderr", captureLimit, getCaptureDir, persistCompleteStreams);
         let killed = false;
         let settled = false;
         let timeoutId;
@@ -632,7 +700,20 @@ function execCommandTemplateOnce(command, args, options = {}) {
                 clearTimeout(killTimeoutId);
             if (options.signal)
                 options.signal.removeEventListener("abort", killProcess);
-            resolve({ stdout, stderr, code, killed });
+            const stdout = stdoutCapture.result();
+            const stderr = stderrCapture.result();
+            resolve({
+                stdout: stdout.content,
+                stderr: stderr.content,
+                code,
+                killed,
+                stdoutBytes: stdout.bytes,
+                stderrBytes: stderr.bytes,
+                ...(stdout.file ? { stdoutFile: stdout.file } : {}),
+                ...(stderr.file ? { stderrFile: stderr.file } : {}),
+                ...(stdout.truncated ? { stdoutTruncated: true } : {}),
+                ...(stderr.truncated ? { stderrTruncated: true } : {}),
+            });
         };
         if (options.signal) {
             if (options.signal.aborted)
@@ -643,16 +724,16 @@ function execCommandTemplateOnce(command, args, options = {}) {
         if (options.timeout !== undefined && options.timeout > 0)
             timeoutId = setTimeout(killProcess, options.timeout);
         proc.stdout?.on("data", (data) => {
-            stdout += data.toString();
+            stdoutCapture.append(data);
         });
         proc.stderr?.on("data", (data) => {
-            stderr += data.toString();
+            stderrCapture.append(data);
         });
         proc.stdin?.on("error", () => { });
         if (options.stdin !== undefined)
             proc.stdin?.end(options.stdin);
         proc.on("error", (error) => {
-            stderr += error instanceof Error ? error.message : String(error);
+            stderrCapture.append(error instanceof Error ? error.message : String(error));
             settle(1);
         });
         proc.on("close", (code) => {

package/dist/lib/config.js

@@ -24,8 +24,6 @@ export function serializeTools(source) {
             entry.name = cfg.recipe.name;
         if (cfg.recipe?.async !== undefined)
             entry.async = cfg.recipe.async;
-        if (cfg.recipe?.state_dir)
-            entry.state_dir = cfg.recipe.state_dir;
         if (cfg.recipe?.values)
             entry.values = cfg.recipe.values;
         if (cfg.template)
@@ -113,9 +111,6 @@ export function normalizeStoredTool(key, value, reservedToolNames) {
         ? {
             name: recipeName,
             ...(typeof record.async === "boolean" ? { async: record.async } : {}),
-            ...(typeof record.state_dir === "string" && record.state_dir.trim()
-                ? { state_dir: record.state_dir.trim() }
-                : {}),
             template,
             ...(record.values &&
                 typeof record.values === "object" &&

package/dist/lib/execution.d.ts

@@ -7,17 +7,33 @@ import * as CommandTemplates from "./command-templates.ts";
 import type { RegisteredTool } from "./config.ts";
 export interface ToolExecOptions {
     actorRecipeContext?: CommandTemplates.CommandTemplateActorRecipeContext;
+    evidenceContext?: {
+        acceptOutput?: "review_evidence";
+        label?: string;
+        repeatIndex?: string;
+    };
     cwd?: string;
     signal?: AbortSignal;
     stdin?: string;
     timeout?: number;
     retry?: number;
+    captureDir?: string;
+    captureLimitBytes?: number;
 }
 export interface ToolExecResult {
     stdout: string;
     stderr: string;
     code: number;
     killed: boolean;
+    stdoutBytes?: number;
+    stderrBytes?: number;
+    stdoutFile?: string;
+    stderrFile?: string;
+    evidenceRef?: string;
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
+    /** Complete internal stdout for downstream pipeline stdin; never returned to model-facing output. */
+    pipelineStdout?: string;
 }
 export interface BranchReport {
     code: number;
@@ -28,8 +44,14 @@ export interface BranchReport {
     status: "done" | "failed" | "timeout";
     stderr?: string;
     stderrBytes: number;
+    stderrCapturedBytes: number;
+    stderrFile?: string;
+    stderrTruncated?: boolean;
     stdout?: string;
     stdoutBytes: number;
+    stdoutCapturedBytes: number;
+    stdoutFile?: string;
+    stdoutTruncated?: boolean;
 }
 export interface SoftQuorumReport {
     coverage: number;
@@ -50,6 +72,14 @@ export interface RegisteredToolExecutionResult {
         command: string;
         fullOutputPath?: string;
         killed: boolean;
+        stderrBytes?: number;
+        stderrCapturedBytes?: number;
+        stderrFile?: string;
+        stderrTruncated?: boolean;
+        stdoutBytes?: number;
+        stdoutCapturedBytes?: number;
+        stdoutFile?: string;
+        stdoutTruncated?: boolean;
         nonCriticalFailures?: Array<{
             code: number;
             command: string;
@@ -64,4 +94,5 @@ export interface RegisteredToolExecutionResult {
     };
 }
 export type RegisteredToolExec = (command: string, args: string[], options?: ToolExecOptions) => Promise<ToolExecResult>;
+export declare function applyOutputAcceptancePolicy(result: ToolExecResult, output: string | undefined): Promise<ToolExecResult>;
 export declare function executeRegisteredTool(cfg: RegisteredTool, params: Record<string, unknown>, exec: RegisteredToolExec, cwd: string, signal?: AbortSignal): Promise<RegisteredToolExecutionResult>;

package/dist/lib/execution.js

@@ -3,6 +3,7 @@
  * Zones: tool execution, command templates, output formatting
  * Owns command-template invocation execution and pi tool-result payload formatting
  */
+import { readFile } from "node:fs/promises";
 import * as CommandTemplates from "./command-templates.js";
 import { formatFailureOutput, formatOutput, formatToolText, } from "./execution-output.js";
 import * as Schema from "./schema.js";
@@ -62,6 +63,63 @@ function getBranchStatus(result) {
         return "done";
     return result.killed ? "timeout" : "failed";
 }
+const REVIEW_RESULT_MARKER = "ACTOR_REVIEW_RESULT";
+export async function applyOutputAcceptancePolicy(result, output) {
+    if (result.code !== 0 || output !== "review_evidence")
+        return result;
+    let semanticStdout = result.pipelineStdout ?? result.stdout;
+    if (result.pipelineStdout === undefined && result.stdoutTruncated) {
+        if (!result.stdoutFile)
+            semanticStdout = "";
+        else {
+            try {
+                semanticStdout = await readFile(result.stdoutFile, "utf8");
+            }
+            catch {
+                semanticStdout = "";
+            }
+        }
+    }
+    const firstNonWhitespaceLine = semanticStdout
+        .split(/\r?\n/)
+        .find((line) => line.trim().length > 0);
+    if (firstNonWhitespaceLine?.trim() === REVIEW_RESULT_MARKER)
+        return result;
+    return {
+        ...result,
+        code: 65,
+        stderr: [
+            result.stderr,
+            `review evidence rejected: missing ${REVIEW_RESULT_MARKER} marker`,
+        ].filter(Boolean).join("\n"),
+    };
+}
+async function resolvePipelineStdout(result) {
+    let stdout = result.pipelineStdout ?? result.stdout;
+    if (result.pipelineStdout === undefined && result.stdoutTruncated) {
+        if (!result.stdoutFile)
+            return undefined;
+        try {
+            stdout = await readFile(result.stdoutFile, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return result.evidenceRef
+        ? `${stdout}\nACTOR_EVIDENCE_REF: ${result.evidenceRef}`
+        : stdout;
+}
+function rejectIncompletePipelineOutput(result) {
+    return {
+        ...result,
+        code: 74,
+        stderr: [
+            result.stderr,
+            `incomplete pipeline stdin: complete stdout unavailable${result.stdoutFile ? `; capture path unreadable: ${result.stdoutFile}` : ""}`,
+        ].filter(Boolean).join("\n"),
+    };
+}
 function getBranchFailureReason(result) {
     if (result.code === 0) {
         return result.stdout.trim() ? undefined : "empty_output";
@@ -80,13 +138,21 @@ function createBranchReport(label, command, result) {
         label,
         status: getBranchStatus(result),
         ...(result.stderr ? { stderr: result.stderr.slice(-1000) } : {}),
-        stderrBytes: Buffer.byteLength(result.stderr),
+        stderrBytes: result.stderrBytes ?? Buffer.byteLength(result.stderr),
+        stderrCapturedBytes: Buffer.byteLength(result.stderr),
+        ...(result.stderrFile ? { stderrFile: result.stderrFile } : {}),
+        ...(result.stderrTruncated ? { stderrTruncated: true } : {}),
         ...(result.stdout ? { stdout: result.stdout.slice(-1000) } : {}),
-        stdoutBytes: Buffer.byteLength(result.stdout),
+        stdoutBytes: result.stdoutBytes ?? Buffer.byteLength(result.stdout),
+        stdoutCapturedBytes: Buffer.byteLength(result.stdout),
+        ...(result.stdoutFile ? { stdoutFile: result.stdoutFile } : {}),
+        ...(result.stdoutTruncated ? { stdoutTruncated: true } : {}),
     };
 }
 function isUsableBranch(branch) {
-    return branch.status === "done" && branch.stdoutBytes > 0;
+    return (branch.status === "done" &&
+        branch.stdoutBytes > 0 &&
+        branch.stdoutTruncated !== true);
 }
 function createSoftQuorum(branches) {
     if (branches.length === 0)
@@ -231,15 +297,24 @@ function formatParallelStatusHeader(branches, minSuccessful) {
         return undefined;
     return `--- parallel_status: ${getParallelStatus(branches, minSuccessful)} usable: ${countUsableBranches(branches)} expected: ${branches.length} minimum: ${minSuccessful} ---`;
 }
+function stdoutWithEvidenceReference(result) {
+    return result.evidenceRef
+        ? `${result.stdout}\nACTOR_EVIDENCE_REF: ${result.evidenceRef}`
+        : result.stdout;
+}
 function joinParallelStdout(branches, results, minSuccessful) {
     const body = results
         .map((result, index) => {
         const branch = branches[index];
-        const header = `--- branch: ${branch.label} status: ${branch.status} ---`;
+        const evidence = result.evidenceRef
+            ? ` evidence_ref: ${result.evidenceRef}`
+            : "";
+        const header = `--- branch: ${branch.label} status: ${branch.status}${evidence} ---`;
         if (branch.status === "done")
-            return `${header}\n${result.stdout}`;
+            return `${header}\n${stdoutWithEvidenceReference(result)}`;
+        const stdout = result.stdout ? `\nrejected_stdout: ${result.stdout}` : "";
         const stderr = branch.stderr ? `\nstderr: ${branch.stderr}` : "";
-        return `${header}\nexit: ${branch.code}${stderr}`;
+        return `${header}\nexit: ${branch.code}${stdout}${stderr}`;
     })
         .join("\n");
     return [formatParallelStatusHeader(branches, minSuccessful), body]
@@ -369,8 +444,18 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
     if (!Array.isArray(normalized.template)) {
         const leaf = { ...normalized, ...context };
         const invocation = CommandTemplates.buildCommandTemplateInvocation(leaf, params, cwd, { emptyMessage: "Tool template produced an empty command." });
-        const result = await exec(invocation.command, invocation.args, {
+        const evidenceContext = {
+            ...(normalized.accept_output
+                ? { acceptOutput: normalized.accept_output }
+                : {}),
+            ...(normalized.label ? { label: normalized.label } : {}),
+            ...(typeof controlValues.index === "string"
+                ? { repeatIndex: controlValues.index }
+                : {}),
+        };
+        const rawResult = await exec(invocation.command, invocation.args, {
             ...(actorRecipeContext ? { actorRecipeContext } : {}),
+            ...(Object.keys(evidenceContext).length > 0 ? { evidenceContext } : {}),
             cwd,
             signal,
             stdin,
@@ -383,6 +468,7 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
                 ? { retry: normalizeRetry(normalized.retry, controlValues) }
                 : {}),
         });
+        const result = await applyOutputAcceptancePolicy(rawResult, normalized.accept_output);
         return {
             branches: [],
             commands: [formatInvocationDetail(invocation)],
@@ -398,6 +484,12 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
         const concurrency = normalizeConcurrency(normalized.concurrency, controlValues, steps.length);
         const minSuccessful = normalizeMinSuccessful(normalized.min_successful, controlValues, steps.length);
         const branchResults = await mapConcurrent(steps, concurrency, (step) => executeTemplateConfig(step, context, params, exec, cwd, signal, stdin, false, actorRecipeContext));
+        const branchPipelineStdouts = await Promise.all(branchResults.map((item) => resolvePipelineStdout(item.result)));
+        for (const [index, item] of branchResults.entries()) {
+            if (item.result.stdoutTruncated && branchPipelineStdouts[index] === undefined) {
+                item.result = rejectIncompletePipelineOutput(item.result);
+            }
+        }
         const commands = branchResults.flatMap((item) => item.commands);
         const failures = branchResults.flatMap((item) => item.failures);
         const branches = branchResults.map((item, index) => createBranchReport(getNodeLabel(steps[index], index), item.commands.at(-1) ?? "<template>", item.result));
@@ -432,8 +524,13 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
             if (item.result.code === 0)
                 return item.result;
             addResultFailure(failures, item);
-            return { ...item.result, code: 0, stdout: "" };
+            return { ...item.result, code: 0 };
         });
+        const completeSuccessful = successful.map((item, index) => ({
+            ...item,
+            stdout: branchPipelineStdouts[index] ?? item.stdout,
+            evidenceRef: undefined,
+        }));
         const result = {
             code: 0,
             killed: successful.some((item) => item.killed),
@@ -442,6 +539,11 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
                 .filter(Boolean)
                 .join("\n"),
             stdout: joinParallelStdout(branches, successful, minSuccessful),
+            pipelineStdout: joinParallelStdout(branches, completeSuccessful, minSuccessful),
+            stdoutBytes: successful.reduce((total, item) => total + (item.stdoutBytes ?? Buffer.byteLength(item.stdout)), 0),
+            ...(successful.some((item) => item.stdoutTruncated)
+                ? { stdoutTruncated: true }
+                : {}),
         };
         if (quorumUnmet && nodeFailure === "root") {
             return {
@@ -504,12 +606,28 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
     const failures = [];
     let nextStdin = stdin;
     let result;
-    for (const step of steps) {
+    for (const [stepIndex, step] of steps.entries()) {
         const executed = await executeTemplateConfig(step, context, params, exec, cwd, signal, nextStdin, false, actorRecipeContext);
         branches.push(...executed.branches);
         commands.push(...executed.commands);
         failures.push(...executed.failures);
-        result = executed.result;
+        const pipelineStdout = await resolvePipelineStdout(executed.result);
+        const incompletePipelineInput = stepIndex < steps.length - 1 && pipelineStdout === undefined;
+        result = incompletePipelineInput
+            ? rejectIncompletePipelineOutput(executed.result)
+            : executed.result;
+        executed.result = result;
+        if (incompletePipelineInput) {
+            addResultFailure(failures, executed);
+            return {
+                branches,
+                commands,
+                criticalFailure: true,
+                failureScope: "root",
+                failures,
+                result,
+            };
+        }
         if (result.code !== 0) {
             const failureScope = maxFailureScope(executed.failureScope, executed.criticalFailure ? "root" : undefined, getFailureScope(step), getFailureScope(normalized), isRoot && steps.length === 1 ? "root" : undefined);
             if (failureScope === "root") {
@@ -537,13 +655,25 @@ async function executeTemplateConfig(config, inherited, params, exec, cwd, signa
             nextStdin = "";
             continue;
         }
-        nextStdin = result.stdout;
+        nextStdin = pipelineStdout;
     }
     return { branches, commands, failures, result: result };
 }
 async function executeTemplateSteps(cfg, params, exec, cwd, signal) {
     return executeTemplateConfig(createTemplateConfig(cfg), {}, params, exec, cwd, signal, undefined, true, undefined);
 }
+function getCaptureDetails(result) {
+    return {
+        stdoutBytes: result.stdoutBytes ?? Buffer.byteLength(result.stdout),
+        stdoutCapturedBytes: Buffer.byteLength(result.stdout),
+        stderrBytes: result.stderrBytes ?? Buffer.byteLength(result.stderr),
+        stderrCapturedBytes: Buffer.byteLength(result.stderr),
+        ...(result.stdoutFile ? { stdoutFile: result.stdoutFile } : {}),
+        ...(result.stderrFile ? { stderrFile: result.stderrFile } : {}),
+        ...(result.stdoutTruncated ? { stdoutTruncated: true } : {}),
+        ...(result.stderrTruncated ? { stderrTruncated: true } : {}),
+    };
+}
 export async function executeRegisteredTool(cfg, params, exec, cwd, signal) {
     const executed = await executeTemplateSteps(cfg, Schema.normalizeRuntimeValues(params, cfg.argTypes), exec, cwd, signal);
     const command = formatCommandDetail(executed.commands);
@@ -556,7 +686,9 @@ export async function executeRegisteredTool(cfg, params, exec, cwd, signal) {
                 branches: executed.branches,
                 code: result.code,
                 command,
+                fullOutputPath: result.stdoutFile ?? formatted.fullOutputPath,
                 killed: result.killed,
+                ...getCaptureDetails(result),
                 ...(executed.failures.length > 0
                     ? { nonCriticalFailures: executed.failures }
                     : {}),
@@ -575,8 +707,9 @@ export async function executeRegisteredTool(cfg, params, exec, cwd, signal) {
         details: {
             code: result.code,
             command,
-            fullOutputPath: formatted.fullOutputPath,
+            fullOutputPath: result.stdoutFile ?? formatted.fullOutputPath,
             killed: result.killed,
+            ...getCaptureDetails(result),
             ...(executed.branches.length > 0 ? { branches: executed.branches } : {}),
             ...(executed.failures.length > 0
                 ? { nonCriticalFailures: executed.failures }

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

@@ -3,4 +3,5 @@
  * Zones: file persistence, atomic writes, runtime state support
  * Owns generic durable JSON file writes shared by registry config and async run state.
  */
+export declare function withFileMutationLock<T>(path: string, mutate: () => T): T;
 export declare function writeJsonAtomic(path: string, value: unknown): void;

package/dist/lib/file-state.js

@@ -3,9 +3,97 @@
  * Zones: file persistence, atomic writes, runtime state support
  * Owns generic durable JSON file writes shared by registry config and async run state.
  */
-import { randomUUID } from "node:crypto";
-import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, parse, resolve } from "node:path";
+const FILE_MUTATION_LOCK_TIMEOUT_MS = 5000;
+const FILE_MUTATION_LOCK_STALE_MS = 30000;
+const FILE_MUTATION_LOCK_ROOT = join(tmpdir(), "pi-actors-file-locks");
+function canonicalMutationPath(path) {
+    const absolute = resolve(path);
+    const suffix = [];
+    let existing = absolute;
+    while (!existsSync(existing)) {
+        const parent = dirname(existing);
+        if (parent === existing || existing === parse(existing).root)
+            break;
+        suffix.unshift(basename(existing));
+        existing = parent;
+    }
+    const canonicalAncestor = existsSync(existing)
+        ? realpathSync.native(existing)
+        : existing;
+    const canonical = resolve(canonicalAncestor, ...suffix);
+    return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+function mutationLockPath(path) {
+    const key = createHash("sha256")
+        .update(canonicalMutationPath(path))
+        .digest("hex");
+    return join(FILE_MUTATION_LOCK_ROOT, `${key}.lock`);
+}
+function lockOwnerIsDead(lockPath) {
+    try {
+        const owner = JSON.parse(readFileSync(join(lockPath, "owner.json"), "utf8"));
+        const pid = Number(owner.pid);
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        try {
+            process.kill(pid, 0);
+            return false;
+        }
+        catch (error) {
+            return error.code === "ESRCH";
+        }
+    }
+    catch {
+        return false;
+    }
+}
+export function withFileMutationLock(path, mutate) {
+    mkdirSync(FILE_MUTATION_LOCK_ROOT, { recursive: true });
+    const lockPath = mutationLockPath(path);
+    const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            mkdirSync(lockPath);
+            try {
+                writeFileSync(join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() })}\n`, "utf8");
+            }
+            catch (error) {
+                rmSync(lockPath, { recursive: true, force: true });
+                throw error;
+            }
+            break;
+        }
+        catch (error) {
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs >
+                    FILE_MUTATION_LOCK_STALE_MS &&
+                    lockOwnerIsDead(lockPath)) {
+                    rmSync(lockPath, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for file mutation lock: ${canonicalMutationPath(path)}`, {
+                    cause: error,
+                });
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+    }
+    try {
+        return mutate();
+    }
+    finally {
+        rmSync(lockPath, { recursive: true, force: true });
+    }
+}
 export function writeJsonAtomic(path, value) {
     mkdirSync(dirname(path), { recursive: true });
     const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;

package/dist/lib/observability.js

@@ -43,6 +43,9 @@ export function deliverRunTransitionNotifications(transitions, sink) {
             display: true,
             details: transition,
         });
+        if (transition.stateDir) {
+            AsyncRuns.markRunTerminalNotificationHandled(transition.stateDir, transition.to);
+        }
     }
 }
 export function deliverRunOutboxNotifications(events, sink) {
@@ -494,9 +497,9 @@ export function detectRunTransitions(previous, summary) {
     for (const run of summary.runs) {
         const key = runObservationKey(run);
         const old = previous.get(key);
-        if (old && old !== run.status && TERMINAL.has(run.status)) {
+        if (!run.terminalHandled && TERMINAL.has(run.status)) {
             transitions.push({
-                from: old,
+                from: old ?? "running",
                 run: run.run,
                 ...(run.stateDir ? { stateDir: run.stateDir } : {}),
                 ...(run.artifacts ? { artifacts: run.artifacts } : {}),

package/dist/lib/prompts.d.ts

@@ -6,13 +6,12 @@
 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: string leaf, array sequence, object node; flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, 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/mailbox/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 runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.\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; 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, 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/mailbox/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 runtime/FIFO/outbox 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. 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.";
     readonly draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.";
     readonly async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.";
-    readonly state_dir: "Optional async run state directory for a co-located template recipe.";
     readonly template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.";
     readonly templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.";
     readonly templateNull: "Delete the tool when template is null.";