@llblab/pi-actors 0.33.0 → 0.34.0

package/dist/lib/async-runs.js

@@ -1,24 +1,27 @@
 /**
- * Command-template async run primitives
- * Zones: async runtime, lifecycle, state files
- * Owns detached run state, observation, log tailing, listing, and cancellation safety
+ * Command-template async run lifecycle facade.
+ * Owns launch, state observation, listing, message/control facade methods, and retention while runs-* subdomains own narrower run internals.
  */
-import { spawn, spawnSync } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
-import { closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, cpSync, readlinkSync, renameSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
-import { createConnection } from "node:net";
-import { platform } from "node:os";
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, writeFileSync, } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { substituteCommandTemplateToken } from "./command-templates.js";
 import { writeJsonAtomic } from "./file-state.js";
-import { readJsonFileResilient, readJsonlFileResilient } from "./state-readers.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;
+import * as RecipesReferences from "./recipes-references.js";
+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 { archiveTerminalRun, pruneTerminalRun } from "./runs-retention.js";
+import { isAlive, isWithinRunnerIdentityGrace, pidMatchesRun, } from "./runs-process.js";
+import * as RunsStart from "./runs-start.js";
+import * as RunsIndex from "./runs-index.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 { readJsonFileResilient } from "./state-readers.js";
 const RUNNER_IDENTITY_GRACE_MS = 5000;
 const DEFAULT_STATE_ROOT = Paths.getRunStateRoot();
 const DEFAULT_RECIPE_ROOT = Paths.getRecipeRoot();
@@ -37,73 +40,8 @@ function asyncRunnerArgv(stateDir) {
         ? [RUNNER_PATH, stateDir]
         : ["--experimental-strip-types", RUNNER_PATH, stateDir];
 }
-function safeRunId(value) {
-    const run = (value || `run-${Date.now()}`).trim();
-    if (!/^[A-Za-z0-9_.-]+$/.test(run))
-        throw new Error("Run id may contain only letters, numbers, dot, underscore, and dash.");
-    return run;
-}
-function resolveArtifactPaths(artifacts, values) {
-    if (!artifacts)
-        return undefined;
-    const resolved = {};
-    for (const [key, value] of Object.entries(artifacts)) {
-        if (!key.trim())
-            continue;
-        if (typeof value === "string") {
-            resolved[key] = substituteCommandTemplateToken(value, values, `recipe artifacts.${key}`);
-        }
-        else if (value &&
-            typeof value === "object" &&
-            typeof value.path === "string") {
-            resolved[key] = {
-                ...value,
-                path: substituteCommandTemplateToken(value.path, values, `recipe artifacts.${key}.path`),
-            };
-        }
-    }
-    return Object.keys(resolved).length > 0 ? resolved : undefined;
-}
-export function resolveArtifactManifest(artifacts) {
-    if (!artifacts)
-        return undefined;
-    const manifest = {};
-    for (const [name, artifact] of Object.entries(artifacts)) {
-        const declaration = typeof artifact === "string" ? { path: artifact } : artifact;
-        if (!declaration?.path)
-            continue;
-        try {
-            const content = readFileSync(declaration.path);
-            manifest[name] = {
-                exists: true,
-                ...(declaration.kind ? { kind: declaration.kind } : {}),
-                ...(declaration.media_type
-                    ? { media_type: declaration.media_type }
-                    : {}),
-                path: declaration.path,
-                ...(declaration.required !== undefined
-                    ? { required: declaration.required }
-                    : {}),
-                sha256: createHash("sha256").update(content).digest("hex"),
-                size: content.byteLength,
-            };
-        }
-        catch {
-            manifest[name] = {
-                exists: false,
-                ...(declaration.kind ? { kind: declaration.kind } : {}),
-                ...(declaration.media_type
-                    ? { media_type: declaration.media_type }
-                    : {}),
-                path: declaration.path,
-                ...(declaration.required !== undefined
-                    ? { required: declaration.required }
-                    : {}),
-            };
-        }
-    }
-    return Object.keys(manifest).length > 0 ? manifest : undefined;
-}
+export { safeRunId } from "./runs-identity.js";
+export { resolveArtifactManifest } from "./runs-artifacts.js";
 function resolveRunTemplate(params) {
     if (!params.template)
         throw new Error("spawn requires file or template.");
@@ -136,18 +74,11 @@ function resolveStateDir(params, run) {
     return resolve(params.state_dir || join(DEFAULT_STATE_ROOT, run));
 }
 function assertNoActiveRunState(stateDir) {
-    const meta = readJson(join(stateDir, "run.json"));
-    if (!meta)
-        return;
-    const pid = Number(meta.pid || 0);
-    const cwd = String(meta.cwd ?? "");
-    if (!pid || !isAlive(pid) || !pidMatchesRun(pid, cwd, stateDir))
-        return;
-    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.`);
+    RunsStart.assertNoActiveRunState(stateDir, readJson, RUNNER_PATH);
 }
 function resolveRecipeFile(file) {
-    return (RecipeReferences.getRecipePath(file, DEFAULT_RECIPE_ROOT) ??
-        RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT));
+    return (RecipesReferences.getRecipePath(file, DEFAULT_RECIPE_ROOT) ??
+        RecipesReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT));
 }
 function isMutableUsageRecipeFile(file) {
     const userRoot = resolve(DEFAULT_RECIPE_ROOT);
@@ -156,9 +87,9 @@ function isMutableUsageRecipeFile(file) {
 }
 function readRecipeFile(file) {
     const path = resolveRecipeFile(file);
-    const raw = RecipeReferences.readRawRecipeConfig(path);
+    const raw = RecipesReferences.readRawRecipeConfig(path);
     const includeActorRecipeContext = raw?.actor_context !== false && raw?.actor_context !== "off";
-    const config = RecipeReferences.readResolvedRecipeConfig(path, [], {
+    const config = RecipesReferences.readResolvedRecipeConfig(path, [], {
         includeActorRecipeContext,
     });
     if (!config) {
@@ -196,104 +127,11 @@ function resolveStartParams(params) {
 function readJson(path) {
     return readJsonFileResilient(path, undefined).value;
 }
-function isAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function pidMatchesRun(pid, cwd, stateDir) {
-    if (platform() !== "linux" || !existsSync(`/proc/${pid}`))
-        return isAlive(pid);
-    try {
-        const procCwd = readlinkSync(`/proc/${pid}/cwd`);
-        const cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8");
-        return (procCwd === resolve(cwd) &&
-            cmdline.includes(RUNNER_PATH) &&
-            cmdline.includes(stateDir));
-    }
-    catch {
-        return false;
-    }
-}
-function isWithinRunnerIdentityGrace(meta) {
-    const createdAt = typeof meta.createdAt === "string" ? Date.parse(meta.createdAt) : NaN;
-    return (Number.isFinite(createdAt) &&
-        Date.now() - createdAt >= 0 &&
-        Date.now() - createdAt <= RUNNER_IDENTITY_GRACE_MS);
-}
-function tailFile(path, lines) {
-    if (!existsSync(path))
-        return "";
-    const content = readFileSync(path, "utf8").trimEnd();
-    if (!content)
-        return "";
-    return content.split("\n").slice(-lines).join("\n");
-}
-function tailLines(path, lines) {
-    const content = tailFile(path, lines);
-    return content ? content.split("\n") : [];
-}
-function getInterruptedRunStatus(stateDir) {
-    const events = readJsonlFileResilient(join(stateDir, "events.jsonl")).records.slice(-200);
-    for (const event of events.reverse()) {
-        if (event.event === "run.kill")
-            return "killed";
-        if (event.event === "run.cancel")
-            return "cancelled";
-    }
-    return undefined;
-}
 function acquireStateStartLock(stateDir) {
-    const lockDir = join(stateDir, ".start.lock");
-    try {
-        mkdirSync(lockDir);
-        writeFileSync(join(lockDir, "owner.json"), `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`, "utf8");
-    }
-    catch (error) {
-        try {
-            const stat = statSync(lockDir);
-            if (Date.now() - stat.mtimeMs > START_LOCK_MAX_AGE_MS) {
-                rmSync(lockDir, { recursive: true, force: true });
-                mkdirSync(lockDir);
-                writeFileSync(join(lockDir, "owner.json"), `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), recovered: true })}\n`, "utf8");
-                return () => rmSync(lockDir, { recursive: true, force: true });
-            }
-        }
-        catch {
-            // Keep the original lock acquisition error below.
-        }
-        throw new Error(`Run state is already being started: ${stateDir}. Retry after the current start finishes.`, { cause: error });
-    }
-    return () => rmSync(lockDir, { recursive: true, force: true });
+    return RunsStart.acquireStateStartLock(stateDir);
 }
 function prepareStateDirForStart(stateDir) {
-    const existing = readJson(join(stateDir, "run.json"));
-    const existingPid = Number(existing?.pid || 0);
-    const existingCwd = typeof existing?.cwd === "string" ? existing.cwd : undefined;
-    const existingResult = readJson(join(stateDir, "result.json"));
-    if (!existingResult &&
-        existingPid &&
-        existingCwd &&
-        isAlive(existingPid) &&
-        pidMatchesRun(existingPid, existingCwd, stateDir)) {
-        throw new Error(`Run is already running: ${String(existing?.run ?? stateDir)}`);
-    }
-    for (const file of [
-        "events.jsonl",
-        "inbox.jsonl",
-        "outbox.jsonl",
-        "progress.json",
-        "result.json",
-        "stderr.log",
-        "stdout.log",
-        "terminal-handled.json",
-    ]) {
-        rmSync(join(stateDir, file), { force: true });
-    }
+    RunsStart.prepareStateDirForStart(stateDir, readJson, RUNNER_PATH);
 }
 export function startRun(params, cwd) {
     const startParams = resolveStartParams(params);
@@ -315,10 +153,10 @@ export function startRun(params, cwd) {
         const includeActorRecipeContext = startParams.actor_context !== false &&
             startParams.actor_context !== "off";
         const recipeContextRecords = recipeFile && includeActorRecipeContext
-            ? RecipeReferences.buildRecipeContextRecords(recipeFile)
+            ? RecipesReferences.buildRecipeContextRecords(recipeFile)
             : undefined;
         if (recipeFile && isMutableUsageRecipeFile(recipeFile)) {
-            RecipeUsage.recordRecipeLaunch(recipeFile, new Date(), startParams.launch_source === "tool" ? "tool" : "spawn");
+            RecipesUsage.recordRecipeLaunch(recipeFile, new Date(), startParams.launch_source === "tool" ? "tool" : "spawn");
         }
         const outFd = openSync(stdout, "a");
         const errFd = openSync(stderr, "a");
@@ -387,63 +225,7 @@ export function startRun(params, cwd) {
         releaseStartLock();
     }
 }
-function normalizeRunOutboxDelivery(value) {
-    return value === "notify" || value === "followup" ? value : "log";
-}
-function normalizeRunOutboxLevel(value) {
-    return value === "warning" || value === "error" ? value : "info";
-}
-function normalizeRunOutboxEvent(raw, run, stateDir, index) {
-    if (!raw || typeof raw !== "object" || Array.isArray(raw))
-        return undefined;
-    const record = raw;
-    const event = typeof record.event === "string" && record.event.trim()
-        ? record.event.trim()
-        : "run.event";
-    const summary = typeof record.summary === "string" && record.summary.trim()
-        ? record.summary.trim()
-        : event;
-    const ts = typeof record.ts === "string" && record.ts.trim()
-        ? record.ts.trim()
-        : new Date(0).toISOString();
-    const id = typeof record.id === "string" && record.id.trim()
-        ? record.id.trim()
-        : `${run}:${index}`;
-    return {
-        ...(record.body !== undefined ? { body: record.body } : {}),
-        ...(typeof record.correlation_id === "string"
-            ? { correlation_id: record.correlation_id }
-            : {}),
-        ...(record.data !== undefined ? { data: record.data } : {}),
-        delivery: normalizeRunOutboxDelivery(record.delivery),
-        ...(record.metadata &&
-            typeof record.metadata === "object" &&
-            !Array.isArray(record.metadata)
-            ? { metadata: record.metadata }
-            : {}),
-        event,
-        ...(typeof record.from === "string" ? { from: record.from } : {}),
-        id,
-        level: normalizeRunOutboxLevel(record.level),
-        ...(typeof record.reply_to === "string"
-            ? { reply_to: record.reply_to }
-            : {}),
-        run,
-        state_dir: stateDir,
-        summary,
-        ...(typeof record.to === "string" ? { to: record.to } : {}),
-        ts,
-        ...(typeof record.type === "string" ? { type: record.type } : {}),
-    };
-}
-export function parseRunOutboxEventLine(line, run, stateDir, index) {
-    try {
-        return normalizeRunOutboxEvent(JSON.parse(line), run, stateDir, index);
-    }
-    catch {
-        return undefined;
-    }
-}
+export { parseRunOutboxEventLine } from "./runs-outbox.js";
 export function getRunStatus(runOrDir) {
     const stateDir = resolve(runOrDir.includes("/")
         ? runOrDir
@@ -451,153 +233,19 @@ export function getRunStatus(runOrDir) {
     const meta = readJson(join(stateDir, "run.json"));
     if (!meta)
         throw new Error(`Run not found: ${runOrDir}`);
-    const result = readJson(join(stateDir, "result.json"));
-    const pid = Number(meta.pid || 0);
-    const aliveOwnedRunner = Boolean(pid &&
-        isAlive(pid) &&
-        (!Array.isArray(meta.argv) ||
-            pidMatchesRun(pid, String(meta.cwd ?? ""), stateDir) ||
-            isWithinRunnerIdentityGrace(meta)));
-    const status = result
-        ? Number(result.code ?? 0) === 0
-            ? "done"
-            : "failed"
-        : aliveOwnedRunner
-            ? "running"
-            : (getInterruptedRunStatus(stateDir) ?? "exited");
-    const terminalHandled = readJson(join(stateDir, "terminal-handled.json"));
-    return {
-        ...meta,
-        eventsFile: join(stateDir, "events.jsonl"),
-        inboxFile: join(stateDir, "inbox.jsonl"),
-        outboxFile: join(stateDir, "outbox.jsonl"),
-        progress: readJson(join(stateDir, "progress.json")) || null,
-        result: result || null,
-        ...(terminalHandled ? { terminal_handled: terminalHandled } : {}),
-        state_dir: String(meta.state_dir ?? stateDir),
-        stderrLog: join(stateDir, "stderr.log"),
-        stdoutLog: join(stateDir, "stdout.log"),
-        status,
-    };
-}
-function matchesStatusFilter(status, filter) {
-    if (!filter || filter === "all")
-        return true;
-    if (filter === "active")
-        return status === "running";
-    if (filter === "terminal")
-        return status !== "running";
-    return status === filter;
+    return buildRunStatus(stateDir, runOrDir, meta, readJson, RUNNER_PATH, RUNNER_IDENTITY_GRACE_MS);
 }
 export function listRunStateDirs(stateRoot = DEFAULT_STATE_ROOT, depth = 0, seen = new Set()) {
-    if (!existsSync(stateRoot) || seen.has(resolve(stateRoot)))
-        return [];
-    seen.add(resolve(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 < 8)
-            result.push(...listRunStateDirs(child, depth + 1, seen));
-    }
-    return result;
-}
-function runIndexPath(stateRoot) {
-    return join(stateRoot, "index.json");
-}
-function indexEntryFromStatus(status) {
-    const progress = status.progress && typeof status.progress === "object"
-        ? status.progress
-        : {};
-    return {
-        ...(typeof status.ownerId === "string" ? { ownerId: status.ownerId } : {}),
-        ...(typeof status.recipe === "string" ? { recipe: status.recipe } : {}),
-        run: String(status.run),
-        state_dir: String(status.state_dir),
-        status: status.status,
-        ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
-        updated_at: typeof progress.updatedAt === "string"
-            ? progress.updatedAt
-            : typeof status.createdAt === "string"
-                ? status.createdAt
-                : new Date(0).toISOString(),
-    };
+    return RunsIndex.listRunStateDirs(stateRoot, depth, seen);
 }
 export function rebuildRunStateIndex(stateRoot = DEFAULT_STATE_ROOT) {
-    mkdirSync(stateRoot, { recursive: true });
-    const entries = listRunStateDirs(stateRoot)
-        .flatMap((stateDir) => {
-        try {
-            return [indexEntryFromStatus(getRunStatus(stateDir))];
-        }
-        catch {
-            return [];
-        }
-    })
-        .sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? ""));
-    writeJsonAtomic(runIndexPath(stateRoot), {
-        entries,
-        rebuilt_at: new Date().toISOString(),
-    });
-    return entries;
+    return RunsIndex.rebuildRunStateIndex(stateRoot, getRunStatus);
 }
 export function readRunStateIndex(stateRoot = DEFAULT_STATE_ROOT) {
-    const index = readJson(runIndexPath(stateRoot));
-    if (!index || typeof index !== "object")
-        return undefined;
-    const entries = index.entries;
-    if (!Array.isArray(entries))
-        return undefined;
-    const valid = entries.filter((entry) => {
-        const record = entry && typeof entry === "object"
-            ? entry
-            : {};
-        return (typeof record.run === "string" &&
-            typeof record.state_dir === "string" &&
-            typeof record.status === "string");
-    });
-    if (valid.some((entry) => !existsSync(join(entry.state_dir, "run.json"))))
-        return undefined;
-    const indexedDirs = new Set(valid.map((entry) => resolve(entry.state_dir)));
-    const stateDirs = listRunStateDirs(stateRoot).map((stateDir) => resolve(stateDir));
-    if (stateDirs.some((stateDir) => !indexedDirs.has(stateDir)))
-        return undefined;
-    return valid;
+    return RunsIndex.readRunStateIndex(stateRoot, readJson);
 }
 export function listRuns(stateRoot = DEFAULT_STATE_ROOT, statusFilter) {
-    if (!existsSync(stateRoot))
-        return [];
-    const indexed = readRunStateIndex(stateRoot);
-    if (indexed) {
-        return indexed
-            .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
-            .map((entry) => ({
-            run: entry.run,
-            state_dir: entry.state_dir,
-            status: entry.status,
-            ...(entry.tool ? { tool: entry.tool } : {}),
-            ...(entry.recipe ? { recipe: entry.recipe } : {}),
-        }));
-    }
-    return rebuildRunStateIndex(stateRoot)
-        .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
-        .map((entry) => ({
-        run: entry.run,
-        state_dir: entry.state_dir,
-        status: entry.status,
-        ...(entry.tool ? { tool: entry.tool } : {}),
-        ...(entry.recipe ? { recipe: entry.recipe } : {}),
-    }));
+    return RunsIndex.listRuns(stateRoot, getRunStatus, readJson, statusFilter);
 }
 export function tailRun(runOrDir, lines = 40) {
     const status = getRunStatus(runOrDir);
@@ -616,55 +264,6 @@ 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) {
-    return readJsonlFileResilient(runInboxFile(stateDir)).records;
-}
-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);
@@ -675,109 +274,22 @@ export function readRunInboxMessages(runOrDir, lines = 40) {
 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();
-    }
+    return updateRunInboxMessageStatusInStateDir(stateDir, id, nextStatus, metadata);
 }
 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();
-    }
+    return claimRunInboxMessageInStateDir(stateDir, owner, statuses);
 }
 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;
+    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 type = event.type || event.event || "run.message";
-    const to = event.to || "coordinator";
-    const metadata = event.metadata ?? {};
-    const requiresResponse = metadata.requires_response === true;
-    const payload = {
-        ...(event.body !== undefined ? { body: event.body } : {}),
-        ...(event.correlation_id ? { correlation_id: event.correlation_id } : {}),
-        ...(event.data !== undefined ? { data: event.data } : {}),
-        delivery: normalizeRunOutboxDelivery(event.delivery ??
-            (requiresResponse
-                ? "followup"
-                : to === "coordinator"
-                    ? "notify"
-                    : "log")),
-        event: type,
-        from: event.from || `run:${run}`,
-        level: normalizeRunOutboxLevel(event.level),
-        ...(event.metadata ? { metadata: event.metadata } : {}),
-        ...(event.reply_to ? { reply_to: event.reply_to } : {}),
-        summary: event.summary || type,
-        to,
-        ts: new Date().toISOString(),
-        type,
-    };
+    const payload = buildRunOutboxEventPayload(run, event);
     const line = `${JSON.stringify(payload)}\n`;
     writeFileSync(join(stateDir, "outbox.jsonl"), line, { flag: "a" });
     return {
@@ -788,115 +300,6 @@ export function appendRunOutboxEvent(runOrDir, event) {
         state_dir: stateDir,
     };
 }
-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);
@@ -906,130 +309,18 @@ export async function sendRunMessage(runOrDir, message, options = {}) {
     const pid = Number(status.pid || 0);
     if (!pid || !isAlive(pid))
         throw new Error(`Run pid is not alive: ${run}`);
-    if (!pidMatchesRun(pid, String(status.cwd), stateDir) &&
-        !isWithinRunnerIdentityGrace(status))
+    if (!pidMatchesRun(pid, String(status.cwd), stateDir, RUNNER_PATH) &&
+        !isWithinRunnerIdentityGrace(status, RUNNER_IDENTITY_GRACE_MS))
         throw new Error(`Run pid owner mismatch: ${run}`);
-    const endpoint = getRunControlEndpoint(status, stateDir);
-    const payload = message.endsWith("\n") ? message : `${message}\n`;
-    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,
-            inbox_id: inboxId,
-            queued: true,
-            run,
-            sent: true,
-            state_dir: stateDir,
-        };
-    }
-    try {
-        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,
-                inbox_id: inboxId,
-                run,
-                sent: true,
-                state_dir: stateDir,
-            };
-        }
-        const bytes = await sendRunMessageToNamedPipe(endpoint, payload, options.namedPipeSend);
-        writeRunMessageReceipt(stateDir, message, bytes, inboxId);
-        return {
-            ...(wake ?? {}),
-            bytes,
-            control: endpoint.path,
-            control_path: endpoint.path,
-            control_type: endpoint.type,
-            inbox_id: inboxId,
-            run,
-            sent: true,
-            state_dir: stateDir,
-        };
-    }
-    catch (error) {
-        const deliveryError = error instanceof Error ? error.message : String(error);
-        throw Object.assign(new Error(`Run control endpoint is not ready: ${endpoint.path}: ${deliveryError}`), {
-            control_path: endpoint.path,
-            control_type: endpoint.type,
-            delivery_error: deliveryError,
-            inbox_id: inboxId,
-            queued: true,
-            run,
-            sent: false,
-            state_dir: stateDir,
-        });
-    }
-}
-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" };
-    }
-    catch {
-        process.kill(pid, signal);
-        return { signalTarget: "process" };
-    }
-}
-function markTerminalHandled(stateDir, details) {
-    writeJsonAtomic(join(stateDir, "terminal-handled.json"), {
-        ...details,
-        ts: new Date().toISOString(),
-    });
+    return deliverRunMessage(status, run, stateDir, message, options);
 }
+export { getRunProcessSignalPlan } from "./runs-control.js";
 function markTerminalProgress(stateDir, phase) {
     const existing = readJson(join(stateDir, "progress.json"));
     const progress = existing && typeof existing === "object" && !Array.isArray(existing)
         ? existing
-        : {};
-    const { activeSubagents: _activeSubagents, ...rest } = progress;
-    writeJsonAtomic(join(stateDir, "progress.json"), {
-        ...rest,
-        completed: typeof progress.completed === "number" ? progress.completed : 0,
-        failures: Array.isArray(progress.failures) ? progress.failures : [],
-        phase,
-        updatedAt: new Date().toISOString(),
-    });
+        : undefined;
+    writeJsonAtomic(join(stateDir, "progress.json"), buildTerminalProgress(progress, phase));
 }
 function stopRun(runOrDir, signal, event) {
     const status = getRunStatus(runOrDir);
@@ -1039,7 +330,7 @@ function stopRun(runOrDir, signal, event) {
         return { stopped: false, reason: "not running", status };
     if (!pid || !isAlive(pid))
         return { stopped: false, reason: "pid not alive", status };
-    if (!pidMatchesRun(pid, String(status.cwd), stateDir)) {
+    if (!pidMatchesRun(pid, String(status.cwd), stateDir, RUNNER_PATH)) {
         return { stopped: false, reason: "pid owner mismatch", status };
     }
     const signalResult = signalOwnedRunProcess(pid, signal);
@@ -1064,54 +355,11 @@ function assertTerminalRun(runOrDir) {
     }
     return status;
 }
-function archivePathFor(run, stateDir) {
-    const archiveRoot = join(dirname(stateDir), "archived");
-    mkdirSync(archiveRoot, { recursive: true });
-    return join(archiveRoot, `${safeRunId(run)}-${new Date().toISOString().replace(/[:.]/g, "-")}`);
-}
 export function archiveRun(runOrDir) {
-    const status = assertTerminalRun(runOrDir);
-    const stateDir = String(status.state_dir);
-    const run = String(status.run ?? basename(stateDir));
-    const archiveDir = archivePathFor(run, stateDir);
-    renameSync(stateDir, archiveDir);
-    mkdirSync(stateDir, { recursive: true });
-    const tombstone = {
-        archived: true,
-        archive_dir: archiveDir,
-        original_state_dir: stateDir,
-        run,
-        status: status.status,
-        ts: new Date().toISOString(),
-    };
-    writeJsonAtomic(join(stateDir, "archive-tombstone.json"), tombstone);
-    return tombstone;
+    return archiveTerminalRun(assertTerminalRun(runOrDir));
 }
 export function pruneRun(runOrDir, options = {}) {
-    const status = assertTerminalRun(runOrDir);
-    const stateDir = String(status.state_dir);
-    const run = String(status.run ?? basename(stateDir));
-    const manifest = resolveArtifactManifest(status.artifacts);
-    const preserved = {};
-    if (options.preserveArtifacts && manifest) {
-        const preserveRoot = join(dirname(stateDir), "preserved-artifacts", safeRunId(run));
-        mkdirSync(preserveRoot, { recursive: true });
-        for (const [name, artifact] of Object.entries(manifest)) {
-            if (!artifact.exists)
-                continue;
-            const target = join(preserveRoot, basename(artifact.path));
-            cpSync(artifact.path, target, { force: true });
-            preserved[name] = target;
-        }
-    }
-    rmSync(stateDir, { recursive: true, force: true });
-    return {
-        pruned: true,
-        preserved_artifacts: preserved,
-        run,
-        state_dir: stateDir,
-        ts: new Date().toISOString(),
-    };
+    return pruneTerminalRun(assertTerminalRun(runOrDir), options);
 }
 export function killRun(runOrDir) {
     const result = stopRun(runOrDir, "SIGKILL", "run.kill");