@llblab/pi-actors 0.20.2 → 0.22.0

package/dist/lib/async-runs.js

@@ -3,8 +3,10 @@
  * Zones: async runtime, lifecycle, state files
  * Owns detached run state, observation, log tailing, listing, and cancellation safety
  */
-import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
 import { closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
+import { createConnection } from "node:net";
 import { platform } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -13,7 +15,9 @@ import { writeJsonAtomic } from "./file-state.js";
 import * as Paths from "./paths.js";
 import * as RecipeReferences from "./recipe-references.js";
 import * as RecipeUsage from "./recipe-usage.js";
+import { notifyRuntimeWake } from "./runtime-notifier.js";
 const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+const RUN_INBOX_LOCK_TIMEOUT_MS = 5000;
 const DEFAULT_STATE_ROOT = Paths.getRunStateRoot();
 const DEFAULT_RECIPE_ROOT = Paths.getRecipeRoot();
 function packageRoot() {
@@ -89,7 +93,8 @@ function assertNoActiveRunState(stateDir) {
     throw new Error(`Run state already has an active owned process: ${String(meta.run ?? stateDir)}. Stop it before reusing the same run_id or state_dir.`);
 }
 function resolveRecipeFile(file) {
-    return RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT);
+    return (RecipeReferences.getRecipePath(file, DEFAULT_RECIPE_ROOT) ??
+        RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT));
 }
 function isMutableUsageRecipeFile(file) {
     const userRoot = resolve(DEFAULT_RECIPE_ROOT);
@@ -300,6 +305,7 @@ export function startRun(params, cwd) {
             template: resolved.template,
             values,
             ...(artifacts ? { artifacts } : {}),
+            ...(startParams.control ? { control: startParams.control } : {}),
             ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
             ...(recipeContextRecords && recipeContextRecords.length > 0
                 ? { recipe_context_records: recipeContextRecords }
@@ -476,6 +482,145 @@ export function readRunEvents(runOrDir, lines = 40) {
         .map((line, index) => parseRunOutboxEventLine(line, run, stateDir, index))
         .filter((event) => Boolean(event));
 }
+function runInboxFile(stateDir) {
+    return join(stateDir, "inbox.jsonl");
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function acquireRunInboxLock(stateDir) {
+    const lockDir = join(stateDir, ".inbox.lock");
+    const started = Date.now();
+    while (true) {
+        try {
+            mkdirSync(lockDir, { recursive: false });
+            writeFileSync(join(lockDir, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`, "utf8");
+            return () => rmSync(lockDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            try {
+                const stat = statSync(lockDir);
+                if (Date.now() - stat.mtimeMs > START_LOCK_MAX_AGE_MS) {
+                    rmSync(lockDir, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() - started > RUN_INBOX_LOCK_TIMEOUT_MS) {
+                throw new Error("Run inbox lock timed out.", { cause: error });
+            }
+            sleepSync(10);
+        }
+    }
+}
+function parseRunInboxLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readRunInboxMessagesFromStateDir(stateDir) {
+    const file = runInboxFile(stateDir);
+    if (!existsSync(file))
+        return [];
+    return readFileSync(file, "utf8")
+        .split("\n")
+        .filter((line) => line.trim())
+        .map(parseRunInboxLine)
+        .filter((message) => Boolean(message));
+}
+function writeRunInboxMessages(stateDir, messages) {
+    writeFileSync(runInboxFile(stateDir), messages.length
+        ? `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`
+        : "", "utf8");
+}
+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);
+    const releaseLock = acquireRunInboxLock(stateDir);
+    try {
+        const messages = readRunInboxMessagesFromStateDir(stateDir);
+        const timestampKey = `${nextStatus}_at`;
+        let changed = false;
+        const updated = messages.map((message) => {
+            if (message.id !== id)
+                return message;
+            changed = true;
+            return {
+                ...message,
+                ...metadata,
+                [timestampKey]: new Date().toISOString(),
+                status: nextStatus,
+            };
+        });
+        if (changed)
+            writeRunInboxMessages(stateDir, updated);
+        return changed;
+    }
+    finally {
+        releaseLock();
+    }
+}
+export function claimRunInboxMessage(runOrDir, owner = "runtime", statuses = ["queued"]) {
+    const status = getRunStatus(runOrDir);
+    const stateDir = String(status.state_dir);
+    const releaseLock = acquireRunInboxLock(stateDir);
+    try {
+        const messages = readRunInboxMessagesFromStateDir(stateDir);
+        const index = messages.findIndex((message) => statuses.includes(String(message.status ?? "queued")));
+        if (index < 0)
+            return undefined;
+        const claimed = {
+            ...messages[index],
+            claimed_at: new Date().toISOString(),
+            claimed_by: owner,
+            id: typeof messages[index].id === "string" ? messages[index].id : randomUUID(),
+            status: "claimed",
+        };
+        messages[index] = claimed;
+        writeRunInboxMessages(stateDir, messages);
+        return claimed;
+    }
+    finally {
+        releaseLock();
+    }
+}
+export async function processRunInboxMessages(runOrDir, handler, options = {}) {
+    const result = { claimed: 0, failed: 0, handled: 0 };
+    const limit = Math.max(1, Number(options.limit ?? 1));
+    const owner = options.owner ?? "runtime";
+    for (let index = 0; index < limit; index += 1) {
+        const message = claimRunInboxMessage(runOrDir, owner, options.statuses);
+        if (!message?.id)
+            break;
+        result.claimed += 1;
+        try {
+            await handler(message);
+            if (updateRunInboxMessageStatus(runOrDir, message.id, "handled")) {
+                result.handled += 1;
+            }
+        }
+        catch (error) {
+            if (updateRunInboxMessageStatus(runOrDir, message.id, "failed", {
+                error: error instanceof Error ? error.message : String(error),
+            })) {
+                result.failed += 1;
+            }
+        }
+    }
+    return result;
+}
 export function appendRunOutboxEvent(runOrDir, event) {
     const status = getRunStatus(runOrDir);
     const stateDir = String(status.state_dir);
@@ -507,10 +652,115 @@ export function appendRunOutboxEvent(runOrDir, event) {
         state_dir: stateDir,
     };
 }
-export function sendRunMessage(runOrDir, message) {
-    if (process.platform === "win32") {
-        throw new Error("run actor messages require Unix FIFO support; use WSL/Linux/macOS or a recipe-specific Windows transport.");
+function getRunControlEndpoint(status, stateDir) {
+    const control = status.control;
+    if (control && typeof control === "object" && !Array.isArray(control)) {
+        const record = control;
+        if ((record.type === "fifo" ||
+            record.type === "mailbox" ||
+            record.type === "named-pipe") &&
+            typeof record.path === "string" &&
+            record.path.trim()) {
+            return { path: record.path, type: record.type };
+        }
+    }
+    return { path: join(stateDir, "control.fifo"), type: "fifo" };
+}
+function appendRunInboxMessage(stateDir, message) {
+    const id = randomUUID();
+    const ts = new Date().toISOString();
+    let record;
+    try {
+        const parsed = JSON.parse(message);
+        record = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : { body: parsed, type: "run.message" };
+    }
+    catch {
+        record = { body: message, type: "run.message" };
+    }
+    const releaseLock = acquireRunInboxLock(stateDir);
+    try {
+        writeFileSync(runInboxFile(stateDir), `${JSON.stringify({ ...record, id, queued_at: ts, received_at: ts, status: "queued" })}\n`, { flag: "a" });
+    }
+    finally {
+        releaseLock();
+    }
+    return id;
+}
+function writeRunMessageReceipt(stateDir, message, bytes, inboxId) {
+    const trimmedMessage = message.trim().toLowerCase();
+    const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(trimmedMessage);
+    const ts = new Date().toISOString();
+    writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ bytes, event: "run.message", inbox_id: inboxId, terminal: terminalMessage || undefined, ts })}\n`, { flag: "a" });
+    updateRunInboxMessageStatus(stateDir, inboxId, "sent", { bytes });
+    if (terminalMessage) {
+        markTerminalHandled(stateDir, {
+            event: "run.message",
+            message: trimmedMessage,
+        });
+    }
+}
+function sendRunMessageToFifo(endpoint, payload) {
+    if (!existsSync(endpoint.path))
+        throw new Error(`Run control FIFO not found: ${endpoint.path}`);
+    const stat = statSync(endpoint.path);
+    if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
+        throw new Error(`Run control endpoint is not a FIFO: ${endpoint.path}`);
+    }
+    let fd;
+    try {
+        fd = openSync(endpoint.path, constants.O_WRONLY | constants.O_NONBLOCK);
+        return writeSync(fd, payload);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function notifyRunMessageWake(stateDir, run, bytes, endpoint, inboxId) {
+    try {
+        const event = notifyRuntimeWake(stateDir, {
+            actor: `run:${run}`,
+            metadata: { bytes, control_type: endpoint.type, inbox_id: inboxId },
+            reason: "run.message",
+        });
+        return { wake: "wake.jsonl", wake_id: event.id };
     }
+    catch {
+        return undefined;
+    }
+}
+function sendRunMessageToNamedPipe(endpoint, payload, send) {
+    if (send)
+        return send(endpoint.path, payload);
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(endpoint.path);
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            reject(new Error("named pipe connection timed out"));
+        }, 5000);
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (error)
+                reject(error);
+            else
+                resolve(Buffer.byteLength(payload));
+        };
+        socket.on("error", finish);
+        socket.on("connect", () => {
+            socket.end(payload, () => finish());
+        });
+    });
+}
+export async function sendRunMessage(runOrDir, message, options = {}) {
     const status = getRunStatus(runOrDir);
     const stateDir = String(status.state_dir);
     const run = String(status.run ?? runOrDir);
@@ -521,52 +771,84 @@ export function sendRunMessage(runOrDir, message) {
         throw new Error(`Run pid is not alive: ${run}`);
     if (!pidMatchesRun(pid, String(status.cwd), stateDir))
         throw new Error(`Run pid owner mismatch: ${run}`);
-    const controlPath = join(stateDir, "control.fifo");
-    if (!existsSync(controlPath))
-        throw new Error(`Run control FIFO not found: ${controlPath}`);
-    const stat = statSync(controlPath);
-    if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
-        throw new Error(`Run control endpoint is not a FIFO: ${controlPath}`);
-    }
+    const endpoint = getRunControlEndpoint(status, stateDir);
     const payload = message.endsWith("\n") ? message : `${message}\n`;
-    let fd;
+    const payloadBytes = Buffer.byteLength(payload);
+    const inboxId = appendRunInboxMessage(stateDir, message);
+    const wake = notifyRunMessageWake(stateDir, run, payloadBytes, endpoint, inboxId);
+    const runtimePlatform = options.platform ?? process.platform;
+    if (endpoint.type === "mailbox") {
+        return {
+            ...(wake ?? {}),
+            bytes: payloadBytes,
+            control: "inbox.jsonl",
+            control_path: endpoint.path,
+            control_type: endpoint.type,
+            queued: true,
+            run,
+            sent: true,
+            state_dir: stateDir,
+        };
+    }
     try {
-        fd = openSync(controlPath, constants.O_WRONLY | constants.O_NONBLOCK);
-        const bytes = writeSync(fd, payload);
-        const trimmedMessage = message.trim().toLowerCase();
-        const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(trimmedMessage);
-        const ts = new Date().toISOString();
-        writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts })}\n`, { flag: "a" });
-        try {
-            const envelope = JSON.parse(message);
-            writeFileSync(join(stateDir, "inbox.jsonl"), `${JSON.stringify({ ...envelope, received_at: ts })}\n`, { flag: "a" });
-        }
-        catch {
-            // Plain control lines are already represented in events.jsonl.
-        }
-        if (terminalMessage) {
-            markTerminalHandled(stateDir, {
-                event: "run.message",
-                message: trimmedMessage,
-            });
+        if (endpoint.type === "fifo") {
+            if (runtimePlatform === "win32") {
+                throw new Error("run actor messages on native Windows require a named-pipe control endpoint; this recipe still exposes Unix FIFO control.");
+            }
+            const bytes = sendRunMessageToFifo(endpoint, payload);
+            writeRunMessageReceipt(stateDir, message, bytes, inboxId);
+            return {
+                ...(wake ?? {}),
+                bytes,
+                control: "control.fifo",
+                control_path: endpoint.path,
+                control_type: endpoint.type,
+                run,
+                sent: true,
+                state_dir: stateDir,
+            };
         }
+        const bytes = await sendRunMessageToNamedPipe(endpoint, payload, options.namedPipeSend);
+        writeRunMessageReceipt(stateDir, message, bytes, inboxId);
         return {
+            ...(wake ?? {}),
             bytes,
-            control: "control.fifo",
+            control: endpoint.path,
+            control_path: endpoint.path,
+            control_type: endpoint.type,
             run,
             sent: true,
             state_dir: stateDir,
         };
     }
     catch (error) {
-        throw new Error(`Run control FIFO is not ready: ${controlPath}: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Run control endpoint is not ready: ${endpoint.path}: ${error instanceof Error ? error.message : String(error)}`);
     }
-    finally {
-        if (fd !== undefined)
-            closeSync(fd);
+}
+export function getRunProcessSignalPlan(pid, signal, runtimePlatform = process.platform) {
+    if (runtimePlatform === "win32") {
+        return {
+            args: [
+                "/PID",
+                String(pid),
+                "/T",
+                ...(signal === "SIGKILL" ? ["/F"] : []),
+            ],
+            command: "taskkill",
+            signalTarget: "processTree",
+        };
     }
+    return { signalTarget: "processGroup" };
 }
 function signalOwnedRunProcess(pid, signal) {
+    const plan = getRunProcessSignalPlan(pid, signal);
+    if (plan.command && plan.args) {
+        const result = spawnSync(plan.command, plan.args, { encoding: "utf8" });
+        if (result.status !== 0) {
+            throw new Error(result.stderr?.trim() || result.stdout?.trim() || `${plan.command} failed`);
+        }
+        return plan;
+    }
     try {
         process.kill(-pid, signal);
         return { signalTarget: "processGroup" };

package/dist/lib/command-templates.js

@@ -74,8 +74,15 @@ function getExecutableName(command) {
         return "";
     return command.split(/[\\/]/).pop()?.toLowerCase() ?? "";
 }
+function matchesFlag(arg, flag) {
+    if (arg === flag)
+        return true;
+    if (/^-[A-Za-z]$/.test(flag) && /^-[A-Za-z]+$/.test(arg))
+        return arg.slice(1).includes(flag.slice(1));
+    return false;
+}
 function hasAnyFlag(args, flags) {
-    return args.some((arg) => flags.includes(arg));
+    return args.some((arg) => flags.some((flag) => matchesFlag(arg, flag)));
 }
 function hasRiskyPathArg(args) {
     return args.some((arg) => arg === "/" ||

package/dist/lib/observability.d.ts

@@ -37,9 +37,23 @@ export interface RunSummary {
 }
 export interface RunRetirementCandidate {
     activeSubagents: number;
+    childRuns: number;
     descendantSubagents: number;
     run: string;
     stateDir: string;
+    terminalChildRuns: number;
+}
+export interface RunRetirementExecution {
+    action: "stop" | "cancel" | "skip" | "failed";
+    error?: string;
+    run: string;
+    stateDir: string;
+}
+export interface RunRetirementExecutorOptions {
+    attempted?: Set<string>;
+    cancelRun: (candidate: RunRetirementCandidate) => Record<string, unknown>;
+    notify?: (message: string, level: "info" | "warning" | "error") => void;
+    sendStop: (candidate: RunRetirementCandidate) => Promise<unknown>;
 }
 export interface RunTransition {
     from: RunObservedStatus;
@@ -72,6 +86,7 @@ export declare function countRunningSubagents(stateRoot?: string, ownerId?: stri
 export declare function renderSubagentStatus(count: number, frame?: number): string | undefined;
 export declare function renderRunStatus(summary: RunSummary, frame?: number): string | undefined;
 export declare function findRunRetirementCandidates(summary: RunSummary): RunRetirementCandidate[];
+export declare function executeRunRetirements(summary: RunSummary, options: RunRetirementExecutorOptions): Promise<RunRetirementExecution[]>;
 export declare function detectRunTransitions(previous: Map<string, RunObservedStatus>, summary: RunSummary): RunTransition[];
 export declare function pruneRunObservationState(previousStatuses: Map<string, RunObservedStatus>, previousLineCounts: Map<string, number>, summary: RunSummary, terminalRuns?: Iterable<string>): void;
 export declare function detectRunOutboxEvents(previousLineCounts: Map<string, number>, summary: RunSummary): RunOutboxEvent[];

package/dist/lib/observability.js

@@ -4,7 +4,7 @@
  * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as Paths from "./paths.js";
 const TERMINAL = new Set([
@@ -15,6 +15,7 @@ const TERMINAL = new Set([
     "killed",
 ]);
 const PROC_DESCENDANT_SCAN_TTL_MS = 1000;
+const RUN_STATE_DISCOVERY_MAX_DEPTH = 8;
 const procDescendantScanCache = new Map();
 function toNumber(value) {
     const number = Number(value);
@@ -34,6 +35,29 @@ function getUpdatedAt(status) {
             ? status.createdAt
             : undefined;
 }
+function listRunStateDirs(stateRoot, depth = 0, seen = new Set()) {
+    if (!existsSync(stateRoot) || seen.has(stateRoot))
+        return [];
+    seen.add(stateRoot);
+    let entries;
+    try {
+        entries = readdirSync(stateRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const result = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const child = join(stateRoot, entry.name);
+        if (existsSync(join(child, "run.json")))
+            result.push(child);
+        if (depth + 1 < RUN_STATE_DISCOVERY_MAX_DEPTH)
+            result.push(...listRunStateDirs(child, depth + 1, seen));
+    }
+    return result;
+}
 function observeRun(stateDir) {
     try {
         const status = AsyncRuns.getRunStatus(stateDir);
@@ -90,9 +114,8 @@ export function summarizeRuns(stateRoot = Paths.getRunStateRoot(), ownerId) {
             total: 0,
         };
     }
-    const runs = readdirSync(stateRoot, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory())
-        .map((entry) => observeRun(join(stateRoot, entry.name)))
+    const runs = listRunStateDirs(stateRoot)
+        .map((stateDir) => observeRun(stateDir))
         .filter((run) => Boolean(run))
         .filter((run) => ownerId === undefined || run.ownerId === ownerId)
         .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
@@ -148,7 +171,7 @@ function getRunningRunPidMap(stateRoot, ownerId) {
     for (const run of summarizeRunsWithoutSubagents(stateRoot, ownerId).runs) {
         if (run.status !== "running")
             continue;
-        const status = AsyncRuns.getRunStatus(join(stateRoot, run.run));
+        const status = AsyncRuns.getRunStatus(run.stateDir ?? join(stateRoot, run.run));
         const pid = Number(status.pid || 0);
         if (pid > 0)
             pids.set(String(pid), run.run);
@@ -167,9 +190,8 @@ function summarizeRunsWithoutSubagents(stateRoot, ownerId) {
             runs: [],
             total: 0,
         };
-    const runs = readdirSync(stateRoot, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory())
-        .map((entry) => observeRun(join(stateRoot, entry.name)))
+    const runs = listRunStateDirs(stateRoot)
+        .map((stateDir) => observeRun(stateDir))
         .filter((run) => Boolean(run))
         .filter((run) => ownerId === undefined || run.ownerId === ownerId)
         .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
@@ -260,23 +282,86 @@ export function renderSubagentStatus(count, frame = 0) {
 export function renderRunStatus(summary, frame = 0) {
     return renderSubagentStatus(summary.runningSubagents, frame);
 }
+function isNestedStateDir(parent, child) {
+    const path = relative(parent, child);
+    return Boolean(path) && !path.startsWith("..") && !isAbsolute(path);
+}
 export function findRunRetirementCandidates(summary) {
     return summary.runs
-        .filter((run) => {
+        .map((run) => {
         const activeSubagents = Math.max(0, Math.floor(run.activeSubagents ?? 0));
         const descendantSubagents = Math.max(0, Math.floor(run.descendantSubagents ?? 0));
-        return (run.status === "running" &&
-            run.retireWhen === "children_terminal" &&
-            run.stateDir &&
-            activeSubagents + descendantSubagents <= 0);
+        const childRuns = run.stateDir
+            ? summary.runs.filter((child) => child.stateDir !== undefined &&
+                child.stateDir !== run.stateDir &&
+                isNestedStateDir(run.stateDir, child.stateDir))
+            : [];
+        const runningChildRuns = childRuns.filter((child) => child.status === "running").length;
+        return {
+            activeSubagents,
+            childRuns: childRuns.length,
+            descendantSubagents,
+            ready: run.status === "running" &&
+                run.retireWhen === "children_terminal" &&
+                run.stateDir !== undefined &&
+                !run.terminalHandled &&
+                activeSubagents + descendantSubagents + runningChildRuns <= 0,
+            run,
+            terminalChildRuns: childRuns.filter((child) => TERMINAL.has(child.status)).length,
+        };
     })
-        .map((run) => ({
-        activeSubagents: Math.max(0, Math.floor(run.activeSubagents ?? 0)),
-        descendantSubagents: Math.max(0, Math.floor(run.descendantSubagents ?? 0)),
-        run: run.run,
-        stateDir: run.stateDir,
+        .filter((item) => item.ready)
+        .map((item) => ({
+        activeSubagents: item.activeSubagents,
+        childRuns: item.childRuns,
+        descendantSubagents: item.descendantSubagents,
+        run: item.run.run,
+        stateDir: item.run.stateDir,
+        terminalChildRuns: item.terminalChildRuns,
     }));
 }
+export async function executeRunRetirements(summary, options) {
+    const results = [];
+    for (const candidate of findRunRetirementCandidates(summary)) {
+        if (options.attempted?.has(candidate.stateDir)) {
+            results.push({ action: "skip", run: candidate.run, stateDir: candidate.stateDir });
+            continue;
+        }
+        options.attempted?.add(candidate.stateDir);
+        try {
+            await options.sendStop(candidate);
+            options.notify?.(`Retiring actor ${candidate.run} after child runs reached terminal state`, "info");
+            results.push({ action: "stop", run: candidate.run, stateDir: candidate.stateDir });
+            continue;
+        }
+        catch (error) {
+            try {
+                const cancelResult = options.cancelRun(candidate);
+                const cancelled = Boolean(cancelResult.cancelled);
+                options.notify?.(cancelled
+                    ? `Retiring actor ${candidate.run} by cancellation after graceful stop failed`
+                    : `Actor retirement skipped for ${candidate.run}: ${error instanceof Error ? error.message : String(error)}`, cancelled ? "warning" : "error");
+                results.push({
+                    action: cancelled ? "cancel" : "skip",
+                    ...(cancelled ? {} : { error: error instanceof Error ? error.message : String(error) }),
+                    run: candidate.run,
+                    stateDir: candidate.stateDir,
+                });
+            }
+            catch (cancelError) {
+                const message = cancelError instanceof Error ? cancelError.message : String(cancelError);
+                options.notify?.(`Actor retirement failed for ${candidate.run}: ${message}`, "error");
+                results.push({
+                    action: "failed",
+                    error: message,
+                    run: candidate.run,
+                    stateDir: candidate.stateDir,
+                });
+            }
+        }
+    }
+    return results;
+}
 export function detectRunTransitions(previous, summary) {
     const transitions = [];
     for (const run of summary.runs) {