@hheei/pi-subagents 0.6.0 → 0.8.0

package/dist/receipts.d.ts

@@ -0,0 +1,80 @@
+export type ReceiptStatus = "reserved" | "dispatching" | "accepted" | "running" | "completed" | "blocked" | "failed" | "uncertain";
+export type ReceiptDelivery = "pending" | "detached";
+export interface Receipt {
+    readonly parentSessionId: string;
+    readonly delegationId: string;
+    readonly childId?: string;
+    readonly revision?: number;
+    readonly task: string;
+    readonly inputCheckpoint?: string;
+    readonly runBoundary?: number;
+    /** The compaction this delegation controls; set instead of a run boundary. */
+    readonly controlId?: string;
+    readonly status: ReceiptStatus;
+    readonly delivery: ReceiptDelivery;
+    readonly resultText?: string;
+    /** Recorded only when a dispatch itself failed; a turn failure leaves both unset. */
+    readonly safeToRetry?: boolean;
+    readonly sideEffects?: readonly string[];
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export interface ReceiptSettlement {
+    readonly childId: string;
+    readonly status: "completed" | "blocked" | "failed";
+    readonly message: string;
+    /** The turn that can settle this event; absent for a control operation. */
+    readonly workVersion?: number;
+    /** Set for a control operation's own settlement; such a receipt has no run boundary. */
+    readonly controlId?: string;
+}
+export declare function createDelegationId(): string;
+export declare function terminalReceipt(status: ReceiptStatus): boolean;
+export declare function reserveReceipt(filePath: string, input: {
+    readonly parentSessionId: string;
+    readonly task: string;
+    readonly childId?: string;
+    readonly delivery: ReceiptDelivery;
+}): Receipt;
+export declare function updateReceipt(filePath: string, parentSessionId: string, delegationId: string, patch: {
+    readonly from: readonly ReceiptStatus[];
+    readonly status: ReceiptStatus;
+    readonly childId?: string;
+    readonly inputCheckpoint?: string;
+    readonly runBoundary?: number;
+    readonly controlId?: string;
+    readonly resultText?: string;
+    readonly safeToRetry?: boolean;
+    readonly sideEffects?: readonly string[];
+}): Receipt | undefined;
+/** A dispatch that died before acceptance cannot be retried safely. */
+export declare function sweepUncertainDispatch(filePath: string, parentSessionId: string): number;
+export declare function settleReceipts(filePath: string, parentSessionId: string, event: ReceiptSettlement): readonly Receipt[];
+/**
+ * A control operation that outlived the process that started it can never be confirmed: the child
+ * may have compacted, may still be compacting, or may never have started. It is recorded as
+ * uncertain instead of being replayed, because replaying compaction is not idempotent.
+ */
+export declare function sweepControlReceipts(filePath: string, parentSessionId: string, message: string): readonly Receipt[];
+export declare function listReceipts(filePath: string, parentSessionId: string, cursor?: number, limit?: number): {
+    readonly receipts: readonly Receipt[];
+    readonly nextCursor?: number;
+};
+/** Stop or shutdown: every open delegation for this child fails, so a waiter cannot hang. */
+export declare function abandonReceipts(filePath: string, parentSessionId: string, childId: string, message: string): readonly Receipt[];
+export declare function maxRunBoundary(filePath: string, parentSessionId: string, childId: string): number;
+export declare function readStoredReceipt(filePath: string, parentSessionId: string, delegationId: string): Receipt | undefined;
+export declare function readReceiptRevision(filePath: string, parentSessionId: string, childId: string, revision: number): Receipt | undefined;
+export declare function latestReceiptForChild(filePath: string, parentSessionId: string, childId: string): Receipt | undefined;
+/** The latest delegation of every agent, without reading any result body. */
+export interface ReceiptSummary {
+    readonly childId: string;
+    readonly delegationId: string;
+    readonly revision: number;
+    readonly status: ReceiptStatus;
+    readonly hasOutput: boolean;
+}
+/** A failed or uncertain receipt stores a reason, not an answer. */
+export declare function receiptCarriesOutput(status: ReceiptStatus, resultText: string | undefined): boolean;
+export declare function latestReceiptSummaries(filePath: string, parentSessionId: string): ReadonlyMap<string, ReceiptSummary>;
+export declare function waitForReceipt(filePath: string, parentSessionId: string, delegationId: string, signal?: AbortSignal): Promise<Receipt>;

package/dist/receipts.js

@@ -0,0 +1,326 @@
+import { randomBytes } from "node:crypto";
+import { openStateDb, withWrite } from "./state-db.js";
+const TERMINAL = new Set([
+    "completed",
+    "blocked",
+    "failed",
+    "uncertain",
+]);
+const waiters = new Map();
+export function createDelegationId() {
+    return `dep_${randomBytes(4).toString("hex")}`;
+}
+export function terminalReceipt(status) {
+    return TERMINAL.has(status);
+}
+export function reserveReceipt(filePath, input) {
+    const db = openStateDb(filePath);
+    const now = Date.now();
+    const delegationId = createDelegationId();
+    return withWrite(db, () => {
+        const revision = input.childId === undefined ? null : nextRevision(db, input.parentSessionId, input.childId);
+        db.prepare(`INSERT INTO delegations (
+				parent_session_id, delegation_id, child_id, delegation_revision, task, status, delivery, created_at, updated_at
+			) VALUES (?, ?, ?, ?, ?, 'reserved', ?, ?, ?)`).run(input.parentSessionId, delegationId, input.childId ?? null, revision, input.task, input.delivery, now, now);
+        const stored = readReceipt(db, input.parentSessionId, delegationId);
+        if (stored === undefined)
+            throw new Error("Reserved delegation was not stored");
+        return stored;
+    });
+}
+export function updateReceipt(filePath, parentSessionId, delegationId, patch) {
+    const db = openStateDb(filePath);
+    const updated = withWrite(db, () => {
+        const current = readReceipt(db, parentSessionId, delegationId);
+        if (current === undefined || !patch.from.includes(current.status))
+            return undefined;
+        const revision = current.revision ??
+            (patch.childId === undefined ? null : nextRevision(db, parentSessionId, patch.childId));
+        db.prepare(`UPDATE delegations
+			 SET status = ?, child_id = COALESCE(?, child_id), input_checkpoint = COALESCE(?, input_checkpoint),
+			     delegation_revision = COALESCE(?, delegation_revision), run_boundary = COALESCE(?, run_boundary),
+			     control_id = COALESCE(?, control_id), result_text = COALESCE(?, result_text),
+			     safe_to_retry = COALESCE(?, safe_to_retry), side_effects = COALESCE(?, side_effects), updated_at = ?
+			 WHERE parent_session_id = ? AND delegation_id = ? AND status = ?`).run(patch.status, patch.childId ?? null, patch.inputCheckpoint ?? null, revision, patch.runBoundary ?? null, patch.controlId ?? null, patch.resultText ?? null, patch.safeToRetry === undefined ? null : patch.safeToRetry ? 1 : 0, patch.sideEffects === undefined ? null : JSON.stringify(patch.sideEffects), Date.now(), parentSessionId, delegationId, current.status);
+        return readReceipt(db, parentSessionId, delegationId);
+    });
+    notify(parentSessionId, delegationId);
+    return updated;
+}
+/** A dispatch that died before acceptance cannot be retried safely. */
+export function sweepUncertainDispatch(filePath, parentSessionId) {
+    const db = openStateDb(filePath);
+    const changed = withWrite(db, () => {
+        const rows = db
+            .prepare(`SELECT delegation_id FROM delegations
+				 WHERE parent_session_id = ? AND status = 'dispatching'`)
+            .all(parentSessionId);
+        for (const row of rows) {
+            db.prepare(`UPDATE delegations SET status = 'uncertain', result_text = ?, updated_at = ?
+				 WHERE parent_session_id = ? AND delegation_id = ? AND status = 'dispatching'`).run("Dispatch was not acknowledged before the controller stopped", Date.now(), parentSessionId, row.delegation_id);
+            notify(parentSessionId, row.delegation_id);
+        }
+        return rows.length;
+    });
+    return changed;
+}
+export function settleReceipts(filePath, parentSessionId, event) {
+    const db = openStateDb(filePath);
+    const settled = withWrite(db, () => {
+        // A control operation is bound to its own id: a late compaction report cannot settle a turn
+        // that started after it, and a turn's answer cannot be reported as a compaction.
+        const rows = (event.controlId === undefined
+            ? db
+                .prepare(`SELECT delegation_id FROM delegations
+							 WHERE parent_session_id = ? AND child_id = ? AND run_boundary = ?
+							   AND control_id IS NULL AND status IN ('accepted', 'running', 'dispatching')`)
+                .all(parentSessionId, event.childId, event.workVersion ?? 0)
+            : db
+                .prepare(`SELECT delegation_id FROM delegations
+							 WHERE parent_session_id = ? AND child_id = ? AND control_id = ?
+							   AND status IN ('accepted', 'running', 'dispatching')`)
+                .all(parentSessionId, event.childId, event.controlId));
+        const now = Date.now();
+        const stored = [];
+        for (const row of rows) {
+            db.prepare(`UPDATE delegations
+				 SET status = ?, result_text = ?, run_boundary = COALESCE(?, run_boundary), updated_at = ?
+				 WHERE parent_session_id = ? AND delegation_id = ? AND status IN ('accepted', 'running', 'dispatching')`).run(event.status, event.message, event.controlId === undefined ? (event.workVersion ?? 0) : null, now, parentSessionId, row.delegation_id);
+            const receipt = readReceipt(db, parentSessionId, row.delegation_id);
+            if (receipt !== undefined)
+                stored.push(receipt);
+        }
+        return stored;
+    });
+    for (const receipt of settled)
+        notify(receipt.parentSessionId, receipt.delegationId);
+    return settled;
+}
+/**
+ * A control operation that outlived the process that started it can never be confirmed: the child
+ * may have compacted, may still be compacting, or may never have started. It is recorded as
+ * uncertain instead of being replayed, because replaying compaction is not idempotent.
+ */
+export function sweepControlReceipts(filePath, parentSessionId, message) {
+    const db = openStateDb(filePath);
+    const swept = withWrite(db, () => {
+        const rows = db
+            .prepare(`SELECT delegation_id FROM delegations
+				 WHERE parent_session_id = ? AND control_id IS NOT NULL
+				   AND status IN ('accepted', 'running')`)
+            .all(parentSessionId);
+        const now = Date.now();
+        const stored = [];
+        for (const row of rows) {
+            db.prepare(`UPDATE delegations SET status = 'uncertain', result_text = ?, updated_at = ?
+				 WHERE parent_session_id = ? AND delegation_id = ? AND status IN ('accepted', 'running')`).run(message, now, parentSessionId, row.delegation_id);
+            const receipt = readReceipt(db, parentSessionId, row.delegation_id);
+            if (receipt !== undefined)
+                stored.push(receipt);
+        }
+        return stored;
+    });
+    for (const receipt of swept)
+        notify(receipt.parentSessionId, receipt.delegationId);
+    return swept;
+}
+export function listReceipts(filePath, parentSessionId, cursor = 0, limit = 20) {
+    const db = openStateDb(filePath);
+    const safeLimit = Number.isInteger(limit) && limit > 0 ? Math.min(limit, 50) : 20;
+    const safeCursor = Number.isInteger(cursor) && cursor > 0 ? cursor : 0;
+    const rows = db
+        .prepare(`SELECT delegation_id FROM delegations
+			 WHERE parent_session_id = ? ORDER BY updated_at DESC LIMIT ? OFFSET ?`)
+        .all(parentSessionId, safeLimit + 1, safeCursor);
+    const receipts = rows.slice(0, safeLimit).flatMap((row) => {
+        const receipt = readReceipt(db, parentSessionId, row.delegation_id);
+        return receipt === undefined ? [] : [receipt];
+    });
+    return rows.length > safeLimit ? { receipts, nextCursor: safeCursor + safeLimit } : { receipts };
+}
+/** Stop or shutdown: every open delegation for this child fails, so a waiter cannot hang. */
+export function abandonReceipts(filePath, parentSessionId, childId, message) {
+    const db = openStateDb(filePath);
+    const abandoned = withWrite(db, () => {
+        const rows = db
+            .prepare(`SELECT delegation_id FROM delegations
+				 WHERE parent_session_id = ? AND child_id = ?
+				   AND status IN ('reserved', 'dispatching', 'accepted', 'running')`)
+            .all(parentSessionId, childId);
+        const now = Date.now();
+        const stored = [];
+        for (const row of rows) {
+            db.prepare(`UPDATE delegations SET status = 'failed', result_text = ?, updated_at = ?
+				 WHERE parent_session_id = ? AND delegation_id = ?
+				   AND status IN ('reserved', 'dispatching', 'accepted', 'running')`).run(message, now, parentSessionId, row.delegation_id);
+            const receipt = readReceipt(db, parentSessionId, row.delegation_id);
+            if (receipt !== undefined)
+                stored.push(receipt);
+        }
+        return stored;
+    });
+    for (const receipt of abandoned)
+        notify(receipt.parentSessionId, receipt.delegationId);
+    return abandoned;
+}
+export function maxRunBoundary(filePath, parentSessionId, childId) {
+    const db = openStateDb(filePath);
+    const row = db
+        .prepare(`SELECT MAX(run_boundary) AS boundary FROM delegations
+			 WHERE parent_session_id = ? AND child_id = ?`)
+        .get(parentSessionId, childId);
+    return row?.boundary ?? 0;
+}
+export function readStoredReceipt(filePath, parentSessionId, delegationId) {
+    return readReceipt(openStateDb(filePath), parentSessionId, delegationId);
+}
+export function readReceiptRevision(filePath, parentSessionId, childId, revision) {
+    const db = openStateDb(filePath);
+    const row = db
+        .prepare("SELECT delegation_id FROM delegations WHERE parent_session_id = ? AND child_id = ? AND delegation_revision = ?")
+        .get(parentSessionId, childId, revision);
+    return row === undefined ? undefined : readReceipt(db, parentSessionId, row.delegation_id);
+}
+export function latestReceiptForChild(filePath, parentSessionId, childId) {
+    const db = openStateDb(filePath);
+    const row = db
+        .prepare(`SELECT delegation_id FROM delegations
+			 WHERE parent_session_id = ? AND child_id = ?
+			 ORDER BY rowid DESC LIMIT 1`)
+        .get(parentSessionId, childId);
+    if (row === undefined)
+        return undefined;
+    return readReceipt(db, parentSessionId, row.delegation_id);
+}
+/** A failed or uncertain receipt stores a reason, not an answer. */
+export function receiptCarriesOutput(status, resultText) {
+    return resultText !== undefined && status !== "failed" && status !== "uncertain";
+}
+export function latestReceiptSummaries(filePath, parentSessionId) {
+    const db = openStateDb(filePath);
+    const rows = db
+        .prepare(`SELECT child_id, delegation_id, delegation_revision, status,
+			        result_text IS NOT NULL AND status NOT IN ('failed', 'uncertain') AS has_output
+			 FROM delegations
+			 WHERE parent_session_id = ? AND child_id IS NOT NULL
+			   AND rowid IN (
+			     SELECT MAX(rowid) FROM delegations
+			     WHERE parent_session_id = ? AND child_id IS NOT NULL GROUP BY child_id
+			   )`)
+        .all(parentSessionId, parentSessionId);
+    const summaries = new Map();
+    for (const row of rows) {
+        if (!isStatus(row.status) || row.delegation_revision === null)
+            continue;
+        summaries.set(row.child_id, {
+            childId: row.child_id,
+            delegationId: row.delegation_id,
+            revision: row.delegation_revision,
+            status: row.status,
+            hasOutput: row.has_output === 1,
+        });
+    }
+    return summaries;
+}
+export function waitForReceipt(filePath, parentSessionId, delegationId, signal) {
+    const current = readStoredReceipt(filePath, parentSessionId, delegationId);
+    if (current !== undefined && terminalReceipt(current.status))
+        return Promise.resolve(current);
+    return new Promise((resolve, reject) => {
+        const key = waiterKey(parentSessionId, delegationId);
+        const wake = () => {
+            const receipt = readStoredReceipt(filePath, parentSessionId, delegationId);
+            if (receipt === undefined || !terminalReceipt(receipt.status))
+                return;
+            finish();
+            resolve(receipt);
+        };
+        const fail = () => {
+            finish();
+            reject(signal?.reason instanceof Error ? signal.reason : new Error("Delegation wait aborted"));
+        };
+        const finish = () => {
+            signal?.removeEventListener("abort", fail);
+            const set = waiters.get(key);
+            set?.delete(wake);
+            if (set !== undefined && set.size === 0)
+                waiters.delete(key);
+        };
+        const set = waiters.get(key) ?? new Set();
+        set.add(wake);
+        waiters.set(key, set);
+        if (signal !== undefined) {
+            if (signal.aborted) {
+                fail();
+                return;
+            }
+            signal.addEventListener("abort", fail, { once: true });
+        }
+        wake();
+    });
+}
+function parseSideEffects(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed)
+            ? parsed.filter((item) => typeof item === "string")
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+function nextRevision(db, parentSessionId, childId) {
+    const row = db
+        .prepare("SELECT MAX(delegation_revision) AS revision FROM delegations WHERE parent_session_id = ? AND child_id = ?")
+        .get(parentSessionId, childId);
+    return (row.revision ?? 0) + 1;
+}
+function readReceipt(db, parentSessionId, delegationId) {
+    const row = db
+        .prepare(`SELECT delegation_id, child_id, delegation_revision, task, input_checkpoint, run_boundary, control_id, status, delivery, result_text, safe_to_retry, side_effects, created_at, updated_at
+			 FROM delegations WHERE parent_session_id = ? AND delegation_id = ?`)
+        .get(parentSessionId, delegationId);
+    if (row === undefined ||
+        !isStatus(row.status) ||
+        (row.delivery !== "pending" && row.delivery !== "detached")) {
+        return undefined;
+    }
+    return {
+        parentSessionId,
+        delegationId: row.delegation_id,
+        task: row.task,
+        status: row.status,
+        delivery: row.delivery,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        ...(row.child_id === null ? {} : { childId: row.child_id }),
+        ...(row.delegation_revision === null ? {} : { revision: row.delegation_revision }),
+        ...(row.input_checkpoint === null ? {} : { inputCheckpoint: row.input_checkpoint }),
+        ...(row.run_boundary === null ? {} : { runBoundary: row.run_boundary }),
+        ...(row.control_id === null ? {} : { controlId: row.control_id }),
+        ...(row.safe_to_retry === null ? {} : { safeToRetry: row.safe_to_retry === 1 }),
+        ...(row.side_effects === null ? {} : { sideEffects: parseSideEffects(row.side_effects) }),
+        ...(row.result_text === null ? {} : { resultText: row.result_text }),
+    };
+}
+function isStatus(value) {
+    return (value === "reserved" ||
+        value === "dispatching" ||
+        value === "accepted" ||
+        value === "running" ||
+        value === "completed" ||
+        value === "blocked" ||
+        value === "failed" ||
+        value === "uncertain");
+}
+function waiterKey(parentSessionId, delegationId) {
+    return `${parentSessionId}\n${delegationId}`;
+}
+function notify(parentSessionId, delegationId) {
+    const set = waiters.get(waiterKey(parentSessionId, delegationId));
+    if (set === undefined)
+        return;
+    for (const wake of set)
+        wake();
+}

package/dist/runtime.d.ts

@@ -2,35 +2,14 @@ import { type ChildRuntime } from "./child-process.js";
 import type { SubagentRecord } from "./domain.js";
 import type { HostAdapter, HostAttachment } from "./host-adapter.js";
 import type { SubagentRegistry } from "./registry.js";
-/** Per-runtime bridge tokens, kept out of the registry because they are credentials. */
-export interface RuntimeTokenStore {
-    remember(runtimeIdentity: string, token: string): void;
-    get(runtimeIdentity: string): string | undefined;
-    forget(runtimeIdentity: string): void;
-}
-export interface RuntimeTokenStoreOptions {
-    /** The parent session these tokens belong to. */
-    readonly parentSessionId: string;
-    /** Override for tests. Defaults to this parent's file in the shared runtime directory. */
-    readonly file?: string;
-    readonly diagnose?: (message: string) => void;
-}
 /**
- * The one socket a parent session listens on. A child dials this path, so a parent that restarts
- * re-listens in the same place and a surviving child reconnects instead of being rebuilt.
+ * The one mailbox a parent session reads. A child polls this path, so a parent that restarts reads
+ * the same file and a surviving child reconnects instead of being rebuilt.
  */
 export declare function parentBridgeEndpoint(_parentSessionId: string): string;
-/** Tokens live in the same sqlite file as the child ledger. Rows do not clobber each other. */
-export declare function parentTokenFile(_parentSessionId: string): string;
-/**
- * Tokens outlive the parent process. A restarted parent reads the same sqlite file and can still
- * match the token a surviving child was launched with.
- */
-export declare function createRuntimeTokenStore(options: RuntimeTokenStoreOptions): RuntimeTokenStore;
 export interface LaunchChildOptions {
     readonly registry: Pick<SubagentRegistry, "get" | "update">;
     readonly record: SubagentRecord;
-    readonly tokens: RuntimeTokenStore;
     /** Waits for this child's bridge connection; false when it did not connect in time. */
     readonly waitForBridge: (childId: string, signal?: AbortSignal) => Promise<boolean>;
     readonly signal?: AbortSignal;
@@ -38,9 +17,9 @@ export interface LaunchChildOptions {
 }
 /**
  * Starts one headless child Pi and waits for it to connect. Nothing is driven over its stdio: the
- * process gets the parent's socket path and its own runtime token in the environment, and the
- * bridge is the only control channel. A child that never connects is terminated here rather than
- * left running with no way to reach it.
+ * process gets the parent's mailbox path in its environment, and the bridge is the only control
+ * channel. A child that never connects is terminated here rather than left running with no way to
+ * reach it.
  */
 export declare function launchChild(options: LaunchChildOptions): Promise<LaunchOutcome<ChildRuntime>>;
 export interface OpenChildPanelOptions extends LaunchChildOptions {

package/dist/runtime.js

@@ -6,72 +6,33 @@
  * so "is this child alive?" is answered by a bridge connection, and the runtime metadata in the
  * registry only records which runtime and endpoint a child was last launched with.
  */
-import { randomBytes, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { chmod, mkdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { errorMessage } from "@hheei/pi-ext-core";
 import { spawnChildRuntime } from "./child-process.js";
-import { buildLaunchSpec, withBridgeToken } from "./launch-spec.js";
+import { buildLaunchSpec } from "./launch-spec.js";
 import { commitLease } from "./lease.js";
-import { defaultStatePath, deleteToken, openStateDb, readToken, writeToken } from "./state-db.js";
+import { defaultStatePath } from "./state-db.js";
 function runtimeDirectory() {
     const user = typeof process.getuid === "function" ? process.getuid() : "user";
     return join(tmpdir(), `pi-subagents-${user}`);
 }
 /**
- * The one socket a parent session listens on. A child dials this path, so a parent that restarts
- * re-listens in the same place and a surviving child reconnects instead of being rebuilt.
+ * The one mailbox a parent session reads. A child polls this path, so a parent that restarts reads
+ * the same file and a surviving child reconnects instead of being rebuilt.
  */
 export function parentBridgeEndpoint(_parentSessionId) {
     return defaultStatePath();
 }
-/** Tokens live in the same sqlite file as the child ledger. Rows do not clobber each other. */
-export function parentTokenFile(_parentSessionId) {
-    return defaultStatePath();
-}
-/**
- * Tokens outlive the parent process. A restarted parent reads the same sqlite file and can still
- * match the token a surviving child was launched with.
- */
-export function createRuntimeTokenStore(options) {
-    const file = options.file ?? defaultStatePath();
-    const diagnose = options.diagnose ?? (() => { });
-    let db;
-    try {
-        db = openStateDb(file);
-    }
-    catch (error) {
-        diagnose(`could not open the state database: ${errorMessage(error)}`);
-    }
-    const database = db;
-    return {
-        remember(runtimeIdentity, token) {
-            if (database === undefined)
-                return;
-            writeToken(database, options.parentSessionId, runtimeIdentity, token);
-        },
-        get(runtimeIdentity) {
-            if (database === undefined)
-                return undefined;
-            return readToken(database, options.parentSessionId, runtimeIdentity);
-        },
-        forget(runtimeIdentity) {
-            if (database === undefined)
-                return;
-            deleteToken(database, options.parentSessionId, runtimeIdentity);
-        },
-    };
-}
 /**
- * Mints the runtime identity and its bridge token, remembers the token so the child's very first
- * hello can be authorized, and builds the one LaunchSpec for this presentation. The token travels
- * in the spec's environment, because who starts the child differs: the parent starts a background
- * child and the host starts a panel one.
+ * Mints the runtime identity and builds the one LaunchSpec for this presentation. Who starts the
+ * child differs (this parent for a background child, the host for a panel one), but the spec does
+ * not.
  */
-function planChildRuntime(record, tokens, presentation) {
+function planChildRuntime(record, presentation) {
     const runtimeIdentity = randomUUID();
-    const token = randomBytes(32).toString("hex");
     const endpoint = parentBridgeEndpoint(record.parentSessionId);
     const spec = buildLaunchSpec({
         config: record.launchConfig,
@@ -85,8 +46,7 @@ function planChildRuntime(record, tokens, presentation) {
             endpoint,
         },
     });
-    tokens.remember(runtimeIdentity, token);
-    return { runtimeIdentity, endpoint, spec: { ...spec, env: withBridgeToken(spec.env, token) } };
+    return { runtimeIdentity, endpoint, spec };
 }
 /** Evidence first: the record names the runtime that was asked for even if starting it fails. */
 async function recordRuntimeEvidence(registry, record, plan) {
@@ -98,13 +58,13 @@ async function recordRuntimeEvidence(registry, record, plan) {
 }
 /**
  * Starts one headless child Pi and waits for it to connect. Nothing is driven over its stdio: the
- * process gets the parent's socket path and its own runtime token in the environment, and the
- * bridge is the only control channel. A child that never connects is terminated here rather than
- * left running with no way to reach it.
+ * process gets the parent's mailbox path in its environment, and the bridge is the only control
+ * channel. A child that never connects is terminated here rather than left running with no way to
+ * reach it.
  */
 export async function launchChild(options) {
     const record = options.record;
-    const plan = planChildRuntime(record, options.tokens, "background");
+    const plan = planChildRuntime(record, "background");
     await recordRuntimeEvidence(options.registry, record, plan);
     const runtime = spawnChildRuntime({
         command: plan.spec.command,
@@ -133,13 +93,12 @@ export async function launchChild(options) {
             failure: `Child ${record.subagentId} never connected to the parent bridge and did not stop (it may still be running)`,
         };
     }
-    options.tokens.forget(plan.runtimeIdentity);
     await commitLease(options.registry, record.subagentId, { type: "runtime-gone", outcome: "clear" }, undefined, plan.runtimeIdentity);
     return { failure: `Child ${record.subagentId} never connected to the parent bridge` };
 }
 export async function openChildPanel(options) {
     const record = options.record;
-    const plan = planChildRuntime(record, options.tokens, "panel");
+    const plan = planChildRuntime(record, "panel");
     await recordRuntimeEvidence(options.registry, record, plan);
     let attachment;
     try {
@@ -200,7 +159,6 @@ export async function openChildPanel(options) {
             failure: `Child ${record.subagentId} never connected to the parent bridge and its panel could not be closed (${cleanup.stderr || "its state could not be observed"}); close it manually`,
         };
     }
-    options.tokens.forget(plan.runtimeIdentity);
     await commitLease(options.registry, record.subagentId, { type: "runtime-gone", outcome: "clear" }, undefined, plan.runtimeIdentity);
     const detail = earlyExitObserved?.detail ? ` (${earlyExitObserved.detail.trim()})` : "";
     return { failure: `Child ${record.subagentId} never connected to the parent bridge${detail}` };

package/dist/session-bootstrap.js

@@ -165,15 +165,12 @@ export function createSubagentId(existingIds) {
 export async function resolveSubagentLaunch(options) {
     const task = options.input.task.trim();
     if (task === "")
-        throw new Error("agent_spawn requires a non-empty task");
+        throw new Error("agents_delegate requires a non-empty task");
     const name = options.input.agent?.trim();
     if (name === undefined || name === "") {
-        throw new Error("agent_spawn requires an explicit agent name; V1 has no built-in default agent");
+        throw new Error("agents_delegate requires an explicit agent name; V1 has no built-in default agent");
     }
     const cwd = resolve(options.input.cwd?.trim() || options.cwd);
-    const requestedTitle = options.input.title?.trim();
-    // A blank title is the same as no title: the child derives one from its own identity.
-    const title = requestedTitle === "" ? undefined : requestedTitle;
     const subagentId = options.subagentId ?? createSubagentId(options.existingSubagentIds);
     const sessionId = options.sessionId ?? randomUUID();
     const bridgeExtensionPath = options.bridgeExtensionPath ?? resolveBridgeExtensionPath();
@@ -209,7 +206,6 @@ export async function resolveSubagentLaunch(options) {
         prompt: assembleChildPrompt(instructions),
         bridgeExtensionPath,
         ...(policy.codemodeOnly ? { codemodeOnly: true } : {}),
-        ...(title === undefined ? {} : { title }),
     });
 }
 /**

package/dist/state-db.d.ts

@@ -1,5 +1,5 @@
 import { DatabaseSync } from "node:sqlite";
-/** The one durable file for child records, commands, and tokens. */
+/** The one durable file for child records, the mailbox, and delegation receipts. */
 export declare function defaultStatePath(): string;
 export declare function openStateDb(filePath: string): DatabaseSync;
 export declare function withWrite<T>(db: DatabaseSync, run: () => T): T;
@@ -47,6 +47,13 @@ export declare function finishCommand(db: DatabaseSync, id: string, outcome: {
     readonly errorCode: string;
     readonly error: string;
 }): void;
-export declare function readToken(db: DatabaseSync, parentSessionId: string, runtimeIdentity: string): string | undefined;
-export declare function writeToken(db: DatabaseSync, parentSessionId: string, runtimeIdentity: string, token: string): void;
-export declare function deleteToken(db: DatabaseSync, parentSessionId: string, runtimeIdentity: string): void;
+/**
+ * A settled command whose waiter died with its process has no reader left. Only a parent that is
+ * taking over the mailbox may run this: a live waiter deletes its own row when it reads it.
+ */
+export declare function deleteSettledCommands(db: DatabaseSync, parentSessionId: string): void;
+/**
+ * Keeps only the newest `keep` queued events for one child. Events are advisory snapshots, so a
+ * parent that stopped reading must not leave an unbounded backlog behind.
+ */
+export declare function trimEventBacklog(db: DatabaseSync, parentSessionId: string, subagentId: string, keep: number): void;