@nettee/beacon 0.5.0 → 0.6.0

package/deploy/io.nettee.beacon.plist.example

@@ -18,6 +18,18 @@
     <key>SuccessfulExit</key>
     <false/>
   </dict>
+  <!--
+    Beacon 0.6+ spawns Pi in a detached worker (new session / PGID), so a
+    plain kill -9 of the daemon should not take in-flight Pi with it.
+    AbandonProcessGroup is optional belt-and-suspenders on Mini LaunchDaemon:
+    if true, launchd will not kill leftover processes that share the job PGID
+    when the job exits. Prefer relying on code-side detach; set this only if
+    you still see Pi die with the daemon after upgrading to 0.6+.
+  -->
+  <!--
+  <key>AbandonProcessGroup</key>
+  <true/>
+  -->
   <key>ThrottleInterval</key>
   <integer>10</integer>
   <key>Umask</key>

package/dist/daemon/dashboard/profiles.js

@@ -37,6 +37,8 @@ const skillsSchema = z
     paths: z.array(z.string().trim().min(1)).default([]),
 })
     .strict();
+const positiveInteger = z.number().int().positive().safe();
+const nonNegativeInteger = z.number().int().nonnegative().safe();
 const profileDocumentSchema = z
     .object({
     playbook: z.string().min(1),
@@ -47,6 +49,10 @@ const profileDocumentSchema = z
         id: z.string().min(1),
     })
         .strict(),
+    /** Optional per-Profile active Run limit; omit → host default. */
+    max_concurrent: positiveInteger.optional(),
+    /** Optional per-Profile queue depth; omit → host `runs.max_queued`. */
+    max_queued: nonNegativeInteger.optional(),
     admin: adminDestinationSchema.optional(),
     schedules: z.array(scheduleSchema).default([]),
     listener: z
@@ -78,6 +84,8 @@ function toDetailView(profileId, document) {
         playbook: document.playbook,
         runtime: document.runtime,
         model: document.model,
+        maxConcurrent: document.max_concurrent ?? null,
+        maxQueued: document.max_queued ?? null,
         admin: document.admin ? { chatId: document.admin.chat_id } : null,
         schedules: document.schedules.map((schedule) => ({
             id: schedule.id,

package/dist/daemon/domain/types.d.ts

@@ -99,6 +99,14 @@ export type ObservabilityFeedbackRecord = {
     submittedAt: string;
 };
 export type DeliveryContent = TextReplyContent | CardContent;
+/** Detached Pi worker handle persisted so a new Beacon daemon can adopt the Run. */
+export type AgentRuntimeRecord = {
+    workerPid: number;
+    lifecycleDirectory: string;
+    runToken: string;
+    supervisorLeasePath: string;
+    orphanAfterMs: number;
+};
 export type RunRecord = {
     runId: string;
     /** Pi session ID. Absent only on records written before session persistence. */
@@ -115,6 +123,8 @@ export type RunRecord = {
     promptDigest: string;
     /** Full `--system-prompt` text sent to Pi. Absent on records written before this field. */
     systemPrompt?: string | undefined;
+    /** Present while a detached Pi worker owns the in-flight Run. */
+    agent?: AgentRuntimeRecord | undefined;
     failure?: Failure | undefined;
 };
 export type FinalOutcomeRecord = {

package/dist/daemon/outcome/server.d.ts

@@ -20,4 +20,6 @@ export type OutcomeServer = OutcomeSink & {
 };
 export declare function startOutcomeServer(options?: {
     maxRequestBytes?: number | undefined;
+    /** Stable directory (e.g. ~/.beacon/state/outcomes). Ephemeral /tmp when omitted. */
+    directory?: string | undefined;
 }): Promise<OutcomeServer>;

package/dist/daemon/outcome/server.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { mkdtemp, rm } from "node:fs/promises";
+import { chmod, mkdir, mkdtemp, rm } from "node:fs/promises";
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -12,8 +12,14 @@ export async function startOutcomeServer(options = {}) {
     if (!Number.isSafeInteger(maxRequestBytes) || maxRequestBytes <= 0) {
         throw new Error("Outcome request limit must be a positive integer");
     }
-    const directory = await mkdtemp(join(tmpdir(), "beacon-outcomes-"));
+    const ephemeral = options.directory === undefined;
+    const directory = options.directory ?? (await mkdtemp(join(tmpdir(), "beacon-outcomes-")));
+    if (!ephemeral) {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await chmod(directory, 0o700);
+    }
     const socketPath = join(directory, "outcomes.sock");
+    await rm(socketPath, { force: true });
     const submissions = new Map();
     const server = createServer((socket) => {
         socket.setEncoding("utf8");
@@ -99,6 +105,7 @@ export async function startOutcomeServer(options = {}) {
             resolve();
         });
     });
+    await chmod(socketPath, 0o600).catch(() => undefined);
     return {
         openRun() {
             const runToken = randomBytes(32).toString("base64url");
@@ -139,7 +146,10 @@ export async function startOutcomeServer(options = {}) {
             await new Promise((resolve, reject) => {
                 server.close((error) => (error ? reject(error) : resolve()));
             });
-            await rm(directory, { recursive: true, force: true });
+            await rm(socketPath, { force: true });
+            if (ephemeral) {
+                await rm(directory, { recursive: true, force: true });
+            }
         },
     };
 }

package/dist/daemon/outcome/submit.d.ts

@@ -1,5 +1,12 @@
 import type { FinalOutcomeContent } from "../domain/types.js";
 import { completeOutcome, mergeOutcome, type OutcomePatch } from "./content.js";
-export declare function submitOutcome(socketPath: string, runToken: string, outcome: OutcomePatch | FinalOutcomeContent): Promise<void>;
+/**
+ * Submit a Final Outcome patch. Retries briefly on connection errors so a
+ * detached Pi worker can survive a short Beacon restart window.
+ */
+export declare function submitOutcome(socketPath: string, runToken: string, outcome: OutcomePatch | FinalOutcomeContent, options?: {
+    retries?: number | undefined;
+    retryDelayMs?: number | undefined;
+}): Promise<void>;
 export declare function submitOutcomeFromCli(): Promise<void>;
 export { completeOutcome, mergeOutcome };

package/dist/daemon/outcome/submit.js

@@ -1,7 +1,6 @@
 import { createConnection } from "node:net";
 import { completeOutcome, mergeOutcome, parseOutcomePatch, } from "./content.js";
-export async function submitOutcome(socketPath, runToken, outcome) {
-    const patch = parseOutcomePatch(outcome);
+async function submitOutcomeOnce(socketPath, runToken, patch) {
     await new Promise((resolve, reject) => {
         const socket = createConnection(socketPath);
         socket.setEncoding("utf8");
@@ -32,6 +31,38 @@ export async function submitOutcome(socketPath, runToken, outcome) {
         });
     });
 }
+function isRetryableSubmitError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = "code" in error ? String(error.code) : "";
+    return (code === "ENOENT" ||
+        code === "ECONNREFUSED" ||
+        code === "ECONNRESET" ||
+        code === "EPIPE");
+}
+/**
+ * Submit a Final Outcome patch. Retries briefly on connection errors so a
+ * detached Pi worker can survive a short Beacon restart window.
+ */
+export async function submitOutcome(socketPath, runToken, outcome, options = {}) {
+    const patch = parseOutcomePatch(outcome);
+    const retries = options.retries ?? 40;
+    const retryDelayMs = options.retryDelayMs ?? 500;
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt += 1) {
+        try {
+            await submitOutcomeOnce(socketPath, runToken, patch);
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === retries || !isRetryableSubmitError(error))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+        }
+    }
+    throw lastError;
+}
 export async function submitOutcomeFromCli() {
     const socketPath = process.env.BEACON_OUTCOME_SOCKET;
     const runToken = process.env.BEACON_RUN_TOKEN;

package/dist/daemon/run/create-pi-orchestrator.d.ts

@@ -4,7 +4,9 @@ import type { OutcomeServer } from "../outcome/server.js";
 import type { TriggerStore } from "../state/trigger-store.js";
 import { type DeliveryAdapter, RunOrchestrator } from "./orchestrator.js";
 import type { RunQueue } from "./queue.js";
-export type PiOrchestratorConfig = Pick<GlobalConfig, "pi" | "runs">;
+export type PiOrchestratorConfig = Pick<GlobalConfig, "pi" | "runs"> & {
+    homeDirectory: string;
+};
 export declare function createPiRunOrchestrator(options: {
     beaconCliPath: string;
     config: PiOrchestratorConfig;
@@ -14,4 +16,7 @@ export declare function createPiRunOrchestrator(options: {
     queue: RunQueue;
     outcomes: OutcomeServer;
     delivery: DeliveryAdapter;
+    /** Override for tests; production always detaches. */
+    detachRuns?: boolean | undefined;
+    orphanAfterMs?: number | undefined;
 }): RunOrchestrator;

package/dist/daemon/run/create-pi-orchestrator.js

@@ -1,6 +1,10 @@
+import { join } from "node:path";
 import { runPiAgent } from "../runtime/pi-rpc.js";
+import { DEFAULT_ORPHAN_AFTER_MS } from "../runtime/supervisor-lease.js";
 import { RunOrchestrator } from "./orchestrator.js";
 export function createPiRunOrchestrator(options) {
+    const detachRuns = options.detachRuns ?? true;
+    const supervisorLeasePath = join(options.config.homeDirectory, "state", "supervisor.lease");
     return new RunOrchestrator({
         profile: options.profile,
         store: options.store,
@@ -18,5 +22,20 @@ export function createPiRunOrchestrator(options) {
             runtimeEnvironment: options.runtimeEnvironment,
         }),
         delivery: options.delivery,
+        ...(detachRuns
+            ? {
+                detached: {
+                    supervisorLeasePath,
+                    orphanAfterMs: options.orphanAfterMs ?? DEFAULT_ORPHAN_AFTER_MS,
+                    executable: options.config.pi.executable,
+                    timeoutMs: options.config.runs.timeoutSeconds * 1_000,
+                    terminateGraceMs: options.config.runs.terminateGraceSeconds * 1_000,
+                    environment: {
+                        PI_CODING_AGENT_DIR: options.config.pi.codingAgentDirectory,
+                    },
+                    runtimeEnvironment: options.runtimeEnvironment,
+                },
+            }
+            : {}),
     });
 }

package/dist/daemon/run/orchestrator.d.ts

@@ -9,6 +9,16 @@ export type DeliveryAdapter = {
         providerRequestId?: string | undefined;
     }>;
 };
+export type DetachedRunOptions = {
+    supervisorLeasePath: string;
+    orphanAfterMs?: number | undefined;
+    executable?: string | undefined;
+    timeoutMs?: number | undefined;
+    terminateGraceMs?: number | undefined;
+    environment?: NodeJS.ProcessEnv | undefined;
+    runtimeEnvironment?: NodeJS.ProcessEnv | undefined;
+    workerMainPath?: string | undefined;
+};
 export type RunOrchestratorOptions = {
     profile: Profile;
     store: TriggerStore;
@@ -18,6 +28,11 @@ export type RunOrchestratorOptions = {
     runAgent: AgentRuntimeRunner;
     delivery: DeliveryAdapter;
     sessionDirectory: string;
+    /**
+     * When set, Pi runs in a detached worker process that can outlive Beacon
+     * restarts. Tests omit this and keep the in-process `runAgent` path.
+     */
+    detached?: DetachedRunOptions | undefined;
     now?: (() => Date) | undefined;
     id?: (() => string) | undefined;
 };
@@ -55,7 +70,11 @@ export declare class RunOrchestrator {
     private deliverField;
     private deliverOutcome;
     private fail;
+    private finalizeWorkerCompletion;
+    private executeDetached;
+    private executeInProcess;
     private execute;
+    private adoptDetachedRun;
     process(triggerKey: string, normalize: () => Promise<TriggerInput>): Promise<void>;
     recover(): Promise<void>;
 }

package/dist/daemon/run/orchestrator.js

@@ -1,8 +1,10 @@
-import { randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import { isAbsolute, join } from "node:path";
 import { isMissingReplyOutcomeError, MISSING_REPLY_OUTCOME_SUMMARY, } from "../outcome/content.js";
 import { inboundOutOfRoleReply } from "../outcome/instructions.js";
 import { PiRuntimeError, RUNTIME_TIMEOUT_OUTCOME_MISSING_NOTE, RUNTIME_TIMEOUT_OUTCOME_SUBMITTED_NOTE, } from "../runtime/pi-rpc.js";
+import { isWorkerAdoptable, signalWorker, spawnDetachedPiWorker, waitForWorkerCompletion, } from "../runtime/pi-worker-lifecycle.js";
+import { DEFAULT_ORPHAN_AFTER_MS } from "../runtime/supervisor-lease.js";
 import { agentSystemPromptTrigger, buildAgentSystemPrompt, profilePromptDigest, } from "../runtime/system-prompt.js";
 function promptFor(input) {
     if (input.kind === "event") {
@@ -302,6 +304,7 @@ export class RunOrchestrator {
                 state: "failed",
                 finishedAt: this.timestamp(),
                 failure,
+                agent: undefined,
             },
             finalOutcome: {
                 origin: "beacon_failure",
@@ -315,32 +318,112 @@ export class RunOrchestrator {
         }));
         await this.deliverOutcome(triggerKey);
     }
-    async execute(triggerKey, input, runId) {
-        const record = await this.options.store.update(triggerKey, (current) => {
-            if (!current.run) {
-                throw new Error(`Cannot execute Trigger ${triggerKey} without a Run`);
-            }
-            const session = current.run.sessionId && current.run.sessionPath
-                ? {
-                    sessionId: current.run.sessionId,
-                    sessionPath: current.run.sessionPath,
+    async finalizeWorkerCompletion(triggerKey, input, runId, notifyTarget, completion) {
+        if (completion.ok) {
+            const outcome = normalizeAgentOutcome(input, completion.outcome, notifyTarget);
+            const updated = await this.options.store.update(triggerKey, (current) => {
+                // Exactly-once terminal write: first waiter wins.
+                if (current.finalOutcome ||
+                    current.run?.state === "succeeded" ||
+                    current.run?.state === "failed") {
+                    return current;
                 }
-                : {
-                    sessionId: current.run.runId,
-                    sessionPath: join(this.options.sessionDirectory, this.options.profile.id, current.run.runId),
+                return {
+                    ...current,
+                    run: {
+                        ...current.run,
+                        state: "succeeded",
+                        finishedAt: this.timestamp(),
+                        provider: completion.result.provider,
+                        model: completion.result.model,
+                        agent: undefined,
+                    },
+                    finalOutcome: {
+                        origin: "agent",
+                        content: outcome,
+                        submittedAt: this.timestamp(),
+                    },
+                    ...(completion.feedback ? { feedback: completion.feedback } : {}),
+                    ...(completion.observabilityFeedback
+                        ? { observabilityFeedback: completion.observabilityFeedback }
+                        : {}),
                 };
-            const systemPrompt = this.agentSystemPrompt(this.triggerFor(current, input), current.run.systemPrompt);
-            return {
-                ...current,
-                run: {
-                    ...current.run,
-                    ...session,
-                    state: "starting",
-                    startedAt: this.timestamp(),
-                    systemPrompt,
-                },
-            };
+            });
+            if (updated.run?.state === "succeeded" && updated.finalOutcome) {
+                await this.deliverOutcome(triggerKey);
+            }
+            return;
+        }
+        let failError = new Error(completion.error.message);
+        let code = completion.error.code === "orphan_abandoned" ||
+            completion.error.code === "worker_failed"
+            ? "runtime_exit_failed"
+            : completion.error.code;
+        if (completion.error.code === "runtime_timeout") {
+            const note = completion.hasReply
+                ? RUNTIME_TIMEOUT_OUTCOME_SUBMITTED_NOTE
+                : RUNTIME_TIMEOUT_OUTCOME_MISSING_NOTE;
+            failError = new PiRuntimeError("runtime_timeout", `${completion.error.message}. ${note}`);
+            code = "runtime_timeout";
+        }
+        else if (completion.error.code === "orphan_abandoned") {
+            code = "service_interrupted";
+            failError = new Error(completion.error.message);
+        }
+        else if (completion.error.code === "runtime_spawn_failed" ||
+            completion.error.code === "runtime_protocol_error" ||
+            completion.error.code === "runtime_exit_failed") {
+            failError = new PiRuntimeError(completion.error.code, completion.error.message);
+        }
+        await this.fail(triggerKey, runId, code, failError, completion.feedback, completion.observabilityFeedback);
+    }
+    async executeDetached(triggerKey, input, runId, record) {
+        const detached = this.options.detached;
+        const sessionPath = record.run.sessionPath;
+        const lifecycleDirectory = join(sessionPath, "beacon-runtime");
+        const runToken = randomBytes(32).toString("base64url");
+        const orphanAfterMs = detached.orphanAfterMs ?? DEFAULT_ORPHAN_AFTER_MS;
+        const handle = await spawnDetachedPiWorker(lifecycleDirectory, {
+            prompt: promptFor(input),
+            playbook: this.options.profile.playbook,
+            provider: this.options.profile.model.provider,
+            model: this.options.profile.model.id,
+            systemPrompt: record.run.systemPrompt,
+            session: {
+                id: record.run.sessionId,
+                path: sessionPath,
+                name: `Beacon ${this.options.profile.id} ${runId}`,
+            },
+            ...(this.options.profile.skills
+                ? { skills: this.options.profile.skills }
+                : {}),
+        }, {
+            beaconCliPath: this.options.beaconCliPath,
+            runToken,
+            supervisorLeasePath: detached.supervisorLeasePath,
+            orphanAfterMs,
+            executable: detached.executable,
+            timeoutMs: detached.timeoutMs,
+            terminateGraceMs: detached.terminateGraceMs,
+            environment: detached.environment,
+            runtimeEnvironment: detached.runtimeEnvironment,
+            workerMainPath: detached.workerMainPath,
         });
+        const agent = {
+            workerPid: handle.workerPid,
+            lifecycleDirectory: handle.lifecycleDirectory,
+            runToken: handle.runToken,
+            supervisorLeasePath: handle.supervisorLeasePath,
+            orphanAfterMs: handle.orphanAfterMs,
+        };
+        await this.options.store.update(triggerKey, (current) => ({
+            ...current,
+            run: { ...current.run, state: "running", agent },
+        }));
+        const completion = await waitForWorkerCompletion(lifecycleDirectory);
+        await this.finalizeWorkerCompletion(triggerKey, input, runId, record.notifyTarget, completion);
+    }
+    async executeInProcess(triggerKey, input, runId, record) {
         await this.options.store.update(triggerKey, (current) => ({
             ...current,
             run: { ...current.run, state: "running" },
@@ -413,6 +496,65 @@ export class RunOrchestrator {
             await this.fail(triggerKey, runId, code, failError, submitted, submittedObservability, settle);
         }
     }
+    async execute(triggerKey, input, runId) {
+        const record = await this.options.store.update(triggerKey, (current) => {
+            if (!current.run) {
+                throw new Error(`Cannot execute Trigger ${triggerKey} without a Run`);
+            }
+            const session = current.run.sessionId && current.run.sessionPath
+                ? {
+                    sessionId: current.run.sessionId,
+                    sessionPath: current.run.sessionPath,
+                }
+                : {
+                    sessionId: current.run.runId,
+                    sessionPath: join(this.options.sessionDirectory, this.options.profile.id, current.run.runId),
+                };
+            const systemPrompt = this.agentSystemPrompt(this.triggerFor(current, input), current.run.systemPrompt);
+            return {
+                ...current,
+                run: {
+                    ...current.run,
+                    ...session,
+                    state: "starting",
+                    startedAt: this.timestamp(),
+                    systemPrompt,
+                },
+            };
+        });
+        if (this.options.detached) {
+            await this.executeDetached(triggerKey, input, runId, record);
+            return;
+        }
+        await this.executeInProcess(triggerKey, input, runId, record);
+    }
+    async adoptDetachedRun(triggerKey, agent) {
+        const latest = await this.record(triggerKey);
+        if (!latest.run || !latest.input) {
+            await this.fail(triggerKey, latest.run?.runId ?? `run_${this.id()}`, "service_interrupted", "Service restarted while Run was active");
+            return;
+        }
+        if (!(await isWorkerAdoptable(agent))) {
+            signalWorker(agent.workerPid, "SIGTERM");
+            await this.fail(triggerKey, latest.run.runId, "service_interrupted", "Service restarted while Run was active");
+            return;
+        }
+        console.log(`[beacon] adopting detached Pi worker pid=${agent.workerPid} run_id=${latest.run.runId}`);
+        const completion = await waitForWorkerCompletion(agent.lifecycleDirectory);
+        // Exactly-once: skip if another waiter already wrote terminal state / Outcome.
+        const after = await this.record(triggerKey);
+        if (after.finalOutcome ||
+            after.run?.state === "succeeded" ||
+            after.run?.state === "failed") {
+            if (after.finalOutcome &&
+                (after.delivery?.state === "pending" ||
+                    after.notifyDelivery?.state === "pending")) {
+                await this.deliverOutcome(triggerKey, false);
+            }
+            return;
+        }
+        await this.finalizeWorkerCompletion(triggerKey, latest.input, latest.run.runId, latest.notifyTarget, completion);
+    }
     async process(triggerKey, normalize) {
         const runId = `run_${this.id()}`;
         let input;
@@ -483,6 +625,25 @@ export class RunOrchestrator {
                 continue;
             }
             if (latest.run?.state === "starting" || latest.run?.state === "running") {
+                const agent = latest.run.agent;
+                if (agent && this.options.detached) {
+                    if (latest.input?.kind === "event") {
+                        await this.options.queue.enqueueWhenAvailable(this.options.profile.id, () => this.adoptDetachedRun(latest.triggerKey, agent));
+                    }
+                    else {
+                        const queued = this.options.queue.enqueue(this.options.profile.id, () => this.adoptDetachedRun(latest.triggerKey, agent));
+                        if (!queued.accepted) {
+                            signalWorker(agent.workerPid, "SIGTERM");
+                            await this.fail(latest.triggerKey, latest.run.runId, "capacity_exceeded", "Run queue capacity exceeded while adopting detached Pi worker");
+                        }
+                        else {
+                            await queued.completion;
+                        }
+                    }
+                    continue;
+                }
+                if (agent)
+                    signalWorker(agent.workerPid, "SIGTERM");
                 await this.fail(latest.triggerKey, latest.run.runId, "service_interrupted", "Service restarted while Run was active");
                 continue;
             }

package/dist/daemon/runtime/pi-rpc.d.ts

@@ -34,6 +34,8 @@ export type PiRuntimeOptions = {
     runtimeEnvironment?: NodeJS.ProcessEnv | undefined;
     terminateGraceMs?: number | undefined;
     maxFrameBytes?: number | undefined;
+    /** When aborted, Beacon stops Pi (SIGTERM → SIGKILL) like a hard timeout. */
+    signal?: AbortSignal | undefined;
 };
 export declare class PiRuntimeError extends Error {
     readonly code: "runtime_spawn_failed" | "runtime_protocol_error" | "runtime_timeout" | "runtime_exit_failed";

package/dist/daemon/runtime/pi-rpc.js

@@ -324,6 +324,9 @@ export async function runPiAgent(request, options = {}) {
     if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
         throw new Error("Pi RPC frame limit must be a positive integer");
     }
+    if (options.signal?.aborted) {
+        throw new PiRuntimeError("runtime_exit_failed", "Pi Run aborted before spawn");
+    }
     const child = spawn(executable, buildArguments(request), {
         cwd: request.playbook,
         env: buildPiEnvironment(request.outcome, options.environment, options.runtimeEnvironment),
@@ -345,8 +348,13 @@ export async function runPiAgent(request, options = {}) {
                     return;
                 finished = true;
                 clearTimeout(timer);
+                options.signal?.removeEventListener("abort", onAbort);
                 reject(error);
             };
+            const onAbort = () => {
+                fail(new PiRuntimeError("runtime_exit_failed", "Pi Run aborted by Beacon supervisor (orphan safety or cancel)"));
+            };
+            options.signal?.addEventListener("abort", onAbort, { once: true });
             const timer = setTimeout(() => fail(new PiRuntimeError("runtime_timeout", formatRuntimeTimeoutMessage(timeoutMs, stderr))), timeoutMs);
             const handleFrame = (line) => {
                 if (finished)
@@ -400,6 +408,7 @@ export async function runPiAgent(request, options = {}) {
                     };
                     finished = true;
                     clearTimeout(timer);
+                    options.signal?.removeEventListener("abort", onAbort);
                     resolve(result);
                 }
                 catch (error) {

package/dist/daemon/runtime/pi-worker-lifecycle.d.ts

@@ -0,0 +1,92 @@
+import type { ProfileSkills } from "../config/profile.js";
+import type { FeedbackRecord, FinalOutcomeContent, ObservabilityFeedbackRecord } from "../domain/types.js";
+import type { PiRunResult, PiRuntimeOptions } from "./pi-rpc.js";
+export type PiWorkerRequest = {
+    prompt: string;
+    playbook: string;
+    provider?: string | undefined;
+    model?: string | undefined;
+    systemPrompt?: string | undefined;
+    session?: {
+        id: string;
+        path: string;
+        name?: string | undefined;
+    } | undefined;
+    skills?: ProfileSkills | undefined;
+    beaconCliPath: string;
+    runToken: string;
+    supervisorLeasePath: string;
+    orphanAfterMs?: number | undefined;
+    executable?: string | undefined;
+    timeoutMs?: number | undefined;
+    terminateGraceMs?: number | undefined;
+    maxFrameBytes?: number | undefined;
+    environment?: NodeJS.ProcessEnv | undefined;
+    runtimeEnvironment?: NodeJS.ProcessEnv | undefined;
+};
+export type PiWorkerCompletion = {
+    ok: true;
+    result: PiRunResult;
+    outcome: FinalOutcomeContent;
+    feedback?: FeedbackRecord | undefined;
+    observabilityFeedback?: ObservabilityFeedbackRecord | undefined;
+    hasReply: boolean;
+    finishedAt: string;
+} | {
+    ok: false;
+    error: {
+        code: "runtime_spawn_failed" | "runtime_protocol_error" | "runtime_timeout" | "runtime_exit_failed" | "orphan_abandoned" | "worker_failed";
+        message: string;
+    };
+    hasReply: boolean;
+    feedback?: FeedbackRecord | undefined;
+    observabilityFeedback?: ObservabilityFeedbackRecord | undefined;
+    finishedAt: string;
+};
+export type AgentRuntimeHandle = {
+    workerPid: number;
+    lifecycleDirectory: string;
+    runToken: string;
+    supervisorLeasePath: string;
+    orphanAfterMs: number;
+};
+export declare function lifecyclePaths(lifecycleDirectory: string): {
+    request: string;
+    completion: string;
+    heartbeat: string;
+    pid: string;
+    outcomeSocket: string;
+};
+export declare function prepareLifecycleDirectory(lifecycleDirectory: string): Promise<void>;
+export declare function writeWorkerRequest(lifecycleDirectory: string, request: PiWorkerRequest): Promise<void>;
+export declare function readWorkerRequest(lifecycleDirectory: string): Promise<PiWorkerRequest>;
+export declare function writeWorkerHeartbeat(lifecycleDirectory: string): Promise<void>;
+export declare function writeWorkerPid(lifecycleDirectory: string, pid: number): Promise<void>;
+export declare function writeWorkerCompletion(lifecycleDirectory: string, completion: PiWorkerCompletion): Promise<void>;
+export declare function readWorkerCompletion(lifecycleDirectory: string): Promise<PiWorkerCompletion | undefined>;
+export declare function readWorkerHeartbeat(lifecycleDirectory: string): Promise<{
+    pid: number;
+    updatedAt: string;
+} | undefined>;
+export declare function readWorkerPid(lifecycleDirectory: string): Promise<number | undefined>;
+export declare function isProcessAlive(pid: number): boolean;
+export declare function isWorkerAdoptable(handle: Pick<AgentRuntimeHandle, "workerPid" | "lifecycleDirectory" | "orphanAfterMs">, nowMs?: number, heartbeatMaxAgeMs?: number): Promise<boolean>;
+export declare function waitForWorkerCompletion(lifecycleDirectory: string, options?: {
+    pollIntervalMs?: number | undefined;
+    abortSignal?: AbortSignal | undefined;
+}): Promise<PiWorkerCompletion>;
+export declare function resolvePiWorkerMainPath(): string;
+export type SpawnDetachedWorkerOptions = PiRuntimeOptions & {
+    beaconCliPath: string;
+    runToken: string;
+    supervisorLeasePath: string;
+    orphanAfterMs?: number | undefined;
+    workerMainPath?: string | undefined;
+};
+export declare function spawnDetachedPiWorker(lifecycleDirectory: string, request: Omit<PiWorkerRequest, "beaconCliPath" | "runToken" | "supervisorLeasePath" | "orphanAfterMs" | "executable" | "timeoutMs" | "terminateGraceMs" | "maxFrameBytes" | "environment" | "runtimeEnvironment"> & {
+    prompt: string;
+    playbook: string;
+}, options: SpawnDetachedWorkerOptions): Promise<AgentRuntimeHandle>;
+/** Stop a still-living worker (orphan / abandon). Best-effort. */
+export declare function signalWorker(pid: number, signal?: NodeJS.Signals): void;
+export declare function assertSupervisorOrThrow(supervisorLeasePath: string, orphanAfterMs: number): Promise<void>;