@hheei/pi-subagents 0.6.0 → 0.8.0

package/dist/manager.js

@@ -1,10 +1,14 @@
+import { createReadStream } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
 import { errorMessage, isRecord } from "@hheei/pi-ext-core";
 import { attachRetainedChild } from "./child-process.js";
+import { agentView, delegationView, } from "./delegation.js";
 import { isOperationError } from "./domain.js";
 import { stripHindsightContent } from "./launch-spec.js";
 import { commitLease, createConversationLease, RUNTIME_ENDED_RESUME, } from "./lease.js";
 import { BridgeError, isChildInputPayload, isChildLifecyclePayload, isContactReportPayload, } from "./protocol.js";
+import { abandonReceipts, latestReceiptForChild, latestReceiptSummaries, maxRunBoundary, readReceiptRevision, readStoredReceipt, reserveReceipt, settleReceipts, sweepControlReceipts, terminalReceipt, updateReceipt, waitForReceipt, } from "./receipts.js";
 import { findSessionFile, planSessionPlacement } from "./session-bootstrap.js";
 async function readSessionJsonlEntries(filePath) {
     const content = await readFile(filePath, "utf8");
@@ -22,10 +26,53 @@ async function readSessionJsonlEntries(filePath) {
     }
     return entries;
 }
+/** One transcript page, parsed only through the requested window. */
+async function readSessionJsonlPage(filePath, cursor, limit) {
+    const entries = [];
+    let index = 0;
+    let past = false;
+    const stream = createReadStream(filePath, { encoding: "utf8" });
+    stream.on("error", () => {
+        // The async iterator rejects with the same error; the listener keeps it from escaping.
+    });
+    const lines = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            if (index >= cursor) {
+                if (entries.length >= limit) {
+                    past = true;
+                    break;
+                }
+                entries.push(parsed);
+            }
+            index += 1;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        lines.close();
+        stream.destroy();
+    }
+    if (index === 0 && entries.length === 0)
+        return undefined;
+    return { entries, ...(past ? { nextCursor: cursor + entries.length } : {}) };
+}
 import { createStateProjector, parseTranscriptFacts, transcriptFacts, } from "./state.js";
 /**
  * How long an idle child keeps its runtime. A background child holds a whole Pi process and its
- * session lock, so an idle one is reclaimed after this window and a later `agent_send` starts it
+ * session lock, so an idle one is reclaimed after this window and a later `agents_delegate` starts it
  * again from the same session.
  */
 export const SUBAGENT_IDLE_TIMEOUT_MS = 15_000;
@@ -56,6 +103,18 @@ function acknowledgedPath(response) {
     }
     return response.path;
 }
+/** A compaction request is a control operation, not a turn. */
+function isCompactCommand(task) {
+    const trimmed = task.trim();
+    return trimmed === "/compact" || trimmed.startsWith("/compact ");
+}
+/** The child names the compaction a request started or joined; without it, nothing can settle it. */
+function acknowledgedControl(response) {
+    if (!isRecord(response) || typeof response.controlId !== "string" || response.controlId === "") {
+        throw new BridgeError("invalid_state", "Child did not confirm which compaction it runs");
+    }
+    return response.controlId;
+}
 function publicChild(record, live, path = record.sessionPath) {
     return {
         id: record.subagentId,
@@ -131,6 +190,8 @@ export class SubagentManager {
      * process is not this child's runtime any more, so it is neither live nor ours to close.
      */
     #leftSessions = new Set();
+    /** Aborted on dispose, so no wait or delivery survives the session it belongs to. */
+    #disposed = new AbortController();
     /** Bumped by every inbound bridge signal, so a reclaim in flight can tell the child moved. */
     #activity = new Map();
     #projectors = new Map();
@@ -140,6 +201,16 @@ export class SubagentManager {
     #working = new Set();
     /** A settled event from an older run cannot clear a newer synchronous start signal. */
     #workVersions = new Map();
+    /** Highest run boundary reserved for a child that has not reached that turn yet. */
+    #lastClaim = new Map();
+    /** The compaction a child's last confirmed input controls, instead of a run boundary. */
+    #lastControl = new Map();
+    #recentSettlement = new Map();
+    /**
+     * Waiting delegations of this process, by child. Occupancy lives here and not in the ledger: a
+     * stored `pending` row is history, and a waiter of a previous process does not exist any more.
+     */
+    #waiters = new Map();
     #settledPanelCloseTimers = new Map();
     #pendingAutoReports = new Map();
     #autoReportBatchTimer;
@@ -162,11 +233,14 @@ export class SubagentManager {
         };
     }
     dispose() {
+        // Ending the session ends its waits: a pending tool call must not outlive the manager.
+        this.#disposed.abort();
         if (this.#autoReportBatchTimer !== undefined) {
             clearTimeout(this.#autoReportBatchTimer);
             this.#autoReportBatchTimer = undefined;
         }
         this.#pendingAutoReports.clear();
+        this.#waiters.clear();
         for (const timer of this.#settledPanelCloseTimers.values()) {
             clearTimeout(timer);
         }
@@ -186,6 +260,7 @@ export class SubagentManager {
             this.#autoReportBatchTimer = undefined;
         }
         this.#pendingAutoReports.clear();
+        this.#waiters.clear();
         this.#processes.clear();
         this.#attachments.clear();
         this.#leftSessions.clear();
@@ -194,6 +269,9 @@ export class SubagentManager {
         this.#paths.clear();
         this.#working.clear();
         this.#workVersions.clear();
+        this.#lastClaim.clear();
+        this.#lastControl.clear();
+        this.#recentSettlement.clear();
         this.#notify();
     }
     /**
@@ -347,10 +425,7 @@ export class SubagentManager {
         const current = await this.#deps.registry.get(id);
         if (current === undefined)
             return undefined;
-        const identity = current.runtime?.runtimeIdentity;
         const next = await commitLease(this.#deps.registry, id, { type: "runtime-gone", outcome });
-        if (identity !== undefined && next.runtime === undefined)
-            this.#deps.tokens?.forget(identity);
         if (outcome === "drop" &&
             current.state === "running" &&
             current.intent !== "stopped" &&
@@ -546,6 +621,12 @@ export class SubagentManager {
                         state: "done",
                     };
                 });
+                this.#recordSettlement({
+                    childId: id,
+                    status: "failed",
+                    message: "Subagent finished without a result.",
+                    workVersion,
+                });
                 return;
             }
             let message;
@@ -570,13 +651,19 @@ export class SubagentManager {
             else {
                 message = text ?? "";
             }
+            const reason = isError ? "error" : isBlocked ? "blocked" : "success";
+            if (reason === "success" &&
+                facts?.contextTokens !== undefined &&
+                facts.contextTokens >= 100_000) {
+                const kTokens = `${Math.round(facts.contextTokens / 1000)}k`;
+                message = `${message}\n\n[Context: ~${kTokens} tokens. If retaining this subagent for future tasks, send "/compact" via agents_delegate to trim memory.]`;
+            }
             const lastDelivered = this.#lastDeliveredTurn.get(id);
             if (lastDelivered !== undefined &&
                 lastDelivered.workVersion === workVersion &&
                 lastDelivered.message === message) {
                 return;
             }
-            const reason = isError ? "error" : isBlocked ? "blocked" : "success";
             const projector = this.#projectors.get(id);
             const updatedRecord = !failed
                 ? await this.#update(id, (current) => {
@@ -595,8 +682,20 @@ export class SubagentManager {
                 projector.syncState(isError ? "error" : isBlocked ? "blocked" : "done");
             }
             this.#scheduleSettledPanelClose(id);
+            // The receipt is the durable record of this turn: it is written before delivery is
+            // coordinated, so a delivery failure cannot leave a settled turn looking unfinished.
+            const settled = this.#recordSettlement({
+                childId: id,
+                status: isError ? "failed" : isBlocked ? "blocked" : "completed",
+                message,
+                workVersion,
+            });
+            // Without a durable settlement there is no record to deliver against: the turn stays
+            // unsettled and undelivered rather than being pushed and then pushed again on a retry.
+            if (settled === undefined)
+                return;
             let deliveryOk = true;
-            if (this.#deps.channel !== undefined) {
+            if (!this.#claimedByWaiter(settled) && this.#deps.channel !== undefined) {
                 const contactResult = await this.contactParent(id, reason, message, updatedRecord);
                 if (isOperationError(contactResult)) {
                     deliveryOk = false;
@@ -608,8 +707,8 @@ export class SubagentManager {
         });
     }
     /** Reads a child's session entries; used by transcript inspection fallbacks. */
-    async getEntries(id) {
-        return this.#entries(id);
+    async getEntries(id, range) {
+        return this.#entries(id, range?.cursor ?? 0, range?.limit ?? 20);
     }
     /** A child is live while its bridge connection is up, or while a process we started still runs. */
     #isLive(id) {
@@ -692,18 +791,137 @@ export class SubagentManager {
         return entries === undefined ? undefined : transcriptFacts(entries, expectedInput);
     }
     /** Reads a child's session entries over the bridge, falling back to disk when disconnected. */
-    async #entries(id) {
+    async #entries(id, cursor = 0, limit = 20) {
         if (this.#deps.bridge.isConnected(id)) {
-            const response = await this.#request(id, "get_entries").catch(() => undefined);
-            if (isRecord(response) && Array.isArray(response.entries) && response.entries.length > 0) {
-                return response.entries;
+            const response = await this.#request(id, "get_entries", { cursor, limit }).catch(() => undefined);
+            if (isRecord(response) &&
+                Array.isArray(response.entries) &&
+                (response.entries.length > 0 || cursor > 0)) {
+                const nextCursor = typeof response.nextCursor === "number" ? response.nextCursor : undefined;
+                return {
+                    entries: response.entries,
+                    ...(nextCursor === undefined ? {} : { nextCursor }),
+                };
             }
         }
-        return this.#diskEntries(id);
+        const record = await this.#deps.registry.get(id).catch(() => undefined);
+        if (record === undefined)
+            return undefined;
+        const sessionPath = record.sessionPath ??
+            (await findSessionFile(record.launchConfig.sessionDir, record.sessionId));
+        if (sessionPath === undefined)
+            return undefined;
+        return readSessionJsonlPage(sessionPath, cursor, limit);
     }
     #request(id, operation, payload) {
         return withDeadline(this.#deps.bridge.request(id, operation, payload), this.#deps.deadlineMs ?? 30_000);
     }
+    /**
+     * Binds one confirmed input to a Pi work version. A steer into a turn that already started
+     * (`agent_start` has incremented the version) shares that version. Anything still queued
+     * reserves the next version, so a later completion cannot answer both.
+     */
+    #restoreWorkVersion(id) {
+        const stored = maxRunBoundary(this.#deps.registry.path, this.#deps.parentSessionId, id);
+        const current = this.#workVersions.get(id) ?? 0;
+        if (stored > current)
+            this.#workVersions.set(id, stored);
+        const claim = this.#lastClaim.get(id) ?? 0;
+        if (stored > claim)
+            this.#lastClaim.set(id, stored);
+    }
+    #claimRunBoundary(id, joining) {
+        // A steer into a turn that already started shares that turn's version. Anything else opens
+        // the next one, which is exactly the version the child's `agent_start` will announce, even
+        // when that announcement wins the race against this dispatch's own acknowledgement.
+        const current = this.#workVersions.get(id) ?? 0;
+        const claimed = joining && current > 0 ? current : current + 1;
+        this.#lastClaim.set(id, claimed);
+        return claimed;
+    }
+    /**
+     * Binds one confirmed input to what can settle it. A compaction is a control operation: it opens
+     * no turn, so it is bound to the child's operation id rather than to a work version that would
+     * never arrive.
+     */
+    #claimDispatch(id, response, claim) {
+        if (claim === undefined) {
+            this.#lastClaim.delete(id);
+            this.#lastControl.set(id, acknowledgedControl(response));
+            return;
+        }
+        this.#lastControl.delete(id);
+        this.#lastClaim.set(id, claim);
+    }
+    #claimedSubmission(id) {
+        const controlId = this.#lastControl.get(id);
+        if (controlId !== undefined)
+            return { controlId };
+        const workVersion = this.#lastClaim.get(id);
+        if (workVersion === undefined) {
+            throw new Error(`Delegation for ${id} was not bound to a run`);
+        }
+        const recent = this.#recentSettlement.get(id);
+        return recent?.workVersion === workVersion ? { workVersion, settled: recent } : { workVersion };
+    }
+    /**
+     * Records a settlement in the ledger and returns what it settled. `undefined` means the write
+     * itself failed: nothing was recorded, so no consumer may treat the turn as delivered and the
+     * caller that can retry is told about it instead.
+     */
+    #recordSettlement(event) {
+        this.#recentSettlement.set(event.childId, event);
+        // The ledger is the manager's own, so a settlement is durable before any consumer sees it and
+        // no caller has to wire this up for delegated turns to settle.
+        try {
+            return settleReceipts(this.#deps.registry.path, this.#deps.parentSessionId, event);
+        }
+        catch (error) {
+            diagnose(`failed to record settlement for ${event.childId}: ${errorMessage(error)}`);
+            return undefined;
+        }
+    }
+    /**
+     * True when a waiting tool call owns this settlement. A steer into the turn it is waiting on is
+     * answered by the same settlement, so pushing it would deliver that turn twice; a compaction has
+     * no boundary of its own and stays a separate result.
+     */
+    #claimedByWaiter(settled) {
+        return settled.some((receipt) => {
+            const childId = receipt.childId;
+            if (childId === undefined)
+                return false;
+            const waiter = this.#waiters.get(childId);
+            if (waiter === undefined || waiter.aborted)
+                return false;
+            if (waiter.delegationId === receipt.delegationId)
+                return true;
+            return waiter.runBoundary !== undefined && receipt.runBoundary === waiter.runBoundary;
+        });
+    }
+    /**
+     * Delivers a settled turn whose waiting tool call went away. The result is already durable, so
+     * this is the same automatic delivery an unwatched turn gets, not a second copy of it.
+     */
+    async #pushSettled(receipt) {
+        const childId = receipt.childId;
+        if (this.#deps.channel === undefined || childId === undefined)
+            return;
+        const text = receipt.resultText;
+        if (text === undefined)
+            return;
+        const record = await this.#deps.registry.get(childId);
+        if (record === undefined)
+            return;
+        const reason = receipt.status === "completed"
+            ? "success"
+            : receipt.status === "blocked"
+                ? "blocked"
+                : "error";
+        await this.contactParent(childId, reason, text, record).catch((error) => {
+            diagnose(`failed to deliver the settled turn of ${childId}: ${errorMessage(error)}`);
+        });
+    }
     #notify() {
         for (const listener of this.#listeners) {
             try {
@@ -720,6 +938,14 @@ export class SubagentManager {
      * until a later send starts it from its recorded session.
      */
     async recover() {
+        // A compaction that was in flight when this process started cannot be confirmed or replayed, so
+        // it ends as uncertain instead of leaving a waiter on a report that may never come.
+        try {
+            sweepControlReceipts(this.#deps.registry.path, this.#deps.parentSessionId, "Compaction was not confirmed before this parent session restarted");
+        }
+        catch (error) {
+            diagnose(`failed to sweep unconfirmed compactions: ${errorMessage(error)}`);
+        }
         const records = (await this.#deps.registry.list()).filter((record) => record.intent === "active" && record.state === "running");
         const outcomes = await Promise.all(records.map(async (record) => {
             this.#working.add(record.subagentId);
@@ -760,9 +986,14 @@ export class SubagentManager {
             return;
         }
         await this.#releaseRuntime(record.subagentId, "parent-exit");
+        // The interrupted turn will not finish. Leaving it accepted lets the next run reuse its work
+        // boundary and settle the old receipt with the new answer.
+        this.#restoreWorkVersion(record.subagentId);
+        abandonReceipts(this.#deps.registry.path, this.#deps.parentSessionId, record.subagentId, "Delegation was interrupted because the background agent ended with the parent session");
     }
     /** Reads a connected child's real state and puts the record back in step with it. */
     async #adopt(id) {
+        this.#restoreWorkVersion(id);
         const workVersion = this.#workVersions.get(id) ?? 0;
         const projector = this.#projectors.get(id);
         const record = await this.#deps.registry.get(id);
@@ -843,13 +1074,214 @@ export class SubagentManager {
         }
         return { presentation: "panel" };
     }
+    /**
+     * One dispatch path for MCP's new-child and existing-child forms. This only confirms input
+     * delivery; waiting for the specific turn's final report belongs to the MCP delegation receipt,
+     * not to spawn/send or the child's durable identity.
+     */
+    async submitDelegation(input, onTarget) {
+        if (stripHindsightContent(input.task).trim() === "") {
+            return failure("delegate", "Task must not be empty", undefined, undefined, [], false);
+        }
+        if (input.id !== undefined) {
+            if (input.id.trim() === "") {
+                return failure("delegate", "Child id must not be empty", undefined, undefined, [], false);
+            }
+            onTarget?.(input.id);
+            // Ignore agent and cwd entirely: this child's launch config was frozen at spawn.
+            const child = await this.send(input.id, input.task);
+            return isOperationError(child)
+                ? child
+                : { child, action: "reuse", ...this.#claimedSubmission(child.id) };
+        }
+        if (input.agent === undefined || input.agent.trim() === "") {
+            return failure("delegate", "Agent is required without an id", undefined, undefined, [], false);
+        }
+        const spawned = await this.#spawnWith({
+            task: input.task,
+            agent: input.agent,
+            ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
+        }, (config) => onTarget?.(config.subagentId));
+        if (isOperationError(spawned))
+            return spawned;
+        return {
+            child: spawned.child,
+            action: "spawn",
+            ...this.#claimedSubmission(spawned.child.id),
+            ...(spawned.note === undefined ? {} : { note: spawned.note }),
+        };
+    }
+    /**
+     * The acceptance path both consumers share: reserve this delegation's revision, dispatch it into
+     * the agent session, then either wait for that revision's settlement or return its identity.
+     * Waiting never holds the per-agent chain, so settlements and later steers still get in.
+     */
+    async delegate(input, signal, onAccepted) {
+        const wait = input.wait ?? true;
+        const task = stripHindsightContent(input.task).trim();
+        if (task === "") {
+            return failure("delegate", "Task must not be empty", undefined, undefined, [], false);
+        }
+        if (input.id !== undefined && input.id.trim() === "") {
+            return failure("delegate", "Child id must not be empty", undefined, undefined, [], false);
+        }
+        if (input.id === undefined && (input.agent === undefined || input.agent.trim() === "")) {
+            return failure("delegate", "Agent is required without an id", undefined, undefined, [], false);
+        }
+        const filePath = this.#deps.registry.path;
+        const parentSessionId = this.#deps.parentSessionId;
+        if (input.id !== undefined && (await this.#deps.registry.get(input.id)) === undefined) {
+            // Nothing is reserved for a target that does not exist: a revision is only ever spent on
+            // work this parent actually accepted.
+            return failure("delegate", "Unknown child", input.id);
+        }
+        const active = input.id === undefined ? undefined : this.#waiters.get(input.id);
+        if (wait && active !== undefined) {
+            // Refused before anything is dispatched: a conflicted wait must not steer first.
+            return failure("delegate", `Child ${input.id ?? ""} already has a waiting delegation ${active.delegationId}`, input.id);
+        }
+        const target = {};
+        const delivery = wait ? "pending" : "detached";
+        let submitted;
+        try {
+            submitted = await this.submitDelegation(input, (childId) => {
+                target.receipt = this.#reserveDelegation(filePath, parentSessionId, childId, task, delivery);
+                // Registered before dispatch, so a settlement that lands during it already knows the
+                // tool result owns this turn and does not push the same answer as well.
+                if (wait) {
+                    this.#waiters.set(childId, {
+                        delegationId: target.receipt.delegationId,
+                        aborted: false,
+                    });
+                }
+            });
+        }
+        catch (error) {
+            // A refused reservation happened before any dispatch, so nothing has to be undone.
+            return failure("delegate", errorMessage(error), input.id, undefined, [], true);
+        }
+        const receipt = target.receipt;
+        if (receipt === undefined) {
+            // Without a reserved revision nothing was accepted, so this is the dispatch's own refusal.
+            if (isOperationError(submitted))
+                return submitted;
+            return failure("delegate", "Delegation was accepted without a reserved revision");
+        }
+        if (isOperationError(submitted)) {
+            // Only this call's own occupancy is released: a wait:false steer never owns one, so
+            // deleting here would let a second waiter take over a delivery that is already claimed.
+            if (wait)
+                this.#waiters.delete(receipt.childId ?? "");
+            const uncertain = submitted.sideEffects.length > 0 && !submitted.safeToRetry;
+            const failed = updateReceipt(filePath, parentSessionId, receipt.delegationId, {
+                from: ["dispatching"],
+                status: uncertain ? "uncertain" : "failed",
+                resultText: submitted.reason,
+                safeToRetry: submitted.safeToRetry,
+                sideEffects: submitted.sideEffects,
+            });
+            return {
+                ...delegationView(failed ?? receipt),
+                error: {
+                    reason: submitted.reason,
+                    safeToRetry: submitted.safeToRetry,
+                    sideEffects: submitted.sideEffects,
+                },
+            };
+        }
+        const childId = submitted.child.id;
+        const bound = this.#bindDispatch(filePath, parentSessionId, receipt, submitted);
+        if (!wait) {
+            return agentView(bound, submitted.child, { includeOutput: bound.status !== "accepted" });
+        }
+        if (bound.status !== "accepted") {
+            this.#waiters.delete(childId);
+            return agentView(bound, submitted.child, { includeOutput: true });
+        }
+        const waiter = this.#waiters.get(childId);
+        if (waiter !== undefined && bound.runBoundary !== undefined) {
+            waiter.runBoundary = bound.runBoundary;
+        }
+        try {
+            onAccepted?.(await agentView(bound, submitted.child));
+            const settled = await waitForReceipt(filePath, parentSessionId, receipt.delegationId, signal === undefined
+                ? this.#disposed.signal
+                : AbortSignal.any([signal, this.#disposed.signal]));
+            // The runtime moved on while the turn was in flight, so the projection is read fresh.
+            const latest = await this.#deps.registry.get(childId);
+            return await agentView(settled, latest === undefined ? submitted.child : publicChild(latest, false), { includeOutput: true });
+        }
+        catch (error) {
+            // The wait ended, not the delegation. A result the tool result can no longer carry goes
+            // back to the automatic path, so the turn is delivered exactly once either way.
+            if (waiter !== undefined)
+                waiter.aborted = true;
+            const current = readStoredReceipt(filePath, parentSessionId, receipt.delegationId) ?? bound;
+            if (!this.#disposed.signal.aborted && terminalReceipt(current.status)) {
+                await this.#pushSettled(current);
+            }
+            if (signal?.aborted === true || this.#disposed.signal.aborted) {
+                return delegationView(current, submitted.child);
+            }
+            throw error;
+        }
+        finally {
+            if (this.#waiters.get(childId) === waiter)
+                this.#waiters.delete(childId);
+        }
+    }
+    #reserveDelegation(filePath, parentSessionId, childId, task, delivery) {
+        const reserved = reserveReceipt(filePath, { parentSessionId, task, childId, delivery });
+        const dispatching = updateReceipt(filePath, parentSessionId, reserved.delegationId, {
+            from: ["reserved"],
+            status: "dispatching",
+        });
+        if (dispatching === undefined)
+            throw new Error("Delegation was not reserved");
+        return dispatching;
+    }
+    /** Binds the accepted revision to what can settle it: a control operation, or a work version. */
+    #bindDispatch(filePath, parentSessionId, receipt, submitted) {
+        // A settlement that arrived before this binding landed is still that delegation's answer, and
+        // the manager already holds it.
+        const recent = this.#recentSettlement.get(submitted.child.id);
+        const settled = submitted.settled ??
+            (submitted.controlId !== undefined && recent?.controlId === submitted.controlId
+                ? recent
+                : undefined);
+        const bound = updateReceipt(filePath, parentSessionId, receipt.delegationId, {
+            from: ["dispatching"],
+            status: settled === undefined ? "accepted" : settled.status,
+            ...(submitted.controlId !== undefined
+                ? { controlId: submitted.controlId }
+                : submitted.workVersion === undefined
+                    ? {}
+                    : { runBoundary: submitted.workVersion }),
+            ...(settled === undefined ? {} : { resultText: settled.message }),
+        });
+        if (bound !== undefined)
+            return bound;
+        // The turn settled before this binding landed, so the stored row is already past dispatching.
+        const current = readStoredReceipt(filePath, parentSessionId, receipt.delegationId);
+        if (current === undefined)
+            throw new Error("Delegation acceptance was lost");
+        return current;
+    }
     async spawn(input) {
+        return this.#spawnWith(input);
+    }
+    /**
+     * The spawn path with one seam: a caller that must own the new identity (a delegation reserves
+     * its revision) sees it here, after it is minted and before anything is persisted or launched.
+     */
+    async #spawnWith(input, onConfig) {
         const cleanTask = stripHindsightContent(input.task).trim();
         if (cleanTask === "")
             return failure("spawn", "Task must not be empty");
         let childId;
         try {
             const config = await withDeadline(this.#deps.resolve(input), this.#deps.deadlineMs ?? 30_000);
+            onConfig?.(config);
             const cleanTask = stripHindsightContent(input.task);
             const placement = this.#placement(input);
             if ("reason" in placement)
@@ -866,9 +1298,16 @@ export class SubagentManager {
             this.#notify();
             await withDeadline(this.#start(record), this.#deps.deadlineMs ?? 60_000);
             let path;
+            // A fresh child's first turn is version 1, claimed before the prompt goes out so a
+            // preceding `agent_start` cannot push the receipt onto a version that never settles.
+            const claim = isCompactCommand(cleanTask)
+                ? undefined
+                : this.#claimRunBoundary(record.subagentId, false);
             try {
-                path = acknowledgedPath(await this.#request(record.subagentId, "prompt", { message: cleanTask }));
+                const response = await this.#request(record.subagentId, "prompt", { message: cleanTask });
+                path = acknowledgedPath(response);
                 this.#paths.set(record.subagentId, path);
+                this.#claimDispatch(record.subagentId, response, claim);
             }
             catch (error) {
                 let failureState = "error";
@@ -923,7 +1362,11 @@ export class SubagentManager {
             return failed;
         }
     }
-    send(id, rawMessage, mode = "steer", signal) {
+    send(id, rawMessage, signal) {
+        return this.#sendWithClaim(id, rawMessage, signal).then((result) => isOperationError(result) ? result : result.child);
+    }
+    /** The same delivery, with the work version this input was bound to. */
+    async #sendWithClaim(id, rawMessage, signal) {
         const message = stripHindsightContent(rawMessage);
         this.#bumpActivity(id);
         this.#clearSettledPanelClose(id);
@@ -965,6 +1408,9 @@ export class SubagentManager {
                 try {
                     await withDeadline(this.#start(resumedRecord), this.#deps.deadlineMs ?? 60_000);
                     isResumed = true;
+                    // A new process counts its turns from one again, so this parent adopts the boundary the
+                    // ledger already spent before it opens the next one.
+                    this.#restoreWorkVersion(id);
                 }
                 catch (error) {
                     const reason = errorMessage(error);
@@ -994,12 +1440,19 @@ export class SubagentManager {
                 }
             }
             const state = isResumed ? "running" : record.state;
-            // A resume already starts a fresh run, so the mode has nothing to decide: the message is
-            // that run's prompt. Otherwise the caller's mode is the request, with no state guessing:
-            // a running child steers at its next model step, an idle one simply starts a run.
-            const operation = isResumed ? "prompt" : mode;
+            // A resume already starts a fresh run, so the message is that run's prompt. Otherwise the
+            // input steers: a running child takes it at its next model step, an idle one starts a run.
+            const operation = isResumed ? "prompt" : "steer";
             if (signal?.aborted)
                 return failure("send", "Send was cancelled", id, state);
+            // Read before this dispatch marks the child running: only a child already inside a turn
+            // shares that turn's boundary, a fresh dispatch always opens the next one. The boundary
+            // is claimed before the request goes out, because the child may announce `agent_start`
+            // before this dispatch's own acknowledgement arrives.
+            // A resume starts a fresh run in a new process, so it never shares the boundary of the
+            // turn the dead one left behind.
+            const joining = !isResumed && this.#working.has(id) && (this.#workVersions.get(id) ?? 0) > 0;
+            const claim = isCompactCommand(message) ? undefined : this.#claimRunBoundary(id, joining);
             this.#clearSettledPanelClose(id);
             const pending = await this.#update(id, (current) => {
                 const { interrupted: _interrupted, ...clean } = current;
@@ -1011,13 +1464,16 @@ export class SubagentManager {
                 };
             });
             try {
-                const path = acknowledgedPath(await this.#request(id, operation, { message }));
+                const response = await this.#request(id, operation, { message });
+                const path = acknowledgedPath(response);
                 this.#paths.set(id, path);
+                this.#claimDispatch(id, response, claim);
             }
             catch (error) {
                 return failure("send", errorMessage(error), id, pending.state, ["input persisted as unacknowledged before dispatch"], false);
             }
-            return publicChild((await this.#deps.registry.get(id)) ?? pending, true, this.#paths.get(id));
+            const child = publicChild((await this.#deps.registry.get(id)) ?? pending, true, this.#paths.get(id));
+            return { child, action: "reuse", ...this.#claimedSubmission(id) };
         });
     }
     async get(id) {
@@ -1027,6 +1483,62 @@ export class SubagentManager {
         const live = this.#isLive(id);
         return publicChild(this.#withSnapshot(record), live, this.#paths.get(id));
     }
+    /**
+     * One delegation of one agent, by revision: the newest by default. The result body is only read
+     * when it is asked for, and then only within the shared output budget.
+     */
+    async inspect(input) {
+        const record = await this.#deps.registry.get(input.id);
+        if (record === undefined)
+            return failure("get", "Unknown child", input.id);
+        const filePath = this.#deps.registry.path;
+        const receipt = input.revision === undefined
+            ? latestReceiptForChild(filePath, this.#deps.parentSessionId, input.id)
+            : readReceiptRevision(filePath, this.#deps.parentSessionId, input.id, input.revision);
+        if (receipt === undefined) {
+            return failure("get", input.revision === undefined
+                ? "This agent has no delegation"
+                : `This agent has no delegation revision ${input.revision}`, input.id, record.state);
+        }
+        return agentView(receipt, publicChild(this.#withSnapshot(record), this.#isLive(input.id), this.#paths.get(input.id)), { includeOutput: input.includeOutput === true });
+    }
+    /** Every agent of this parent: runtime state now, latest delegation status, no result bodies. */
+    async dashboard() {
+        const records = await this.#deps.registry.list();
+        const summaries = latestReceiptSummaries(this.#deps.registry.path, this.#deps.parentSessionId);
+        const children = [];
+        for (const record of records) {
+            const summary = summaries.get(record.subagentId);
+            if (summary === undefined)
+                continue;
+            const live = this.#withSnapshot(record);
+            children.push({
+                id: record.subagentId,
+                agent: record.launchConfig.agent.name,
+                runtimeState: live.state,
+                revision: summary.revision,
+                status: summary.status,
+                hasOutput: summary.hasOutput,
+                ...(live.latestSummary === undefined ? {} : { summary: live.latestSummary }),
+            });
+        }
+        const count = (state) => children.filter((child) => child.runtimeState === state).length;
+        return {
+            total: children.length,
+            running: count("running"),
+            blocked: count("blocked"),
+            completed: count("done"),
+            failed: count("error"),
+            children,
+        };
+    }
+    /** Stops the runtime and reports the same projection every other read returns. */
+    async stopAgent(id) {
+        const stopped = await this.stop(id);
+        if (isOperationError(stopped))
+            return stopped;
+        return this.inspect({ id });
+    }
     async list() {
         const records = await this.#deps.registry.list();
         return records.map((record) => publicChild(this.#withSnapshot(record), this.#isLive(record.subagentId), this.#paths.get(record.subagentId)));
@@ -1103,6 +1615,9 @@ export class SubagentManager {
                 const finished = await this.#releaseRuntime(id, "finished");
                 if (finished !== undefined)
                     stopped = finished;
+                // Nothing can settle these any more: a waiter that was waiting on this child must end
+                // with the reason, not hang on a runtime that is gone.
+                abandonReceipts(this.#deps.registry.path, this.#deps.parentSessionId, id, "Child was stopped before the delegation finished");
                 return publicChild(stopped, false);
             }
             catch (error) {
@@ -1174,28 +1689,42 @@ export class SubagentManager {
                 throw new BridgeError("stale_report", "This report does not belong to the current runtime");
             }
             const reason = payload.reason ?? "blocked";
-            const delivered = await this.contactParent(childId, reason, payload.message, record);
+            const settles = reason === "success" || reason === "blocked";
+            // The settlement is durable before delivery is coordinated, and a waiting tool call that
+            // already owns this turn's answer suppresses the push, so it is delivered exactly once.
+            const settled = settles
+                ? this.#recordSettlement({
+                    childId,
+                    status: reason === "blocked" ? "blocked" : "completed",
+                    message: payload.message,
+                    ...(payload.controlId === undefined
+                        ? { workVersion: this.#workVersions.get(childId) ?? 0 }
+                        : { controlId: payload.controlId }),
+                })
+                : [];
+            if (settled === undefined) {
+                // The child still holds the report, so it can retry instead of losing the settlement.
+                throw new BridgeError("delivery_failed", "Settlement was not recorded");
+            }
+            const delivered = this.#claimedByWaiter(settled)
+                ? { delivered: true }
+                : await this.contactParent(childId, reason, payload.message, record);
             if ("reason" in delivered)
                 throw new BridgeError("delivery_failed", delivered.reason);
-            if (reason === "success") {
+            if (reason === "success" || reason === "blocked") {
+                const terminalState = reason === "success" ? "done" : "blocked";
                 const projector = this.#projectors.get(childId);
                 if (projector !== undefined) {
-                    projector.syncState("done");
+                    projector.syncState(terminalState);
                 }
-                await this.#update(childId, (current) => ({
-                    ...current,
-                    state: "done",
-                }));
-            }
-            else if (reason === "blocked") {
-                const projector = this.#projectors.get(childId);
-                if (projector !== undefined) {
-                    projector.syncState("blocked");
-                }
-                await this.#update(childId, (current) => ({
-                    ...current,
-                    state: "blocked",
-                }));
+                await this.#update(childId, (current) => {
+                    const { unacknowledgedInput: _input, ...clean } = current;
+                    return {
+                        ...clean,
+                        state: terminalState,
+                    };
+                });
+                this.#scheduleSettledPanelClose(childId);
             }
             else {
                 const projector = this.#projectors.get(childId);
@@ -1268,16 +1797,23 @@ export class SubagentManager {
                 const message = value.message === undefined || value.message === ""
                     ? "Task is unfinished and waiting for user intent."
                     : value.message;
-                await this.contactParent(id, "user_interrupt", message, record);
+                const settled = this.#recordSettlement({
+                    childId: id,
+                    status: "blocked",
+                    message,
+                    workVersion,
+                });
+                if (settled !== undefined && !this.#claimedByWaiter(settled)) {
+                    await this.contactParent(id, "user_interrupt", message, record);
+                }
                 return;
             }
             if (value.kind === "left_session") {
                 this.#working.delete(id);
                 // The process now serves another session, so it is no longer this child's runtime. Its
-                // credential is revoked and its runtime evidence dropped, so neither a reconnect nor a
-                // later adopt can mistake the new session for this child; the panel belongs to that other
-                // session from now on, which is why it is forgotten here and never closed.
-                const retired = record.runtime?.runtimeIdentity;
+                // runtime evidence is dropped, so neither a reconnect nor a later adopt can mistake the new
+                // session for this child; the panel belongs to that other session from now on, which is why
+                // it is forgotten here and never closed.
                 this.#clearSettledPanelClose(id);
                 this.#projectors.delete(id);
                 this.#attachments.delete(id);
@@ -1286,8 +1822,12 @@ export class SubagentManager {
                 // relaunch mistake the old connection for the new runtime.
                 this.#deps.bridge.disconnect(id);
                 await commitLease(this.#deps.registry, id, { type: "left-session" });
-                if (retired !== undefined)
-                    this.#deps.tokens?.forget(retired);
+                this.#recordSettlement({
+                    childId: id,
+                    status: "failed",
+                    message: "Child left the delegated session.",
+                    workVersion,
+                });
                 return;
             }
             // A child's own quit is a lifecycle notice, not state: the disconnect that follows says
@@ -1385,9 +1925,6 @@ export class SubagentManager {
             registry: this.#deps.registry,
             hosts: directory,
             processes: { alive: processAlive },
-            forgetRuntime: (runtimeIdentity) => {
-                this.#deps.tokens?.forget(runtimeIdentity);
-            },
         });
         const result = await lease.ready();
         if (!result.ok)