@llblab/pi-actors 0.32.0 → 0.34.0

package/dist/lib/runs-artifacts.js

@@ -0,0 +1,68 @@
+/**
+ * Async run artifact declarations and manifest resolution.
+ * Owns artifact path template expansion and filesystem-backed artifact metadata.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { substituteCommandTemplateToken } from "./command-templates.js";
+export 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;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Async run process control primitives.
+ * Owns platform signal planning, owned-process signalling, and terminal control markers.
+ */
+export interface RunProcessSignalPlan {
+    args?: string[];
+    command?: string;
+    signalTarget: "processGroup" | "process" | "processTree";
+}
+export declare function getRunProcessSignalPlan(pid: number, signal: NodeJS.Signals, runtimePlatform?: NodeJS.Platform): RunProcessSignalPlan;
+export declare function signalOwnedRunProcess(pid: number, signal: NodeJS.Signals): RunProcessSignalPlan;
+export declare function markTerminalHandled(stateDir: string, details: Record<string, unknown>): void;
+export declare function buildTerminalProgress(existing: Record<string, unknown> | undefined, phase: "cancelled" | "killed"): Record<string, unknown>;

package/dist/lib/runs-control.js

@@ -0,0 +1,59 @@
+/**
+ * Async run process control primitives.
+ * Owns platform signal planning, owned-process signalling, and terminal control markers.
+ */
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { writeJsonAtomic } from "./file-state.js";
+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" };
+}
+export 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" };
+    }
+}
+export function markTerminalHandled(stateDir, details) {
+    writeJsonAtomic(join(stateDir, "terminal-handled.json"), {
+        ...details,
+        ts: new Date().toISOString(),
+    });
+}
+export function buildTerminalProgress(existing, phase) {
+    const progress = existing ?? {};
+    const { activeSubagents: _activeSubagents, ...rest } = progress;
+    return {
+        ...rest,
+        completed: typeof progress.completed === "number" ? progress.completed : 0,
+        failures: Array.isArray(progress.failures) ? progress.failures : [],
+        phase,
+        updatedAt: new Date().toISOString(),
+    };
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Async run identity helpers.
+ * Owns run id normalization shared by run lifecycle and retention paths.
+ */
+export declare function safeRunId(value: string | undefined): string;

package/dist/lib/runs-identity.js

@@ -0,0 +1,11 @@
+/**
+ * Async run identity helpers.
+ * Owns run id normalization shared by run lifecycle and retention paths.
+ */
+export 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;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Async run state index.
+ * Owns recursive run-state discovery, index rebuild/read, and status filtering.
+ */
+export interface RunStateIndexEntry {
+    ownerId?: string;
+    recipe?: string;
+    run: string;
+    state_dir: string;
+    status: string;
+    tool?: string;
+    updated_at?: string;
+}
+export type RunStatusReader = (runOrDir: string) => Record<string, unknown>;
+export declare function listRunStateDirs(stateRoot: string, depth?: number, seen?: Set<string>): string[];
+export declare function rebuildRunStateIndex(stateRoot: string, getRunStatus: RunStatusReader): RunStateIndexEntry[];
+export declare function readRunStateIndex(stateRoot: string, readJson: (path: string) => Record<string, unknown> | undefined): RunStateIndexEntry[] | undefined;
+export declare function listRuns(stateRoot: string, getRunStatus: RunStatusReader, readJson: (path: string) => Record<string, unknown> | undefined, statusFilter?: string): Array<Record<string, unknown>>;

package/dist/lib/runs-index.js

@@ -0,0 +1,119 @@
+/**
+ * Async run state index.
+ * Owns recursive run-state discovery, index rebuild/read, and status filtering.
+ */
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { writeJsonAtomic } from "./file-state.js";
+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;
+}
+export function listRunStateDirs(stateRoot, 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: String(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(),
+    };
+}
+export function rebuildRunStateIndex(stateRoot, getRunStatus) {
+    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;
+}
+export function readRunStateIndex(stateRoot, readJson) {
+    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;
+}
+function compactIndexEntry(entry) {
+    return {
+        run: entry.run,
+        state_dir: entry.state_dir,
+        status: entry.status,
+        ...(entry.tool ? { tool: entry.tool } : {}),
+        ...(entry.recipe ? { recipe: entry.recipe } : {}),
+    };
+}
+export function listRuns(stateRoot, getRunStatus, readJson, statusFilter) {
+    if (!existsSync(stateRoot))
+        return [];
+    const indexed = readRunStateIndex(stateRoot, readJson);
+    const entries = indexed ?? rebuildRunStateIndex(stateRoot, getRunStatus);
+    return entries
+        .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
+        .map(compactIndexEntry);
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Async run mailbox state.
+ * Owns durable run inbox records, claim locks, and handler status transitions.
+ */
+export type RunInboxStatus = "queued" | "sent" | "claimed" | "handled" | "failed";
+export type RunInboxMessage = Record<string, unknown> & {
+    id?: string;
+    status?: RunInboxStatus | string;
+};
+export interface ProcessRunInboxResult {
+    claimed: number;
+    failed: number;
+    handled: number;
+}
+export declare function runInboxFile(stateDir: string): string;
+export declare function parseRunInboxLine(line: string): RunInboxMessage | undefined;
+export declare function readRunInboxMessagesFromStateDir(stateDir: string): RunInboxMessage[];
+export declare function updateRunInboxMessageStatusInStateDir(stateDir: string, id: string, nextStatus: RunInboxStatus, metadata?: Record<string, unknown>): boolean;
+export declare function claimRunInboxMessageInStateDir(stateDir: string, owner?: string, statuses?: string[]): RunInboxMessage | undefined;
+export declare function appendRunInboxMessageInStateDir(stateDir: string, record: Record<string, unknown>): string;
+export declare function processRunInboxMessagesInStateDir(stateDir: string, handler: (message: RunInboxMessage) => Promise<void> | void, options?: {
+    limit?: number;
+    owner?: string;
+    statuses?: string[];
+}): Promise<ProcessRunInboxResult>;

package/dist/lib/runs-mailbox.js

@@ -0,0 +1,146 @@
+/**
+ * Async run mailbox state.
+ * Owns durable run inbox records, claim locks, and handler status transitions.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonlFileResilient } from "./state-readers.js";
+const RUN_INBOX_LOCK_TIMEOUT_MS = 5000;
+const STALE_INBOX_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+export function runInboxFile(stateDir) {
+    return join(stateDir, "inbox.jsonl");
+}
+export function parseRunInboxLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readRunInboxMessagesFromStateDir(stateDir) {
+    return readJsonlFileResilient(runInboxFile(stateDir))
+        .records;
+}
+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 > STALE_INBOX_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 writeRunInboxMessages(stateDir, messages) {
+    writeFileSync(runInboxFile(stateDir), messages.length
+        ? `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`
+        : "", "utf8");
+}
+export function updateRunInboxMessageStatusInStateDir(stateDir, id, nextStatus, metadata = {}) {
+    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 claimRunInboxMessageInStateDir(stateDir, owner = "runtime", statuses = ["queued"]) {
+    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 function appendRunInboxMessageInStateDir(stateDir, record) {
+    const id = randomUUID();
+    const ts = new Date().toISOString();
+    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;
+}
+export async function processRunInboxMessagesInStateDir(stateDir, 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 = claimRunInboxMessageInStateDir(stateDir, owner, options.statuses);
+        if (!message?.id)
+            break;
+        result.claimed += 1;
+        try {
+            await handler(message);
+            if (updateRunInboxMessageStatusInStateDir(stateDir, message.id, "handled")) {
+                result.handled += 1;
+            }
+        }
+        catch (error) {
+            if (updateRunInboxMessageStatusInStateDir(stateDir, message.id, "failed", {
+                error: error instanceof Error ? error.message : String(error),
+            })) {
+                result.failed += 1;
+            }
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Async run message delivery.
+ * Owns run control endpoint resolution, inbox enqueueing, wake notification,
+ * transport writes, and delivery receipts.
+ */
+export interface RunControlEndpoint {
+    path: string;
+    type: "fifo" | "mailbox" | "named-pipe";
+}
+export interface SendRunMessageOptions {
+    namedPipeSend?: (path: string, payload: string) => Promise<number>;
+    platform?: NodeJS.Platform;
+}
+export declare function getRunControlEndpoint(status: Record<string, unknown>, stateDir: string): RunControlEndpoint;
+export declare function deliverRunMessage(status: Record<string, unknown>, run: string, stateDir: string, message: string, options?: SendRunMessageOptions): Promise<Record<string, unknown>>;

package/dist/lib/runs-messages.js

@@ -0,0 +1,179 @@
+/**
+ * Async run message delivery.
+ * Owns run control endpoint resolution, inbox enqueueing, wake notification,
+ * transport writes, and delivery receipts.
+ */
+import { closeSync, constants, existsSync, openSync, statSync, writeFileSync, writeSync, } from "node:fs";
+import { createConnection } from "node:net";
+import { join } from "node:path";
+import { markTerminalHandled } from "./runs-control.js";
+import { appendRunInboxMessageInStateDir, updateRunInboxMessageStatusInStateDir, } from "./runs-mailbox.js";
+import { notifyRuntimeWake } from "./runtime-notifier.js";
+export 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) {
+    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" };
+    }
+    return appendRunInboxMessageInStateDir(stateDir, record);
+}
+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" });
+    updateRunInboxMessageStatusInStateDir(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 deliverRunMessage(status, run, stateDir, message, options = {}) {
+    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,
+        });
+    }
+}