@llblab/pi-actors 0.23.0 → 0.24.0

package/README.md

@@ -43,6 +43,8 @@ Or from git:
 pi install git:github.com/llblab/pi-actors
 ```
 
+The npm package is dist-first for JavaScript-only runtimes: default Pi metadata points at compiled `dist/` entrypoints and mirrored runtime assets. Source TypeScript and source skills remain in the package for TypeScript-native runtimes through optional source metadata.
+
 ## Address Surface
 
 Actors and coordination endpoints are addressed with compact route strings:
@@ -255,6 +257,17 @@ Use mailbox declarations when an actor has a stable conversational surface.
 
 Core actor state, inspection, foreground tools, and basic async runs are portable Node.js behavior. Run-local messaging and stop/kill use a platform adapter under the same `message` API: Unix-compatible recipes can use their existing local control endpoint, while native Windows recipes can expose a Windows-native endpoint in run state. Some packaged scripts still depend on Unix tools and are WSL/Linux/macOS-only until migrated; their public recipe surface should stay `spawn` / `message` / `inspect` either way.
 
+| Surface | Linux/macOS/WSL | Native Windows |
+| --- | --- | --- |
+| Foreground tools, recipe discovery, inspect | Supported | Supported |
+| Async runs and file-backed state | Supported | Supported |
+| Mailbox-only actors and worker recipe | Supported | Supported |
+| FIFO control endpoints | Supported | Not supported; use mailbox or named pipe |
+| Named-pipe control endpoints | Not needed | Supported when recipe exposes one |
+| Process cancel/kill | Process group signal with pid fallback | Windows process-tree adapter |
+
+Packaged recipes should prefer mailbox/wake behavior for portable control. Recipes that require FIFO, Unix shell tools, or platform-specific media backends should make that limitation visible in docs or diagnostics before launch.
+
 ## Safety Boundary
 
 `pi-actors` is local-first, not sandbox-first.

package/dist/fixtures/protocol/actor-message-branch.json

@@ -0,0 +1,13 @@
+{
+  "to": "branch:demo/reviewer",
+  "from": "run:demo",
+  "type": "task.assign",
+  "summary": "Review the current slice",
+  "body": {
+    "task": "Check mailbox loop semantics"
+  },
+  "correlation_id": "task-001",
+  "metadata": {
+    "requires_response": true
+  }
+}

package/dist/fixtures/protocol/artifact-manifest.json

@@ -0,0 +1,9 @@
+{
+  "report": {
+    "path": "{state_dir}/report.md",
+    "kind": "markdown",
+    "media_type": "text/markdown",
+    "required": true
+  },
+  "journal": "{state_dir}/journal.jsonl"
+}

package/dist/fixtures/protocol/mailbox-contract.json

@@ -0,0 +1,15 @@
+{
+  "accepts": [
+    "task.assign",
+    {
+      "type": "control.stop",
+      "description": "Request graceful worker shutdown"
+    }
+  ],
+  "emits": [
+    "task.claim",
+    "task.result",
+    "awaiting_assignment",
+    "actor.leave"
+  ]
+}

package/dist/fixtures/protocol/recipe-summary.json

@@ -0,0 +1,16 @@
+{
+  "id": "actor-worker",
+  "path": "recipes/actor-worker.json",
+  "location": "packaged",
+  "active": true,
+  "args": [
+    "run",
+    "branch",
+    "poll_ms",
+    "state_dir"
+  ],
+  "mailbox": {
+    "kind": "branch",
+    "accepts": ["task.assign", "control.stop"]
+  }
+}

package/dist/fixtures/protocol/room-message.json

@@ -0,0 +1,11 @@
+{
+  "to": "room:demo",
+  "from": "branch:demo/worker",
+  "type": "task.result",
+  "summary": "Worker completed task",
+  "body": {
+    "id": "inbox-001",
+    "result": "ok"
+  },
+  "received_at": "2026-05-26T00:00:00.000Z"
+}

package/dist/fixtures/protocol/room-roster.json

@@ -0,0 +1,11 @@
+{
+  "room": "main",
+  "members": {
+    "branch:demo/worker": {
+      "display": "worker",
+      "role": "worker",
+      "status": "present",
+      "last_seen": "2026-05-26T00:00:00.000Z"
+    }
+  }
+}

package/dist/fixtures/protocol/run-inbox-message.json

@@ -0,0 +1,9 @@
+{
+  "id": "inbox-001",
+  "status": "queued",
+  "queued_at": "2026-05-26T00:00:00.000Z",
+  "to": "run:demo",
+  "from": "coordinator",
+  "type": "control.continue",
+  "body": "continue"
+}

package/dist/fixtures/protocol/run-outbox-event.json

@@ -0,0 +1,9 @@
+{
+  "id": "event-001",
+  "type": "task.result",
+  "summary": "Worker completed task",
+  "body": {
+    "result": "ok"
+  },
+  "created_at": "2026-05-26T00:00:00.000Z"
+}

package/dist/fixtures/protocol/run-state.json

@@ -0,0 +1,10 @@
+{
+  "run": "demo",
+  "state_dir": "{state_dir}",
+  "status": "running",
+  "template": "echo demo",
+  "values": {
+    "run_id": "demo",
+    "state_dir": "{state_dir}"
+  }
+}

package/dist/index.js

@@ -39,6 +39,7 @@ export default function toolRegistryExtension(pi) {
     const runDirWatchers = new Map();
     const observedRuns = new Map();
     const observedRunEventLines = new Map();
+    const observedRunOutboxEventIds = new Map();
     const retirementAttempts = new Set();
     let runStatusFrame = 0;
     let communicationWidgetVisible = false;
@@ -102,7 +103,7 @@ export default function toolRegistryExtension(pi) {
             }
             : undefined, { placement: "belowEditor" });
         const transitions = Observability.detectRunTransitions(observedRuns, summary);
-        const outboxEvents = Observability.detectRunOutboxEvents(observedRunEventLines, summary);
+        const outboxEvents = Observability.detectRunOutboxEvents(observedRunEventLines, summary, observedRunOutboxEventIds);
         if (!notify)
             return;
         retireCandidateRuns(ctx, summary);
@@ -121,7 +122,7 @@ export default function toolRegistryExtension(pi) {
                 details: transition,
             }, { deliverAs: "followUp", triggerTurn: true });
         }
-        Observability.pruneRunObservationState(observedRuns, observedRunEventLines, summary, transitions.map((transition) => transition.stateDir ?? transition.run));
+        Observability.pruneRunObservationState(observedRuns, observedRunEventLines, summary, transitions.map((transition) => transition.stateDir ?? transition.run), observedRunOutboxEventIds);
         for (const event of outboxEvents) {
             if (!Observability.shouldNotifyRunOutboxEvent(event))
                 continue;

package/dist/lib/actor-inspector-tui.js

@@ -7,31 +7,14 @@ import * as path from "node:path";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import * as Limits from "./limits.js";
 import * as Paths from "./paths.js";
+import { readJsonFileResilient, readJsonlFileResilient } from "./state-readers.js";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
         : {};
 }
 function readJsonLines(file) {
-    try {
-        return fs
-            .readFileSync(file, "utf8")
-            .split("\n")
-            .filter(Boolean)
-            .flatMap((line) => {
-            try {
-                return [JSON.parse(line)];
-            }
-            catch {
-                return [];
-            }
-        });
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return [];
-        return [];
-    }
+    return readJsonlFileResilient(file).records;
 }
 function previewValue(value, maxLength = Limits.INSPECTOR_BODY_PREVIEW_CHARS) {
     if (value === undefined)
@@ -85,12 +68,7 @@ function previewFromMessage(run, message, timestamp, displayNames = {}) {
     };
 }
 function readRoomRosterRecords(stateDir, room) {
-    try {
-        return JSON.parse(fs.readFileSync(path.join(stateDir, "rooms", room, "roster.json"), "utf8"));
-    }
-    catch {
-        return {};
-    }
+    return readJsonFileResilient(path.join(stateDir, "rooms", room, "roster.json"), {}).value;
 }
 function memberDisplay(_address, member) {
     const display = typeof member.display === "string" ? member.display.trim() : "";
@@ -170,13 +148,8 @@ function readOutboxPreviews(run, stateDir) {
         .filter((preview) => Boolean(preview));
 }
 function getRunOwnerId(stateDir) {
-    try {
-        const meta = JSON.parse(fs.readFileSync(path.join(stateDir, "run.json"), "utf8"));
-        return typeof meta.ownerId === "string" ? meta.ownerId : undefined;
-    }
-    catch {
-        return undefined;
-    }
+    const meta = readJsonFileResilient(path.join(stateDir, "run.json"), undefined).value;
+    return typeof meta?.ownerId === "string" ? meta.ownerId : undefined;
 }
 function matchesOwner(stateDir, ownerId) {
     return ownerId === undefined || getRunOwnerId(stateDir) === ownerId;

package/dist/lib/actor-rooms.d.ts

@@ -44,6 +44,8 @@ export interface RoomStatus {
     message_count: number;
     roster_count: number;
     compaction?: RoomCompactionInfo;
+    diagnostics?: string[];
+    diagnostics_count?: number;
     last_message_at?: string;
     last_message_from?: string;
     last_message_summary?: string;
@@ -71,6 +73,11 @@ export interface ActorCommunicationSnapshot {
 }
 export declare function readRoomRoster(stateDir: string, room: string): Record<string, RoomMember>;
 export interface BranchInboxRecord extends ActorMessage {
+    claimed_at?: string;
+    claimed_by?: string;
+    error?: string;
+    failed_at?: string;
+    handled_at?: string;
     id?: string;
     queued_at?: string;
     status?: string;
@@ -83,6 +90,7 @@ export declare function readBranchInboxMessages(stateDir: string, run: string, a
 export declare function readBranchInboxDiagnostics(stateDir: string, run: string, address: string, limit?: number): BranchInboxReadResult;
 export declare function getBranchInboxTerminalRetainLimit(): number;
 export declare function appendBranchInboxMessage(stateDir: string, run: string, address: string, message: ActorMessage): void;
+export declare function claimBranchInboxMessage(stateDir: string, run: string, address: string, owner?: string, statuses?: string[]): BranchInboxRecord | undefined;
 export declare function updateBranchInboxMessageStatus(stateDir: string, run: string, address: string, id: string, status: "claimed" | "handled" | "failed", metadata?: Record<string, unknown>): boolean;
 export declare function appendRoomMessage(stateDir: string, room: string, message: ActorMessage): RoomAppendResult;
 export declare function readRoomMessages(stateDir: string, room: string, limit?: number): RoomTimelineEntry[];

package/dist/lib/actor-rooms.js

@@ -8,6 +8,7 @@ import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import * as Limits from "./limits.js";
 import { notifyRuntimeWake } from "./runtime-notifier.js";
+import { formatStateReadDiagnostics, readJsonFileResilient, readJsonlFileResilient, } from "./state-readers.js";
 const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 const STATE_LOCK_TIMEOUT_MS = 5000;
 const DEFAULT_ROOM_MAX_MESSAGES = 10000;
@@ -87,14 +88,7 @@ function runFromRoomAddress(address) {
     return match?.[1];
 }
 function readJsonFile(file, fallback) {
-    try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return fallback;
-        throw error;
-    }
+    return readJsonFileResilient(file, fallback).value;
 }
 function writeJsonFile(file, value) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -394,6 +388,43 @@ export function appendBranchInboxMessage(stateDir, run, address, message) {
         releaseLock();
     }
 }
+export function claimBranchInboxMessage(stateDir, run, address, owner = "runtime", statuses = ["queued"]) {
+    const branch = branchIdFromAddress(address, run);
+    if (!branch)
+        throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+    const releaseLock = acquireBranchInboxLock(stateDir, branch);
+    try {
+        const file = branchInboxFile(stateDir, branch);
+        const records = readAllBranchInboxLines(stateDir, run, address);
+        let claimed;
+        const now = new Date().toISOString();
+        const updated = records.map((record) => {
+            if (claimed || !("message" in record))
+                return record;
+            const status = record.message.status ?? "queued";
+            if (!statuses.includes(status))
+                return record;
+            claimed = {
+                ...record.message,
+                claimed_at: now,
+                claimed_by: owner,
+                status: "claimed",
+            };
+            return { message: claimed };
+        });
+        if (!claimed)
+            return undefined;
+        fs.writeFileSync(file, `${updated.map((record) => ("raw" in record ? record.raw : JSON.stringify(record.message))).join("\n")}\n`);
+        notifyActorWake(stateDir, address, "branch.inbox.claim", {
+            id: claimed.id,
+            owner,
+        });
+        return claimed;
+    }
+    finally {
+        releaseLock();
+    }
+}
 export function updateBranchInboxMessageStatus(stateDir, run, address, id, status, metadata = {}) {
     const branch = branchIdFromAddress(address, run);
     if (!branch)
@@ -469,7 +500,14 @@ export function appendRoomMessage(stateDir, room, message) {
 export function readRoomMessages(stateDir, room, limit = 40) {
     try {
         const lines = readJsonlTailLines(messagesFile(stateDir, room), limit);
-        return lines.map((line) => JSON.parse(line));
+        return lines.flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        });
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -503,7 +541,14 @@ export function readRoomMessagePreviews(stateDir, room, limit = 40) {
 export function getRoomStatus(stateDir, room) {
     const messageCount = readRoomMessageCount(stateDir, room);
     const [last] = readRoomMessages(stateDir, room, 1);
-    const compaction = readJsonFile(path.join(roomDir(stateDir, room), "compaction.json"), undefined);
+    const compactionRead = readJsonFileResilient(path.join(roomDir(stateDir, room), "compaction.json"), undefined);
+    const rosterRead = readJsonFileResilient(rosterFile(stateDir, room), {});
+    const messageRead = readJsonlFileResilient(messagesFile(stateDir, room));
+    const diagnostics = [
+        ...messageRead.diagnostics,
+        ...rosterRead.diagnostics,
+        ...compactionRead.diagnostics,
+    ];
     return {
         ...(last
             ? {
@@ -513,10 +558,16 @@ export function getRoomStatus(stateDir, room) {
                 last_message_type: last.type,
             }
             : {}),
-        ...(compaction ? { compaction } : {}),
+        ...(compactionRead.value ? { compaction: compactionRead.value } : {}),
+        ...(diagnostics.length
+            ? {
+                diagnostics: formatStateReadDiagnostics(diagnostics),
+                diagnostics_count: diagnostics.length,
+            }
+            : {}),
         message_count: messageCount,
         room,
-        roster_count: Object.keys(readRoomRoster(stateDir, room)).length,
+        roster_count: Object.keys(rosterRead.value).length,
     };
 }
 export function ensureRoomMember(stateDir, run, room, address, body, summary) {
@@ -541,14 +592,7 @@ export function ensureDefaultRoom(stateDir, run) {
     return ensureRoomMember(stateDir, run, "main", `run:${run}`, { role: "run", status: "present" }, "Run joined default room");
 }
 export function readCommunicationSnapshot(stateDir) {
-    try {
-        return JSON.parse(fs.readFileSync(snapshotFile(stateDir), "utf8"));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return undefined;
-        throw error;
-    }
+    return readJsonFileResilient(snapshotFile(stateDir), undefined).value;
 }
 export function readRoomContacts(stateDir, room, self) {
     return Object.values(readRoomRoster(stateDir, room))

package/dist/lib/actor-worker.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical mailbox-backed actor worker entrypoint logic.
+ * Zones: worker demo, mailbox loop recipe runtime
+ */
+interface ActorWorkerArgs {
+    branch?: string;
+    poll_ms?: string | number;
+    run?: string;
+    state_dir?: string;
+}
+export declare function parseActorWorkerArgs(argv: string[]): ActorWorkerArgs;
+export declare function runActorWorker(argv?: string[]): Promise<void>;
+export {};

package/dist/lib/actor-worker.js

@@ -0,0 +1,86 @@
+/**
+ * Canonical mailbox-backed actor worker entrypoint logic.
+ * Zones: worker demo, mailbox loop recipe runtime
+ */
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendRoomMessage, ensureRoomMember } from "./actor-rooms.js";
+import { handleMailboxLoopOnce, isMailboxLoopStopMessage } from "./mailbox-loop.js";
+export function parseActorWorkerArgs(argv) {
+    const args = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token.startsWith("--"))
+            continue;
+        const key = token.slice(2).replaceAll("-", "_");
+        const next = argv[index + 1];
+        if (!next || next.startsWith("--")) {
+            args[key] = true;
+            continue;
+        }
+        args[key] = next;
+        index += 1;
+    }
+    return args;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function text(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+export async function runActorWorker(argv = process.argv.slice(2)) {
+    const args = parseActorWorkerArgs(argv);
+    const stateDir = String(args.state_dir ?? "");
+    const run = String(args.run ?? "");
+    const branch = String(args.branch ?? "worker");
+    const pollMs = Math.max(50, Number(args.poll_ms ?? 1000));
+    if (!stateDir || !run) {
+        throw new Error("usage: actor-worker.mjs --state-dir <dir> --run <id> [--branch worker] [--poll-ms 1000]");
+    }
+    const branchAddress = `branch:${run}/${branch}`;
+    const roomAddress = `room:${run}`;
+    const journalPath = join(stateDir, "worker-events.jsonl");
+    function journal(event, data = {}) {
+        appendFileSync(journalPath, `${JSON.stringify({ event, ts: new Date().toISOString(), ...data })}\n`);
+    }
+    function room(type, summary, body = {}) {
+        appendRoomMessage(stateDir, "main", {
+            body,
+            from: branchAddress,
+            summary,
+            to: roomAddress,
+            type,
+        });
+    }
+    ensureRoomMember(stateDir, run, "main", branchAddress, { display: branch, role: "worker", status: "present" }, `${branch} joined as mailbox worker`);
+    room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
+    journal("worker.started", { branch, run });
+    let stopping = false;
+    while (!stopping) {
+        const result = await handleMailboxLoopOnce({ address: branchAddress, kind: "branch", run, stateDir }, (message) => {
+            if (isMailboxLoopStopMessage(message)) {
+                stopping = true;
+                room("actor.leave", `${branch} stopping`, { branch, reason: message.type });
+                journal("worker.stopping", { id: message.id, type: message.type });
+                return;
+            }
+            room("task.claim", `${branch} claimed ${message.type}`, {
+                branch,
+                id: message.id,
+                type: message.type,
+            });
+            room("task.result", `${branch} handled ${message.type}`, {
+                branch,
+                id: message.id,
+                result: text(message.body),
+                type: message.type,
+            });
+            room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
+            journal("task.handled", { id: message.id, type: message.type });
+        }, { owner: branchAddress });
+        if (!result.handled)
+            await sleep(pollMs);
+    }
+    journal("worker.done", { branch, run });
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Detached async-runner entrypoint logic.
+ * Zones: async run process, command-template execution telemetry
+ */
+export declare function runAsyncRunner(stateDir?: string): Promise<void>;

package/dist/lib/async-runner.js

@@ -0,0 +1,134 @@
+/**
+ * Detached async-runner entrypoint logic.
+ * Zones: async run process, command-template execution telemetry
+ */
+import { appendFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendRecipeContextToPiArgs } from "./actor-recipe-context.js";
+import { execCommandTemplate } from "./command-templates.js";
+import { executeRegisteredTool } from "./execution.js";
+import { writeJsonAtomic } from "./file-state.js";
+function quoteCommandDetailPart(value) {
+    if (value === "")
+        return "''";
+    if (/^[A-Za-z0-9_/:=.,@%+\-]+$/.test(value))
+        return value;
+    return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+function formatCommandDetail(command, args) {
+    return [command, ...args].map(quoteCommandDetailPart).join(" ");
+}
+function summarizeCommandDetail(commandDetail) {
+    return commandDetail.length > 160
+        ? `${commandDetail.slice(0, 157)}...`
+        : commandDetail;
+}
+export async function runAsyncRunner(stateDir = process.argv[2]) {
+    if (!stateDir)
+        throw new Error("missing state dir");
+    const runPath = join(stateDir, "run.json");
+    const progressPath = join(stateDir, "progress.json");
+    const resultPath = join(stateDir, "result.json");
+    const eventsPath = join(stateDir, "events.jsonl");
+    const outboxPath = join(stateDir, "outbox.jsonl");
+    const stdoutPath = join(stateDir, "stdout.log");
+    const stderrPath = join(stateDir, "stderr.log");
+    const meta = JSON.parse(readFileSync(runPath, "utf8"));
+    function event(name, data = {}) {
+        appendFileSync(eventsPath, `${JSON.stringify({ event: name, ts: new Date().toISOString(), ...data })}\n`);
+    }
+    function outbox(name, summary, data = {}, delivery = "log", level = "info") {
+        appendFileSync(outboxPath, `${JSON.stringify({ body: data, data, delivery, event: name, from: `run:${meta.run}`, level, summary, to: "coordinator", ts: new Date().toISOString(), type: name })}\n`);
+    }
+    function progress(phase, extra = {}) {
+        writeJsonAtomic(progressPath, {
+            phase,
+            updatedAt: new Date().toISOString(),
+            ...extra,
+        });
+    }
+    let activeSubagents = 0;
+    let completedSubagents = 0;
+    const subagentFailures = [];
+    function getCommandDoneDelivery(result) {
+        return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
+    }
+    function progressRunning() {
+        progress("running", {
+            activeSubagents,
+            completed: completedSubagents,
+            failures: subagentFailures,
+        });
+    }
+    async function observedExec(command, args, options) {
+        const commandDetail = formatCommandDetail(command, args);
+        const execArgs = appendRecipeContextToPiArgs(command, args, meta.recipe_context_records, options?.actorRecipeContext);
+        activeSubagents += 1;
+        event("command.start", { activeSubagents, command: commandDetail });
+        progressRunning();
+        const result = await execCommandTemplate(command, execArgs, options);
+        activeSubagents = Math.max(0, activeSubagents - 1);
+        completedSubagents += 1;
+        if (result.code !== 0) {
+            subagentFailures.push({
+                code: result.code,
+                command: commandDetail,
+                killed: result.killed,
+            });
+        }
+        event("command.done", {
+            activeSubagents,
+            code: result.code,
+            command: commandDetail,
+            killed: result.killed,
+        });
+        outbox("command.done", `Command ${summarizeCommandDetail(commandDetail)} completed with code ${result.code}`, {
+            activeSubagents,
+            ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
+            run_files: [stdoutPath, stderrPath, resultPath, eventsPath, outboxPath],
+            code: result.code,
+            command: commandDetail,
+            killed: result.killed,
+        }, getCommandDoneDelivery(result), result.code === 0 ? "info" : "error");
+        progressRunning();
+        return result;
+    }
+    try {
+        event("run.runner.start", { pid: process.pid });
+        progressRunning();
+        const result = await executeRegisteredTool({
+            name: "run_actor",
+            description: "Detached command-template run actor",
+            template: meta.template,
+            args: [],
+            defaults: {},
+        }, meta.values || {}, observedExec, meta.cwd);
+        const text = result.content?.[0]?.text || "";
+        appendFileSync(stdoutPath, text);
+        writeJsonAtomic(resultPath, {
+            code: result.details.code,
+            command: result.details.command,
+            killed: result.details.killed,
+            truncated: result.details.truncated,
+            completedAt: new Date().toISOString(),
+        });
+        progress("done", {
+            completed: 1,
+            failures: result.details.nonCriticalFailures || [],
+        });
+        event("run.done", { code: result.details.code });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        appendFileSync(stderrPath, `${message}\n`);
+        writeJsonAtomic(resultPath, {
+            code: 1,
+            error: message,
+            killed: false,
+            completedAt: new Date().toISOString(),
+        });
+        progress("failed", { completed: 0, failures: [{ message }] });
+        event("run.failed", { error: message });
+        throw error;
+    }
+}