@nettee/beacon 0.5.1 → 0.6.1

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/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,12 @@
+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 stateDirectory = join(options.config.homeDirectory, "state");
+    const supervisorLeasePath = join(stateDirectory, "supervisor.lease");
+    const outcomesDirectory = join(stateDirectory, "outcomes");
     return new RunOrchestrator({
         profile: options.profile,
         store: options.store,
@@ -18,5 +24,21 @@ export function createPiRunOrchestrator(options) {
             runtimeEnvironment: options.runtimeEnvironment,
         }),
         delivery: options.delivery,
+        ...(detachRuns
+            ? {
+                detached: {
+                    supervisorLeasePath,
+                    outcomesDirectory,
+                    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,18 @@ export type DeliveryAdapter = {
         providerRequestId?: string | undefined;
     }>;
 };
+export type DetachedRunOptions = {
+    supervisorLeasePath: string;
+    /** Directory for short per-run Outcome sockets (e.g. ~/.beacon/state/outcomes). */
+    outcomesDirectory: 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 +30,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 +72,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, resolveWorkerOutcomeSocketPath, 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,114 @@ 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 outcomeSocketPath = resolveWorkerOutcomeSocketPath(detached.outcomesDirectory, runId);
+        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}`,
+            },
+            outcomeSocketPath,
+            ...(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 +498,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 +627,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,104 @@
+import type { ProfileSkills } from "../config/profile.js";
+import type { FeedbackRecord, FinalOutcomeContent, ObservabilityFeedbackRecord } from "../domain/types.js";
+import type { PiRunResult, PiRuntimeOptions } from "./pi-rpc.js";
+/**
+ * Usable AF_UNIX path length on macOS (`sun_path` is 104 including NUL).
+ * Enforced on all platforms so Linux CI catches oversize paths too.
+ */
+export declare const UNIX_SOCKET_PATH_MAX_BYTES = 103;
+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;
+    /** Short absolute path under ~/.beacon/state/outcomes/<16hex>.sock */
+    outcomeSocketPath: 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;
+};
+/** Stable, short per-run Outcome socket under the daemon outcomes directory. */
+export declare function resolveWorkerOutcomeSocketPath(outcomesDirectory: string, runId: string): string;
+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;
+    /** @deprecated 0.6.0 bound here; 0.6.1+ uses resolveWorkerOutcomeSocketPath. */
+    legacyOutcomeSocket: string;
+};
+export declare function prepareLifecycleDirectory(lifecycleDirectory: string, options?: {
+    outcomeSocketPath?: string | undefined;
+}): 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>;

package/dist/daemon/runtime/pi-worker-lifecycle.js

@@ -0,0 +1,252 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { access, chmod, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_ORPHAN_AFTER_MS, isSupervisorLeaseFresh, } from "./supervisor-lease.js";
+/**
+ * Usable AF_UNIX path length on macOS (`sun_path` is 104 including NUL).
+ * Enforced on all platforms so Linux CI catches oversize paths too.
+ */
+export const UNIX_SOCKET_PATH_MAX_BYTES = 103;
+/** Stable, short per-run Outcome socket under the daemon outcomes directory. */
+export function resolveWorkerOutcomeSocketPath(outcomesDirectory, runId) {
+    if (!isAbsolute(outcomesDirectory)) {
+        throw new Error("Worker outcome socket directory must be absolute");
+    }
+    if (!runId) {
+        throw new Error("Worker outcome socket requires a run id");
+    }
+    const shortId = createHash("sha256").update(runId).digest("hex").slice(0, 16);
+    const socketPath = join(outcomesDirectory, `${shortId}.sock`);
+    const bytes = Buffer.byteLength(socketPath, "utf8");
+    if (bytes > UNIX_SOCKET_PATH_MAX_BYTES) {
+        throw new Error(`Worker outcome socket path exceeds Unix sun_path limit (${bytes} > ${UNIX_SOCKET_PATH_MAX_BYTES} bytes): ${socketPath}`);
+    }
+    return socketPath;
+}
+const REQUEST_FILE = "request.json";
+const COMPLETION_FILE = "completion.json";
+const HEARTBEAT_FILE = "worker.heartbeat";
+const PID_FILE = "worker.pid";
+export function lifecyclePaths(lifecycleDirectory) {
+    return {
+        request: join(lifecycleDirectory, REQUEST_FILE),
+        completion: join(lifecycleDirectory, COMPLETION_FILE),
+        heartbeat: join(lifecycleDirectory, HEARTBEAT_FILE),
+        pid: join(lifecycleDirectory, PID_FILE),
+        /** @deprecated 0.6.0 bound here; 0.6.1+ uses resolveWorkerOutcomeSocketPath. */
+        legacyOutcomeSocket: join(lifecycleDirectory, "outcomes.sock"),
+    };
+}
+export async function prepareLifecycleDirectory(lifecycleDirectory, options = {}) {
+    if (!isAbsolute(lifecycleDirectory)) {
+        throw new Error("Pi worker lifecycle directory must be absolute");
+    }
+    await mkdir(lifecycleDirectory, { recursive: true, mode: 0o700 });
+    await chmod(lifecycleDirectory, 0o700);
+    const paths = lifecyclePaths(lifecycleDirectory);
+    await rm(paths.completion, { force: true });
+    await rm(paths.heartbeat, { force: true });
+    await rm(paths.pid, { force: true });
+    await rm(paths.legacyOutcomeSocket, { force: true });
+    if (options.outcomeSocketPath) {
+        if (!isAbsolute(options.outcomeSocketPath)) {
+            throw new Error("Worker outcome socket path must be absolute");
+        }
+        await mkdir(dirname(options.outcomeSocketPath), {
+            recursive: true,
+            mode: 0o700,
+        });
+        await rm(options.outcomeSocketPath, { force: true });
+    }
+}
+export async function writeWorkerRequest(lifecycleDirectory, request) {
+    if (!request.outcomeSocketPath || !isAbsolute(request.outcomeSocketPath)) {
+        throw new Error("Pi worker request requires an absolute outcomeSocketPath");
+    }
+    await prepareLifecycleDirectory(lifecycleDirectory, {
+        outcomeSocketPath: request.outcomeSocketPath,
+    });
+    const temporary = `${lifecyclePaths(lifecycleDirectory).request}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(request, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    await rename(temporary, lifecyclePaths(lifecycleDirectory).request);
+}
+export async function readWorkerRequest(lifecycleDirectory) {
+    const raw = JSON.parse(await readFile(lifecyclePaths(lifecycleDirectory).request, "utf8"));
+    if (!raw.beaconCliPath ||
+        !raw.runToken ||
+        !raw.supervisorLeasePath ||
+        !raw.outcomeSocketPath) {
+        throw new Error("Pi worker request is missing required fields");
+    }
+    if (!isAbsolute(raw.outcomeSocketPath)) {
+        throw new Error("Pi worker outcomeSocketPath must be absolute");
+    }
+    return raw;
+}
+export async function writeWorkerHeartbeat(lifecycleDirectory) {
+    const temporary = `${lifecyclePaths(lifecycleDirectory).heartbeat}.tmp`;
+    await writeFile(temporary, `${JSON.stringify({ pid: process.pid, updatedAt: new Date().toISOString() })}\n`, { mode: 0o600 });
+    await rename(temporary, lifecyclePaths(lifecycleDirectory).heartbeat);
+}
+export async function writeWorkerPid(lifecycleDirectory, pid) {
+    await writeFile(lifecyclePaths(lifecycleDirectory).pid, `${pid}\n`, {
+        mode: 0o600,
+    });
+}
+export async function writeWorkerCompletion(lifecycleDirectory, completion) {
+    const temporary = `${lifecyclePaths(lifecycleDirectory).completion}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(completion, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    await rename(temporary, lifecyclePaths(lifecycleDirectory).completion);
+}
+export async function readWorkerCompletion(lifecycleDirectory) {
+    try {
+        return JSON.parse(await readFile(lifecyclePaths(lifecycleDirectory).completion, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function readWorkerHeartbeat(lifecycleDirectory) {
+    try {
+        const raw = JSON.parse(await readFile(lifecyclePaths(lifecycleDirectory).heartbeat, "utf8"));
+        if (typeof raw !== "object" ||
+            raw === null ||
+            !("pid" in raw) ||
+            !("updatedAt" in raw) ||
+            typeof raw.pid !== "number" ||
+            typeof raw.updatedAt !== "string") {
+            return undefined;
+        }
+        return { pid: raw.pid, updatedAt: raw.updatedAt };
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function readWorkerPid(lifecycleDirectory) {
+    try {
+        const raw = (await readFile(lifecyclePaths(lifecycleDirectory).pid, "utf8")).trim();
+        const pid = Number(raw);
+        return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isProcessAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function isWorkerAdoptable(handle, nowMs = Date.now(), heartbeatMaxAgeMs = 60_000) {
+    if (!isProcessAlive(handle.workerPid))
+        return false;
+    const completion = await readWorkerCompletion(handle.lifecycleDirectory);
+    if (completion)
+        return true;
+    const heartbeat = await readWorkerHeartbeat(handle.lifecycleDirectory);
+    if (!heartbeat)
+        return false;
+    const updatedAt = Date.parse(heartbeat.updatedAt);
+    if (!Number.isFinite(updatedAt))
+        return false;
+    return nowMs - updatedAt <= heartbeatMaxAgeMs;
+}
+export async function waitForWorkerCompletion(lifecycleDirectory, options = {}) {
+    const pollIntervalMs = options.pollIntervalMs ?? 250;
+    for (;;) {
+        if (options.abortSignal?.aborted) {
+            throw new Error("Waiting for Pi worker completion was aborted");
+        }
+        const completion = await readWorkerCompletion(lifecycleDirectory);
+        if (completion)
+            return completion;
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, pollIntervalMs);
+            options.abortSignal?.addEventListener("abort", () => {
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+        });
+    }
+}
+export function resolvePiWorkerMainPath() {
+    return fileURLToPath(new URL(import.meta.url.endsWith(".ts")
+        ? "../../dist/runtime/pi-worker-main.js"
+        : "./pi-worker-main.js", import.meta.url));
+}
+export async function spawnDetachedPiWorker(lifecycleDirectory, request, options) {
+    const orphanAfterMs = options.orphanAfterMs ?? DEFAULT_ORPHAN_AFTER_MS;
+    const workerRequest = {
+        ...request,
+        beaconCliPath: options.beaconCliPath,
+        runToken: options.runToken,
+        supervisorLeasePath: options.supervisorLeasePath,
+        orphanAfterMs,
+        executable: options.executable,
+        timeoutMs: options.timeoutMs,
+        terminateGraceMs: options.terminateGraceMs,
+        maxFrameBytes: options.maxFrameBytes,
+        environment: options.environment,
+        runtimeEnvironment: options.runtimeEnvironment,
+    };
+    await writeWorkerRequest(lifecycleDirectory, workerRequest);
+    const workerMainPath = options.workerMainPath ?? resolvePiWorkerMainPath();
+    try {
+        await access(workerMainPath);
+    }
+    catch (error) {
+        throw new Error(`Pi worker entry is missing (build the daemon first): ${workerMainPath}`, { cause: error });
+    }
+    const child = spawn(process.execPath, [workerMainPath, lifecycleDirectory], {
+        detached: true,
+        stdio: "ignore",
+        env: {
+            PATH: process.env.PATH,
+            HOME: process.env.HOME,
+            USER: process.env.USER,
+            TMPDIR: process.env.TMPDIR,
+            LANG: process.env.LANG,
+        },
+    });
+    if (child.pid === undefined) {
+        throw new Error("Failed to spawn detached Pi worker (no pid)");
+    }
+    child.unref();
+    await writeWorkerPid(lifecycleDirectory, child.pid);
+    return {
+        workerPid: child.pid,
+        lifecycleDirectory,
+        runToken: options.runToken,
+        supervisorLeasePath: options.supervisorLeasePath,
+        orphanAfterMs,
+    };
+}
+/** Stop a still-living worker (orphan / abandon). Best-effort. */
+export function signalWorker(pid, signal = "SIGTERM") {
+    if (!isProcessAlive(pid))
+        return;
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        // already gone
+    }
+}
+export async function assertSupervisorOrThrow(supervisorLeasePath, orphanAfterMs) {
+    if (!(await isSupervisorLeaseFresh(supervisorLeasePath, orphanAfterMs))) {
+        throw new Error(`No Beacon supervisor lease for ${orphanAfterMs}ms; abandoning orphan Pi worker`);
+    }
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/daemon/runtime/pi-worker-main.js

@@ -0,0 +1,225 @@
+import { chmod, mkdir, rm } from "node:fs/promises";
+import { createServer } from "node:net";
+import { dirname } from "node:path";
+import { completeOutcome, mergeOutcome, parseOutcomePatch, } from "../outcome/content.js";
+import { PiRuntimeError, runPiAgent } from "./pi-rpc.js";
+import { assertSupervisorOrThrow, readWorkerRequest, writeWorkerCompletion, writeWorkerHeartbeat, } from "./pi-worker-lifecycle.js";
+import { DEFAULT_ORPHAN_AFTER_MS } from "./supervisor-lease.js";
+function respond(socket, response) {
+    socket.end(`${JSON.stringify(response)}\n`);
+}
+async function startWorkerOutcomeServer(socketPath, runToken, maxRequestBytes = 1024 * 1024) {
+    await rm(socketPath, { force: true });
+    const record = {};
+    const server = createServer((socket) => {
+        socket.setEncoding("utf8");
+        let buffer = "";
+        let finished = false;
+        socket.on("data", (chunk) => {
+            if (finished)
+                return;
+            buffer += chunk;
+            if (Buffer.byteLength(buffer, "utf8") > maxRequestBytes) {
+                finished = true;
+                respond(socket, {
+                    ok: false,
+                    error: "Outcome submission request is too large",
+                });
+                return;
+            }
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            finished = true;
+            let request;
+            try {
+                request = JSON.parse(buffer.slice(0, newline));
+            }
+            catch {
+                respond(socket, { ok: false, error: "invalid JSON request" });
+                return;
+            }
+            if (typeof request !== "object" ||
+                request === null ||
+                !("runToken" in request) ||
+                !("outcome" in request) ||
+                typeof request.runToken !== "string") {
+                respond(socket, {
+                    ok: false,
+                    error: "runToken and outcome are required",
+                });
+                return;
+            }
+            if (request.runToken !== runToken) {
+                respond(socket, { ok: false, error: "unknown Run Capability" });
+                return;
+            }
+            let patch;
+            try {
+                patch = parseOutcomePatch(request.outcome);
+            }
+            catch (error) {
+                respond(socket, {
+                    ok: false,
+                    error: `invalid Final Outcome: ${error instanceof Error ? error.message : String(error)}`,
+                });
+                return;
+            }
+            try {
+                const previous = record.outcome;
+                record.outcome = mergeOutcome(record.outcome, patch);
+                if (patch.feedback && !previous?.feedback) {
+                    record.feedbackSubmittedAt = new Date().toISOString();
+                }
+                if (patch.observabilityFeedback && !previous?.observabilityFeedback) {
+                    record.observabilityFeedbackSubmittedAt = new Date().toISOString();
+                }
+            }
+            catch (error) {
+                respond(socket, {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return;
+            }
+            respond(socket, { ok: true });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(socketPath, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    await chmod(socketPath, 0o600);
+    return {
+        take() {
+            return completeOutcome(record.outcome ?? {});
+        },
+        takeFeedback() {
+            const items = record.outcome?.feedback?.items;
+            if (!items || record.feedbackSubmittedAt === undefined)
+                return undefined;
+            return { items, submittedAt: record.feedbackSubmittedAt };
+        },
+        takeObservabilityFeedback() {
+            const items = record.outcome?.observabilityFeedback?.items;
+            if (!items || record.observabilityFeedbackSubmittedAt === undefined) {
+                return undefined;
+            }
+            return { items, submittedAt: record.observabilityFeedbackSubmittedAt };
+        },
+        hasReply() {
+            return record.outcome?.reply !== undefined;
+        },
+        async close() {
+            await new Promise((resolve, reject) => {
+                server.close((error) => (error ? reject(error) : resolve()));
+            });
+            await rm(socketPath, { force: true });
+        },
+    };
+}
+async function runWorker(lifecycleDirectory) {
+    const request = await readWorkerRequest(lifecycleDirectory);
+    const orphanAfterMs = request.orphanAfterMs ?? DEFAULT_ORPHAN_AFTER_MS;
+    const outcomeSocketPath = request.outcomeSocketPath;
+    await mkdir(lifecycleDirectory, { recursive: true, mode: 0o700 });
+    await mkdir(dirname(outcomeSocketPath), { recursive: true, mode: 0o700 });
+    const abort = new AbortController();
+    const heartbeat = setInterval(() => {
+        void writeWorkerHeartbeat(lifecycleDirectory).catch(() => undefined);
+        void assertSupervisorOrThrow(request.supervisorLeasePath, orphanAfterMs)
+            .then(() => undefined)
+            .catch(() => {
+            if (!abort.signal.aborted)
+                abort.abort();
+        });
+    }, 5_000);
+    heartbeat.unref?.();
+    await writeWorkerHeartbeat(lifecycleDirectory);
+    const outcomes = await startWorkerOutcomeServer(outcomeSocketPath, request.runToken);
+    const finish = async (completion) => {
+        clearInterval(heartbeat);
+        await writeWorkerCompletion(lifecycleDirectory, completion);
+        await outcomes.close().catch(() => undefined);
+    };
+    try {
+        await assertSupervisorOrThrow(request.supervisorLeasePath, orphanAfterMs);
+        const result = await runPiAgent({
+            prompt: request.prompt,
+            playbook: request.playbook,
+            provider: request.provider,
+            model: request.model,
+            systemPrompt: request.systemPrompt,
+            session: request.session,
+            skills: request.skills,
+            outcome: {
+                socketPath: outcomeSocketPath,
+                runToken: request.runToken,
+                cliPath: request.beaconCliPath,
+            },
+        }, {
+            executable: request.executable,
+            timeoutMs: request.timeoutMs,
+            terminateGraceMs: request.terminateGraceMs,
+            maxFrameBytes: request.maxFrameBytes,
+            environment: request.environment,
+            runtimeEnvironment: request.runtimeEnvironment,
+            signal: abort.signal,
+        });
+        await finish({
+            ok: true,
+            result,
+            outcome: outcomes.take(),
+            feedback: outcomes.takeFeedback(),
+            observabilityFeedback: outcomes.takeObservabilityFeedback(),
+            hasReply: outcomes.hasReply(),
+            finishedAt: new Date().toISOString(),
+        });
+    }
+    catch (error) {
+        const orphaned = abort.signal.aborted;
+        const code = orphaned
+            ? "orphan_abandoned"
+            : error instanceof PiRuntimeError
+                ? error.code
+                : "worker_failed";
+        const message = orphaned
+            ? "Pi worker stopped after Beacon supervisor lease expired (orphan safety)"
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        await finish({
+            ok: false,
+            error: { code, message },
+            hasReply: outcomes.hasReply(),
+            feedback: outcomes.takeFeedback(),
+            observabilityFeedback: outcomes.takeObservabilityFeedback(),
+            finishedAt: new Date().toISOString(),
+        });
+    }
+}
+const lifecycleDirectory = process.argv[2];
+if (!lifecycleDirectory) {
+    console.error("Usage: node pi-worker-main.js <lifecycle-directory>");
+    process.exitCode = 1;
+}
+else {
+    runWorker(lifecycleDirectory).catch(async (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        try {
+            await writeWorkerCompletion(lifecycleDirectory, {
+                ok: false,
+                error: { code: "worker_failed", message },
+                hasReply: false,
+                finishedAt: new Date().toISOString(),
+            });
+        }
+        catch {
+            console.error(`[beacon-pi-worker] fatal: ${message}`);
+        }
+        process.exitCode = 1;
+    });
+}

package/dist/daemon/runtime/supervisor-lease.d.ts

@@ -0,0 +1,15 @@
+export type SupervisorLease = {
+    pid: number;
+    updatedAt: string;
+};
+export declare const DEFAULT_ORPHAN_AFTER_MS = 120000;
+export declare const DEFAULT_LEASE_INTERVAL_MS = 10000;
+export declare function writeSupervisorLease(path: string): Promise<void>;
+export declare function readSupervisorLease(path: string): Promise<SupervisorLease | undefined>;
+/** True when a supervisor has refreshed the lease within orphanAfterMs. */
+export declare function isSupervisorLeaseFresh(path: string, orphanAfterMs: number, nowMs?: number): Promise<boolean>;
+export type SupervisorLeaseHandle = {
+    stop(): void;
+};
+/** Refresh the lease until stop(). Writes once immediately. */
+export declare function startSupervisorLeaseWriter(path: string, intervalMs?: number): SupervisorLeaseHandle;

package/dist/daemon/runtime/supervisor-lease.js

@@ -0,0 +1,63 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+export const DEFAULT_ORPHAN_AFTER_MS = 120_000;
+export const DEFAULT_LEASE_INTERVAL_MS = 10_000;
+export async function writeSupervisorLease(path) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const lease = {
+        pid: process.pid,
+        updatedAt: new Date().toISOString(),
+    };
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(lease)}\n`, { mode: 0o600 });
+    await rename(temporary, path);
+}
+export async function readSupervisorLease(path) {
+    try {
+        const raw = JSON.parse(await readFile(path, "utf8"));
+        if (typeof raw !== "object" ||
+            raw === null ||
+            !("pid" in raw) ||
+            !("updatedAt" in raw) ||
+            typeof raw.pid !== "number" ||
+            typeof raw.updatedAt !== "string") {
+            return undefined;
+        }
+        return { pid: raw.pid, updatedAt: raw.updatedAt };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when a supervisor has refreshed the lease within orphanAfterMs. */
+export async function isSupervisorLeaseFresh(path, orphanAfterMs, nowMs = Date.now()) {
+    const lease = await readSupervisorLease(path);
+    if (!lease)
+        return false;
+    const updatedAt = Date.parse(lease.updatedAt);
+    if (!Number.isFinite(updatedAt))
+        return false;
+    return nowMs - updatedAt <= orphanAfterMs;
+}
+/** Refresh the lease until stop(). Writes once immediately. */
+export function startSupervisorLeaseWriter(path, intervalMs = DEFAULT_LEASE_INTERVAL_MS) {
+    let stopped = false;
+    let timer;
+    const tick = () => {
+        void writeSupervisorLease(path).catch((error) => {
+            console.error(`[beacon] failed to refresh supervisor lease: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    };
+    tick();
+    timer = setInterval(tick, intervalMs);
+    timer.unref?.();
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+        },
+    };
+}

package/dist/daemon/service.js

@@ -14,6 +14,7 @@ import { createFeishuMessagePipeline } from "./feishu/message-pipeline.js";
 import { startOutcomeServer } from "./outcome/server.js";
 import { createPiRunOrchestrator } from "./run/create-pi-orchestrator.js";
 import { createRunQueue } from "./run/queue.js";
+import { startSupervisorLeaseWriter } from "./runtime/supervisor-lease.js";
 import { ScheduleCursorStore } from "./schedule/cursor-store.js";
 import { ScheduleLoop } from "./schedule/loop.js";
 import { ScheduleReconciler } from "./schedule/reconciler.js";
@@ -44,7 +45,11 @@ export async function runBeacon(configPath, options) {
     const eventProducers = global.events
         ? await loadEventCredentials(global.events.credentialsPath)
         : [];
-    const outcomes = await startOutcomeServer();
+    const supervisorLeasePath = join(global.homeDirectory, "state", "supervisor.lease");
+    const supervisorLease = startSupervisorLeaseWriter(supervisorLeasePath);
+    const outcomes = await startOutcomeServer({
+        directory: join(global.homeDirectory, "state", "outcomes"),
+    });
     const queue = createRunQueue(global.runs, profiles);
     let dashboard;
     try {
@@ -165,6 +170,7 @@ export async function runBeacon(configPath, options) {
             dashboard?.close() ?? Promise.resolve(),
             outcomes.close(),
         ]);
+        supervisorLease.stop();
         for (const result of [...stoppedEvents, ...drained, ...closed]) {
             if (result.status === "rejected" && !failures.includes(result.reason))
                 failures.push(result.reason);

package/dist/daemon/state/trigger-store.js

@@ -44,6 +44,21 @@ const inputSchema = z.discriminatedUnion("kind", [
         .strict(),
     z.object({ kind: z.literal("manual"), text: z.string().min(1) }).strict(),
 ]);
+const agentRuntimeSchema = z
+    .object({
+    workerPid: z.number().int().positive(),
+    lifecycleDirectory: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "Pi worker lifecycle directory must be absolute"),
+    runToken: z.string().min(1),
+    supervisorLeasePath: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "Supervisor lease path must be absolute"),
+    orphanAfterMs: z.number().int().positive(),
+})
+    .strict();
 const runSchema = z
     .object({
     runId: z.string().min(1),
@@ -65,6 +80,7 @@ const runSchema = z
     playbook: z.string().min(1),
     promptDigest: z.string().regex(/^[a-f0-9]{64}$/),
     systemPrompt: z.string().min(1).optional(),
+    agent: agentRuntimeSchema.optional(),
     failure: failureSchema.optional(),
 })
     .strict();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nettee/beacon",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "A single-host bridge from messaging and schedules to isolated agent runs",
   "license": "Apache-2.0",
   "repository": {