@wjarka/cezarion 0.14.8 → 0.14.9-dev.1009

package/dist/runs/store.d.ts

@@ -1,7 +1,8 @@
 import { EventEmitter } from 'node:events';
 import { z } from 'zod';
-import type { CiWait, ConversationState, AgentInput, DelegationState, WorkerCollectedResult } from '../contract/index.js';
+import type { CiWait, ConversationState, AgentInput, InboxClaim, DelegationState, WorkerCollectedResult } from '../contract/index.js';
 import { type WorkerExecutionIdentity } from '../delegation/execution-identity.ts';
+import { type WorkerProcessRecord } from '../delegation/process-liveness.ts';
 import { workflowDefSchema } from '../workflows/types.ts';
 import type { RunnerId } from '../core/agent-runner.ts';
 export type RunStatus = 'queued' | 'running' | 'waiting' | 'review' | 'done' | 'failed' | 'cancelled';
@@ -125,6 +126,18 @@ export declare const runRecordSchema: z.ZodObject<{
                 }>;
                 resumed: z.ZodOptional<z.ZodLiteral<true>>;
                 instruction: z.ZodOptional<z.ZodString>;
+                question: z.ZodOptional<z.ZodObject<{
+                    questions: z.ZodArray<z.ZodObject<{
+                        id: z.ZodOptional<z.ZodString>;
+                        header: z.ZodString;
+                        question: z.ZodString;
+                        options: z.ZodArray<z.ZodObject<{
+                            label: z.ZodString;
+                            description: z.ZodOptional<z.ZodString>;
+                        }, z.core.$strict>>;
+                        multiSelect: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
             }, z.core.$strict>>;
             outcomes: z.ZodArray<z.ZodObject<{
                 requestId: z.ZodUUID;
@@ -133,6 +146,7 @@ export declare const runRecordSchema: z.ZodObject<{
                     "completed-without-reply": "completed-without-reply";
                     destroyed: "destroyed";
                     failed: "failed";
+                    "human-fallback": "human-fallback";
                     replied: "replied";
                     "sender-closed": "sender-closed";
                     "timed-out": "timed-out";
@@ -175,6 +189,7 @@ export declare const runRecordSchema: z.ZodObject<{
                     "completed-without-reply": "completed-without-reply";
                     destroyed: "destroyed";
                     failed: "failed";
+                    "human-fallback": "human-fallback";
                     replied: "replied";
                     "sender-closed": "sender-closed";
                     "timed-out": "timed-out";
@@ -228,6 +243,7 @@ export declare const runRecordSchema: z.ZodObject<{
                     "completed-without-reply": "completed-without-reply";
                     destroyed: "destroyed";
                     failed: "failed";
+                    "human-fallback": "human-fallback";
                     replied: "replied";
                     "sender-closed": "sender-closed";
                     "timed-out": "timed-out";
@@ -316,6 +332,7 @@ export declare const runRecordSchema: z.ZodObject<{
                     "completed-without-reply": "completed-without-reply";
                     destroyed: "destroyed";
                     failed: "failed";
+                    "human-fallback": "human-fallback";
                     replied: "replied";
                     "sender-closed": "sender-closed";
                     "timed-out": "timed-out";
@@ -369,6 +386,7 @@ export declare const runRecordSchema: z.ZodObject<{
                     "completed-without-reply": "completed-without-reply";
                     destroyed: "destroyed";
                     failed: "failed";
+                    "human-fallback": "human-fallback";
                     replied: "replied";
                     "sender-closed": "sender-closed";
                     "timed-out": "timed-out";
@@ -486,6 +504,15 @@ export declare const runRecordSchema: z.ZodObject<{
         text: z.ZodString;
         createdAt: z.ZodISODateTime;
         deliveredAt: z.ZodOptional<z.ZodISODateTime>;
+        consumedAt: z.ZodOptional<z.ZodISODateTime>;
+        awaitingRead: z.ZodOptional<z.ZodLiteral<true>>;
+        inboxClaim: z.ZodOptional<z.ZodObject<{
+            receiptId: z.ZodUUID;
+            generation: z.ZodUUID;
+            expiresAt: z.ZodISODateTime;
+            acknowledgedAt: z.ZodOptional<z.ZodISODateTime>;
+            memberIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>>;
     ciWait: z.ZodOptional<z.ZodObject<{
         prUrl: z.ZodString;
@@ -592,6 +619,11 @@ export declare const runRecordSchema: z.ZodObject<{
     systemPrompt: z.ZodOptional<z.ZodString>;
     generateFollowups: z.ZodOptional<z.ZodBoolean>;
     autonomous: z.ZodOptional<z.ZodBoolean>;
+    notify: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    webhook: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        lastDeliveredAt: z.ZodOptional<z.ZodString>;
+        lastError: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     automation: z.ZodOptional<z.ZodObject<{
         automationId: z.ZodString;
         automationRevision: z.ZodNumber;
@@ -648,6 +680,8 @@ export declare const runRecordSchema: z.ZodObject<{
     worktreeReclaimedAt: z.ZodOptional<z.ZodString>;
     groupId: z.ZodOptional<z.ZodString>;
     variant: z.ZodOptional<z.ZodString>;
+    clientRequestId: z.ZodOptional<z.ZodString>;
+    clientRequestHash: z.ZodOptional<z.ZodString>;
     peakRssBytes: z.ZodOptional<z.ZodNumber>;
     peakProcCount: z.ZodOptional<z.ZodNumber>;
     archived: z.ZodDefault<z.ZodBoolean>;
@@ -777,10 +811,22 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
                 state: "accepted" | "continuation-required" | "destroyed" | "late";
                 resumed?: true | undefined;
                 instruction?: string | undefined;
+                question?: {
+                    questions: {
+                        id?: string | undefined;
+                        header: string;
+                        question: string;
+                        options: {
+                            label: string;
+                            description?: string | undefined;
+                        }[];
+                        multiSelect?: boolean | undefined;
+                    }[];
+                } | undefined;
             }[];
             outcomes: {
                 requestId: string;
-                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                 observedAt: string;
                 replyId?: string | undefined;
             }[];
@@ -803,7 +849,7 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
             requestIds?: string[] | undefined;
             requestOutcomes?: {
                 requestId: string;
-                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                 observedAt: string;
                 replyId?: string | undefined;
             }[] | undefined;
@@ -830,7 +876,7 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
             requestIds?: string[] | undefined;
             requestOutcomes?: {
                 requestId: string;
-                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                 observedAt: string;
                 replyId?: string | undefined;
             }[] | undefined;
@@ -877,7 +923,7 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
             requestIds?: string[] | undefined;
             requestOutcomes?: {
                 requestId: string;
-                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                 observedAt: string;
                 replyId?: string | undefined;
             }[] | undefined;
@@ -904,7 +950,7 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
             requestIds?: string[] | undefined;
             requestOutcomes?: {
                 requestId: string;
-                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "replied" | "sender-closed" | "timed-out";
+                status: "cancelled" | "completed-without-reply" | "destroyed" | "failed" | "human-fallback" | "replied" | "sender-closed" | "timed-out";
                 observedAt: string;
                 replyId?: string | undefined;
             }[] | undefined;
@@ -974,6 +1020,15 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
         text: string;
         createdAt: string;
         deliveredAt?: string | undefined;
+        consumedAt?: string | undefined;
+        awaitingRead?: true | undefined;
+        inboxClaim?: {
+            receiptId: string;
+            generation: string;
+            expiresAt: string;
+            acknowledgedAt?: string | undefined;
+            memberIds?: string[] | undefined;
+        } | undefined;
     }[] | undefined;
     ciWait?: {
         prUrl: string;
@@ -1043,6 +1098,11 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
     systemPrompt?: string | undefined;
     generateFollowups?: boolean | undefined;
     autonomous?: boolean | undefined;
+    notify?: boolean | undefined;
+    webhook?: {
+        lastDeliveredAt?: string | undefined;
+        lastError?: string | undefined;
+    } | undefined;
     automation?: {
         automationId: string;
         automationRevision: number;
@@ -1085,6 +1145,8 @@ export declare function parseRunRecords(raw: unknown): z.ZodSafeParseResult<{
     worktreeReclaimedAt?: string | undefined;
     groupId?: string | undefined;
     variant?: string | undefined;
+    clientRequestId?: string | undefined;
+    clientRequestHash?: string | undefined;
     peakRssBytes?: number | undefined;
     peakProcCount?: number | undefined;
     archived: boolean;
@@ -1220,6 +1282,9 @@ export declare class RunStore extends EventEmitter {
     setRepoHandle(handle: RepoHandle | null): void;
     listRuns(): RunRecord[];
     getRun(id: string): RunRecord | undefined;
+    /** The run an idempotent start already created (#504), archived or not. A deleted run is gone
+     *  with its record, so a retry after deletion honestly creates a fresh one. */
+    findRunByClientRequestId(clientRequestId: string): RunRecord | undefined;
     createRun(input: {
         title: string;
         systemPrompt?: string;
@@ -1234,9 +1299,13 @@ export declare class RunStore extends EventEmitter {
         agentProfile?: string;
         generateFollowups?: boolean;
         autonomous?: boolean;
+        /** Task webhook opt-in (#589), set at creation so the first transition is already covered. */
+        notify?: boolean;
         worktree?: false;
         groupId?: string;
         variant?: string;
+        clientRequestId?: string;
+        clientRequestHash?: string;
         steps: Array<Pick<StepState, 'id' | 'name' | 'kind'>>;
     }): RunRecord;
     /** Build without publishing: owned creation must commit its receipt and run together. */
@@ -1247,7 +1316,23 @@ export declare class RunStore extends EventEmitter {
         input: AgentInput;
     }): void;
     /** Observable atomic input checkpoint: a failed write publishes nothing. */
+    /** Accepted input the harness will never read returns to the queue (#505): only its
+     * delivery and consumption receipts are cleared; order and identity are kept. */
+    requeueUnconsumedAgentInputs(id: string, ids: readonly string[]): void;
+    /** Model consumption observed by the current session (#505). Never un-sets deliveredAt. */
+    commitAgentInputsConsumed(id: string, ids: readonly string[], at: string): void;
+    /** Delivered, but the harness never confirmed reading it (#505): stop awaiting a read. */
+    commitAgentInputsUnconfirmed(id: string, ids: readonly string[]): void;
+    /** Crash recovery (#505): input a harness accepted but was never seen reading goes
+     * back to the queue. Returns the requeued IDs. */
+    requeueAwaitingReadInputs(id: string): string[];
     commitAgentInputs(id: string, inputs: readonly AgentInput[], openingContinuationInputId?: string): void;
+    /** Reserve only unread conversation inputs in one durable index replacement. */
+    claimInboxInputs(runId: string, ids: readonly string[], claim: InboxClaim): void;
+    /** A receipt owns every matching input or none; exact ACK retries preserve the first timestamp. */
+    ackInboxInputs(runId: string, receiptId: string, generation: string, at: string): 'acknowledged' | 'already-acknowledged';
+    releaseInboxInputs(runId: string, receiptId: string, generation: string): 'released';
+    clearExpiredInboxClaims(runId: string, now: string): void;
     /** CI intent and its wake entry share one atomic index replacement. */
     commitCiWait(id: string, wait: CiWait, input?: AgentInput): void;
     /** Retire the wait and precisely its pending wake, optionally accepting human input. */
@@ -1458,6 +1543,15 @@ export declare class RunStore extends EventEmitter {
     } | undefined;
     private writeWorkerExecution;
     commitWorkerExecutionStart(id: string): string;
+    /** Private process record (#469): which processes a generation spawned, never part of run JSON or SSE. */
+    private processesPath;
+    /** Tri-state: only ENOENT is `absent` (legacy, scan-only). A present record that is unreadable,
+     * wrongly permissioned, malformed or of another generation is `unknown`: never finalized or reaped. */
+    readWorkerProcesses(id: string, generation: string): WorkerProcessRecord | 'absent' | 'unknown';
+    private writeWorkerProcesses;
+    /** Bound to the current generation. Past the cap the record never drops an entry: the
+     * working-directory scan is the remaining evidence. */
+    appendWorkerProcess(id: string, generation: string, pid: number): boolean;
     commitWorkerExecutionComplete(id: string, generation: string): boolean;
     /** Cancellation must hit disk before queued no-start evidence authorizes cleanup. */
     commitWorkerCancellation(id: string): void;

package/dist/runs/store.js

@@ -1,13 +1,16 @@
 import { EventEmitter } from 'node:events';
+import { removeArtifacts } from '../artifacts/lifecycle.js';
 import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
 import { appendFileSync, closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, readSync, realpathSync, readdirSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { z } from 'zod';
-import { ciWaitSchema, agentInputSchema, delegationStateSchema, workerCreationReceiptSchema, workerCollectedResultSchema, workerResultFileSchema, continuationMessageSchema, runRecordSchema as contractRunRecordSchema, } from '../contract/index.js';
+import { ciWaitSchema, agentInputSchema, inboxClaimSchema, delegationStateSchema, workerCreationReceiptSchema, workerCollectedResultSchema, workerResultFileSchema, continuationMessageSchema, runRecordSchema as contractRunRecordSchema, } from '../contract/index.js';
 import { storedDelegationStateSchema } from './delegation-state.js';
 import { refreshHumanAskSummary } from './human-ask-summary.js';
 import { workerExecutionIdentitySchema } from '../delegation/execution-identity.js';
 import { reconcileWorkerWait } from '../delegation/wait.js';
+import { processStartToken } from '../delegation/process-liveness.js';
 import { collectSecretValues, redactDeep, redactSecrets } from '../core/secret-redaction.js';
 // Pure, dependency-free reference helpers — the same sanity bound the marker parser applies.
 import { MAX_REF } from './task-refs.js';
@@ -167,6 +170,10 @@ export const runRecordSchema = z.object({
      *  group-pick winner-park read it). Additive-safe: absent = falsy = not
      *  autonomous. Set at creation from `WorkflowInput.autonomous`. */
     autonomous: z.boolean().optional(),
+    /** Task webhook opt-in (#589). Absent = off; `POST /runs/:id/notify` flips it at any time. */
+    notify: z.boolean().optional().catch(undefined),
+    /** The last task-webhook delivery's outcome (#589), written by `runs/webhook.ts`. */
+    webhook: contractRunRecordSchema.shape.webhook.catch(undefined),
     /** Optional provenance for tasks launched by a project GitHub automation. */
     automation: z
         .object({
@@ -262,6 +269,10 @@ export const runRecordSchema = z.object({
     groupId: z.string().optional(),
     /** Variant letter within the group — 'A' | 'B' | 'C' (kept as a string). */
     variant: z.string().optional(),
+    /** Idempotent start (#504): the caller's request id and the hash of the start payload it
+     *  named (`src/runs/client-request.ts`). Absent on every run started without one. */
+    clientRequestId: z.string().optional(),
+    clientRequestHash: z.string().optional(),
     /** Peak resident memory (bytes) / process count observed across the run's
      *  agent process trees (#348) — written when a session's telemetry ends.
      *  Optional: old runs.json files and `ps`-less platforms have neither. */
@@ -695,6 +706,11 @@ export function rescopeRun(run, handle) {
     }
     return changed;
 }
+const WORKER_PROCESS_CAP = 32;
+const recordedProcessSchema = z.object({ pid: z.number().int().positive(), startToken: z.string().min(1).max(128).optional() }).strict();
+const workerProcessRecordSchema = z.object({ generation: z.string().uuid(), controller: recordedProcessSchema,
+    processes: z.array(recordedProcessSchema).max(WORKER_PROCESS_CAP) }).strict();
+const startToken = (pid) => { const token = processStartToken(pid); return token === undefined ? {} : { startToken: token }; };
 /**
  * File-backed run store: `runs.json` index (atomic tmp+rename writes, the
  * pattern from @cezar/core's IssueStore) plus one append-only NDJSON event
@@ -776,6 +792,14 @@ export class RunStore extends EventEmitter {
     getRun(id) {
         return this.runs.get(id);
     }
+    /** The run an idempotent start already created (#504), archived or not. A deleted run is gone
+     *  with its record, so a retry after deletion honestly creates a fresh one. */
+    findRunByClientRequestId(clientRequestId) {
+        for (const run of this.runs.values())
+            if (run.clientRequestId === clientRequestId)
+                return run;
+        return undefined;
+    }
     createRun(input) {
         const run = this.buildRun(input, randomUUID());
         this.runs.set(run.id, run);
@@ -804,9 +828,11 @@ export class RunStore extends EventEmitter {
             agentProfile: input.agentProfile,
             generateFollowups: input.generateFollowups,
             autonomous: input.autonomous,
+            ...(input.notify ? { notify: true } : {}),
             worktree: input.worktree,
             groupId: input.groupId,
             variant: input.variant,
+            ...(input.clientRequestId === undefined ? {} : { clientRequestId: input.clientRequestId, clientRequestHash: input.clientRequestHash }),
             status: 'queued',
             createdAt: new Date().toISOString(),
             tokensUsed: 0,
@@ -846,11 +872,65 @@ export class RunStore extends EventEmitter {
         this.commitIndex(proposed, changed);
     }
     /** Observable atomic input checkpoint: a failed write publishes nothing. */
+    /** Accepted input the harness will never read returns to the queue (#505): only its
+     * delivery and consumption receipts are cleared; order and identity are kept. */
+    requeueUnconsumedAgentInputs(id, ids) {
+        const run = this.runs.get(id);
+        if (!run?.agentInputs || !ids.length)
+            return;
+        this.commitAgentInputs(id, run.agentInputs.map(input => {
+            if (!ids.includes(input.id))
+                return input;
+            const { deliveredAt: _delivered, consumedAt: _consumed, awaitingRead: _awaiting, ...queued } = input;
+            return queued;
+        }));
+    }
+    /** Model consumption observed by the current session (#505). Never un-sets deliveredAt. */
+    commitAgentInputsConsumed(id, ids, at) {
+        const run = this.runs.get(id);
+        if (!run?.agentInputs || !ids.length)
+            return;
+        this.commitAgentInputs(id, run.agentInputs.map(input => {
+            if (!ids.includes(input.id) || !input.deliveredAt || input.consumedAt)
+                return input;
+            const { awaitingRead: _awaiting, ...read } = input;
+            return { ...read, consumedAt: at };
+        }));
+    }
+    /** Delivered, but the harness never confirmed reading it (#505): stop awaiting a read. */
+    commitAgentInputsUnconfirmed(id, ids) {
+        const run = this.runs.get(id);
+        if (!run?.agentInputs || !ids.length)
+            return;
+        this.commitAgentInputs(id, run.agentInputs.map(input => {
+            if (!ids.includes(input.id) || !input.awaitingRead)
+                return input;
+            const { awaitingRead: _awaiting, ...unconfirmed } = input;
+            return unconfirmed;
+        }));
+    }
+    /** Crash recovery (#505): input a harness accepted but was never seen reading goes
+     * back to the queue. Returns the requeued IDs. */
+    requeueAwaitingReadInputs(id) {
+        const ids = (this.runs.get(id)?.agentInputs ?? []).filter(input => input.awaitingRead && input.deliveredAt && !input.consumedAt).map(input => input.id);
+        this.requeueUnconsumedAgentInputs(id, ids);
+        return ids;
+    }
     commitAgentInputs(id, inputs, openingContinuationInputId) {
         const run = this.runs.get(id);
         if (!run)
             throw new Error('missing agent input target');
         const agentInputs = inputs.map(input => agentInputSchema.parse(input));
+        const now = new Date().toISOString();
+        for (const input of run.agentInputs ?? []) {
+            const claim = input.inboxClaim;
+            if (!claim || claim.acknowledgedAt || claim.expiresAt <= now)
+                continue;
+            const matching = agentInputs.filter(next => next.id === input.id);
+            if (matching.length !== 1 || !isDeepStrictEqual(matching[0].inboxClaim, claim)) {
+                throw new Error('live inbox receipt changed');
+            }
+        }
         if (openingContinuationInputId && (run.continuationMessage?.agentInputId !== openingContinuationInputId ||
             !agentInputs.some(input => input.id === openingContinuationInputId && input.deliveredAt)))
             throw new Error('opening agent input checkpoint changed');
@@ -858,6 +938,96 @@ export class RunStore extends EventEmitter {
         proposed.set(id, { ...run, agentInputs, ...(openingContinuationInputId ? { continuationMessage: undefined } : {}) });
         this.commitIndex(proposed, new Set([id]));
     }
+    /** Reserve only unread conversation inputs in one durable index replacement. */
+    claimInboxInputs(runId, ids, claim) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new Error('missing inbox recipient');
+        const selected = z.array(z.uuid()).min(1).max(32).refine(values => new Set(values).size === values.length).parse(ids);
+        const receipt = inboxClaimSchema.parse({ ...claim, memberIds: selected });
+        if (receipt.acknowledgedAt || receipt.expiresAt <= new Date().toISOString())
+            throw new Error('inbox claim is not live');
+        const inputs = run.agentInputs ?? [];
+        if (inputs.some(input => input.inboxClaim?.receiptId === receipt.receiptId))
+            throw new Error('inbox receipt already exists');
+        for (const id of selected) {
+            const matching = inputs.filter(input => input.id === id);
+            if (matching.length !== 1 || matching[0]?.source !== 'agent' || !matching[0].conversation ||
+                matching[0].deliveredAt || (matching[0].inboxClaim && matching[0].inboxClaim.expiresAt > new Date().toISOString())) {
+                throw new Error('inbox input is not available');
+            }
+        }
+        const selectedIds = new Set(selected);
+        const proposed = new Map(this.runs);
+        proposed.set(runId, { ...run, agentInputs: inputs.map(input => selectedIds.has(input.id)
+                ? agentInputSchema.parse({ ...input, inboxClaim: receipt }) : input) });
+        this.commitIndex(proposed, new Set([runId]));
+    }
+    /** A receipt owns every matching input or none; exact ACK retries preserve the first timestamp. */
+    ackInboxInputs(runId, receiptId, generation, at) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new Error('missing inbox recipient');
+        inboxClaimSchema.shape.receiptId.parse(receiptId);
+        inboxClaimSchema.shape.generation.parse(generation);
+        inboxClaimSchema.shape.expiresAt.parse(at);
+        const matching = (run.agentInputs ?? []).filter(input => input.inboxClaim?.receiptId === receiptId);
+        const receipt = matching[0]?.inboxClaim;
+        const memberIds = receipt?.memberIds;
+        if (!memberIds || matching.length !== memberIds.length ||
+            !memberIds.every(id => matching.some(input => input.id === id)) ||
+            matching.some(input => !isDeepStrictEqual(input.inboxClaim, receipt)) ||
+            matching.some(input => input.inboxClaim?.generation !== generation ||
+                input.source !== 'agent' || !input.conversation))
+            throw new Error('inbox receipt changed');
+        if (matching.every(input => input.inboxClaim?.acknowledgedAt && input.deliveredAt === input.inboxClaim.acknowledgedAt)) {
+            return 'already-acknowledged';
+        }
+        if (matching.some(input => input.deliveredAt || input.inboxClaim?.acknowledgedAt || input.inboxClaim.expiresAt <= at)) {
+            throw new Error('inbox receipt expired or displaced');
+        }
+        const proposed = new Map(this.runs);
+        proposed.set(runId, { ...run, agentInputs: run.agentInputs.map(input => input.inboxClaim?.receiptId === receiptId
+                ? agentInputSchema.parse({ ...input, deliveredAt: at, inboxClaim: { ...input.inboxClaim, acknowledgedAt: at } }) : input) });
+        this.commitIndex(proposed, new Set([runId]));
+        return 'acknowledged';
+    }
+    releaseInboxInputs(runId, receiptId, generation) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new Error('missing inbox recipient');
+        inboxClaimSchema.shape.receiptId.parse(receiptId);
+        inboxClaimSchema.shape.generation.parse(generation);
+        const matching = (run.agentInputs ?? []).filter(input => input.inboxClaim?.receiptId === receiptId);
+        if (!matching.length || matching.some(input => input.inboxClaim?.generation !== generation ||
+            input.inboxClaim?.acknowledgedAt || input.deliveredAt))
+            throw new Error('inbox receipt changed');
+        const proposed = new Map(this.runs);
+        proposed.set(runId, { ...run, agentInputs: run.agentInputs.map(input => {
+                if (input.inboxClaim?.receiptId !== receiptId)
+                    return input;
+                const { inboxClaim: _claim, ...unclaimed } = input;
+                return agentInputSchema.parse(unclaimed);
+            }) });
+        this.commitIndex(proposed, new Set([runId]));
+        return 'released';
+    }
+    clearExpiredInboxClaims(runId, now) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new Error('missing inbox recipient');
+        inboxClaimSchema.shape.expiresAt.parse(now);
+        if (!run.agentInputs?.some(input => input.inboxClaim && !input.inboxClaim.acknowledgedAt && input.inboxClaim.expiresAt <= now))
+            return;
+        const proposed = new Map(this.runs);
+        proposed.set(runId, { ...run, agentInputs: run.agentInputs.map(input => {
+                if (!input.inboxClaim || input.inboxClaim.acknowledgedAt || input.inboxClaim.expiresAt > now)
+                    return input;
+                const { inboxClaim: _claim, ...unclaimed } = input;
+                return agentInputSchema.parse(unclaimed);
+            }) });
+        this.commitIndex(proposed, new Set([runId]));
+    }
     /** CI intent and its wake entry share one atomic index replacement. */
     commitCiWait(id, wait, input) {
         const run = this.runs.get(id);
@@ -1337,7 +1507,7 @@ export class RunStore extends EventEmitter {
             ? startedAgentSteps.reduce((sum, candidate) => sum + (candidate.outputTokens ?? 0), 0)
             : undefined;
         const cost = run.steps.reduce((sum, s) => sum + (s.costUsd ?? 0), 0);
-        run.costUsd = cost > 0 ? cost : undefined;
+        run.costUsd = run.steps.some((step) => step.costUsd !== undefined) ? cost : undefined;
         this.touch(run);
     }
     setArchived(id, archived) {
@@ -1808,9 +1978,78 @@ export class RunStore extends EventEmitter {
             throw new Error('Worker execution checkpoint does not prove safe admission');
         }
         const generation = randomUUID();
+        // #469: the controller is durable before `starting`, so a crash leaves a provable generation.
+        this.writeWorkerProcesses(id, { generation, controller: { pid: process.pid, ...startToken(process.pid) }, processes: [] });
         this.writeWorkerExecution(id, { generation, phase: 'starting' });
         return generation;
     }
+    /** Private process record (#469): which processes a generation spawned, never part of run JSON or SSE. */
+    processesPath(id) {
+        return this.executionPath(id).replace(/\.execution\.json$/, '.processes.json');
+    }
+    /** Tri-state: only ENOENT is `absent` (legacy, scan-only). A present record that is unreadable,
+     * wrongly permissioned, malformed or of another generation is `unknown`: never finalized or reaped. */
+    readWorkerProcesses(id, generation) {
+        try {
+            const fd = openSync(this.processesPath(id), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const info = fstatSync(fd);
+                if (!info.isFile() || info.size > 8192 || (info.mode & 0o077))
+                    return 'unknown';
+                const buffer = Buffer.alloc(8193);
+                const count = readSync(fd, buffer, 0, buffer.length, 0);
+                const record = workerProcessRecordSchema.parse(JSON.parse(buffer.subarray(0, count).toString('utf8')));
+                return record.generation === generation ? record : 'unknown';
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        catch (error) {
+            return error.code === 'ENOENT' ? 'absent' : 'unknown';
+        }
+    }
+    writeWorkerProcesses(id, record) {
+        const path = this.processesPath(id);
+        try {
+            const existing = lstatSync(path);
+            if (!existing.isFile() || existing.isSymbolicLink())
+                throw new Error('Unsafe process record');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        try {
+            writeFileSync(fd, JSON.stringify(workerProcessRecordSchema.parse(record)));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        try {
+            renameSync(temporary, path);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+    }
+    /** Bound to the current generation. Past the cap the record never drops an entry: the
+     * working-directory scan is the remaining evidence. */
+    appendWorkerProcess(id, generation, pid) {
+        const record = this.readWorkerProcesses(id, generation);
+        if (typeof record === 'string' || this.readWorkerExecution(id)?.generation !== generation)
+            return false;
+        const entry = { pid, ...startToken(pid) };
+        if (record.processes.some(known => known.pid === entry.pid && known.startToken === entry.startToken))
+            return true;
+        if (record.processes.length >= WORKER_PROCESS_CAP)
+            return false;
+        this.writeWorkerProcesses(id, { ...record, processes: [...record.processes, entry] });
+        return true;
+    }
     commitWorkerExecutionComplete(id, generation) {
         const proof = this.readWorkerExecution(id);
         if (!proof || proof.generation !== generation)
@@ -1933,6 +2172,7 @@ export class RunStore extends EventEmitter {
                 this.removeRunHistoryBytes(id);
                 // Private process/account evidence is now replaced by the exact parent receipt.
                 rmSync(this.identityPath(id), { force: true });
+                rmSync(this.processesPath(id), { force: true });
                 rmSync(this.executionPath(id), { force: true });
                 const retained = this.readWorkerResult(parent.id, id);
                 this.commitWorkerResult(parent.id, { ...retained, observedAt: new Date().toISOString(),
@@ -1974,6 +2214,7 @@ export class RunStore extends EventEmitter {
         rmSync(this.eventsPath(id), { force: true });
         rmSync(this.handoffPath(id), { force: true });
         rmSync(this.imagesDir(id), { recursive: true, force: true });
+        removeArtifacts(this.dataDir, id);
     }
     deleteRun(id) {
         if (!this.canDeleteRun(id))
@@ -1987,6 +2228,7 @@ export class RunStore extends EventEmitter {
                 rmSync(this.eventsPath(id), { force: true });
                 rmSync(this.handoffPath(id), { force: true });
                 rmSync(this.imagesDir(id), { recursive: true, force: true });
+                removeArtifacts(this.dataDir, id);
             }
             catch { /* Ordinary run deletion preserves its existing best-effort behavior. */ }
             this.seqs.delete(id);
@@ -2054,6 +2296,7 @@ export class RunStore extends EventEmitter {
                 rmSync(this.eventsPath(stale.id), { force: true });
                 rmSync(this.handoffPath(stale.id), { force: true });
                 rmSync(this.imagesDir(stale.id), { recursive: true, force: true });
+                removeArtifacts(this.dataDir, stale.id);
             }
             catch {
                 // best effort