opencode-courier 0.13.8 → 0.14.0

package/dist/tree/send.js

@@ -4,17 +4,13 @@ import { syncStanding } from "./standing.js";
 import { childStore, groupStore } from "./store.js";
 import { reportBody } from "./text.js";
 import { noteSent } from "./wake.js";
-/**
- * Drops a message into another session's inbox; OpenCode wakes that session if it is idle. From a spawned session
- * to the one that started it, it is its report or its progress (`noteReport`); a group member's final report is held (`hold`).
- */
 export async function send(ports, from, input) {
     const { status, dropped } = await statusFor(ports, from, input);
-    // Noted first: the delivery may wake the parent, whose turn may end before a later note.
+    // the delivery may wake the parent, whose turn may end before a later note
     const noted = await noteReport(ports, from, input.sessionID, status).catch(() => undefined);
     try {
         const held = noted?.member && status && status !== "blocked" ? await hold(ports, noted.member, { at: noted.at, status, message: input.message, ...(input.artifacts ? { artifacts: input.artifacts } : {}) }) : undefined;
-        // The parent's standing before the delivery, which may wake it: its first step then shows the report or progress noted.
+        // an entry put now shows at the woken parent's next step (api-notes)
         if (noted)
             await syncStanding(ports, input.sessionID);
         if (held)
@@ -24,13 +20,11 @@ export async function send(ports, from, input) {
     }
     catch (error) {
         await noted?.undo().catch(() => undefined);
-        // The standing as before the note, once the note is taken back.
         if (noted)
             await syncStanding(ports, input.sessionID);
         throw error;
     }
 }
-/** Delivers the message, watches it, and takes a held report back after a blocked one; the message id and status delivered. */
 async function deliver(ports, from, input, status, noted) {
     const text = envelope(from, reportBody(input.message, input.artifacts), status ? { status } : {});
     const description = `Message from ${from}`;
@@ -41,19 +35,14 @@ async function deliver(ports, from, input, status, noted) {
         metadata: { source: "courier", from, ...(status ? { status } : {}) },
         delivery: input.queue ? "queue" : "steer",
     });
-    // Watched now, not when OpenCode's enqueued event is handled: a spawn in the same step must count the child it wakes.
+    // the enqueued event is handled apart from this call (api-notes)
     await noteSent(ports, { sessionID: input.sessionID, inboxID: delivered.id, text, description }).catch(() => undefined);
-    // A blocked report, once delivered, is the member's latest word: an earlier report held for it would be stale.
     if (noted?.member && status === "blocked")
         await unholdForBlocked(groupStore(ports.storage), noted.member).catch(() => undefined);
     return { messageID: delivered.id, ...(status ? { status } : {}) };
 }
-/**
- * The message's status, checked, as OpenCode does not check the schema. A status is a report's: on a message to a
- * session below the sender it means nothing, so it is `dropped`, and the result says so.
- */
+// tool inputs use plain schemas, so the value is checked here (api-notes)
 async function statusFor(ports, from, input) {
-    // Some models send null for an optional field they leave out.
     const given = input.status ?? undefined;
     if (given === undefined)
         return {};
@@ -61,15 +50,10 @@ async function statusFor(ports, from, input) {
         throw new Error(`status must be one of ${STATUSES.join(", ")}, not ${JSON.stringify(given)}.`);
     return (await isBelow(ports, from, input.sessionID)) ? { dropped: given } : { status: given };
 }
-/** Whether `from` started `to`, directly or through others, by the reverse index; false when the index does not name `to` or cannot be read. */
 async function isBelow(ports, from, to) {
     const above = await childStore(ports.storage).indexedAncestors(to).catch(() => []);
     return above.includes(from);
 }
-/**
- * Notes `from`'s message to `to` when `to` started it: as its report when it carries a status, or when an earlier
- * release briefed `from`, else as progress. Returns which, when, how to take the note back, and `from`'s group membership.
- */
 async function noteReport(ports, from, to, status) {
     const children = childStore(ports.storage);
     const entry = await children.indexedEntry(from);
@@ -80,7 +64,6 @@ async function noteReport(ports, from, to, status) {
     const before = await children.peek(from, field);
     const at = ports.now();
     await (report ? children.settled(from, "report", at, status) : children.progressed(from, at));
-    // Only its own note: another courier_send of the session's may have noted its report since.
     const undo = async () => {
         const now = (await children.peek(from, field));
         if (now?.at !== at || (report && now.by !== "report"))
@@ -89,10 +72,6 @@ async function noteReport(ports, from, to, status) {
     };
     return { report, at, undo, member: status !== undefined ? await memberIn(ports, entry) : undefined };
 }
-/**
- * A child's membership of an open group of its parent's, by its roster entry; none once courier_cleanup dropped it. One that
- * cannot be read is dropped from the group, best effort, as the report then goes on its own and the group must not wait for it.
- */
 async function memberIn(ports, entry) {
     const groups = groupStore(ports.storage);
     try {
@@ -106,24 +85,18 @@ async function memberIn(ports, entry) {
         return undefined;
     }
 }
-/**
- * Holds a member's report with its group, and nudges the scheduler if that completes the group. Undefined
- * when it could not be held: the member is dropped from the group, which releases without it, and reports on its own.
- */
 async function hold(ports, member, report) {
     const groups = groupStore(ports.storage);
     try {
         await holdReport(groups, member, report);
     }
     catch (error) {
-        // Neither held nor dropped, the group would wait for ever: the call fails, and the sender sends it again.
         await groups.remove(member.parentID, member.group, member.sessionID).catch((dropError) => {
             throw new Error(`the report could not be held with group ${member.group} (${String(error)}), nor the member dropped from it (${String(dropError)}); send it again.`);
         });
         ports.nudge();
         return undefined;
     }
-    // Held whatever the count gives; a count that cannot be read gets the nudge, as a tick that finds nothing due is cheap.
     const standing = await groupStanding(groups, member.parentID, member.group).catch(() => undefined);
     if (standing?.complete !== false)
         ports.nudge();

package/dist/tree/spawn.d.ts

@@ -5,17 +5,10 @@ export interface SpawnInput {
     readonly agent?: string;
     readonly isolate?: boolean;
     readonly group?: string;
-    /** `provider/model` to run on; left out, the agent's own model, else the caller's. */
     readonly model?: string;
-    /** The variant of that model, its reasoning effort; left out, the chosen model's own. */
     readonly variant?: string;
-    /** Whether the child is OpenCode's subagent of the caller; left out, the `nativeChildren` option decides. */
     readonly native?: boolean;
 }
-/**
- * Creates a child session, hands it the task and returns at once; the child reports back with
- * courier_send. Refused past a limit, whether or not the `context` hook hid the tool.
- */
 export declare function spawn(ports: CourierPorts, parentID: string, input: SpawnInput): Promise<{
     native?: boolean | undefined;
     model?: string | undefined;

package/dist/tree/spawn.js

@@ -6,30 +6,19 @@ import { chooseModel } from "./model.js";
 import { putEntries, syncStanding } from "./standing.js";
 import { childStore, groupStore } from "./store.js";
 import { childBrief, childBranch, nativeIsolateRefusal, ROLE_KEY, rolePart } from "./text.js";
-/**
- * A spawned session's own rules: OpenCode's schedule tools are hidden, as their wake-ups go round the tree, so a child
- * that schedules one and ends its turn would read as silent. A native child would otherwise run on its parent's rules.
- */
+// a schedule's wake-up is invisible to Waits (api-notes, OpenCode's schedules)
 const CHILD_RULES = [{ action: "opencode_schedule_*", resource: "*", effect: "deny" }];
 function titleOf(task) {
     const line = task.trim().split("\n")[0] ?? "";
     return line.length > 60 ? `${line.slice(0, 57)}...` : line;
 }
-/** Removes a worktree made for a child that was never created; one that cannot be removed stays. */
 async function dropWorktree(ports, directory) {
     try {
         await ports.worktree.remove({ projectID: ports.projectID, directory, force: false });
     }
-    catch {
-        // The spawn's own failure is the one to report.
-    }
+    catch { }
 }
-/**
- * Creates a child session, hands it the task and returns at once; the child reports back with
- * courier_send. Refused past a limit, whether or not the `context` hook hid the tool.
- */
 export async function spawn(ports, parentID, input) {
-    // Some models send null, or an empty string, for an optional field they leave out.
     const group = typeof input.group === "string" ? input.group.trim() || undefined : (input.group ?? undefined);
     if (group !== undefined && !isGroupName(group))
         throw new Error(`group must be a name of 1 to 60 letters, digits, dots, dashes or underscores, not ${JSON.stringify(group)}.`);
@@ -63,7 +52,6 @@ async function start(ports, parentID, input, admitted, group) {
         await handOver(ports, entry, admitted.depth, input.task, !rosterError, !rosterError && !groupError);
     }
     finally {
-        // The parent's standing with the child on it, prompted or failed, announced at its next step.
         await syncStanding(ports, parentID);
     }
     return {
@@ -78,10 +66,6 @@ async function start(ports, parentID, input, admitted, group) {
         ...(entry.native ? { native: true } : {}),
     };
 }
-/**
- * Creates the child's session, in a worktree of its own if asked, which goes again if the session cannot be created.
- * `model` names the child's model when it is not its parent's, for the roster and the result.
- */
 async function create(ports, parentID, input) {
     const { model, parent } = await chooseModel(ports, parentID, input, input.agent);
     const handedDown = input.isolate ? await parentWork(ports, parentID) : undefined;
@@ -90,7 +74,7 @@ async function create(ports, parentID, input) {
         : undefined;
     const base = worktree ? await ports.head(worktree) : undefined;
     const title = input.title ?? titleOf(input.task);
-    // OpenCode takes a location or a parentID, never both, so an isolated child cannot be a native one.
+    // OpenCode takes a location or a parentID, never both
     const native = (input.native ?? ports.nativeChildren === true) && !worktree;
     const child = await ports.session
         .create({
@@ -103,7 +87,6 @@ async function create(ports, parentID, input) {
         metadata: { courier: { parentID } },
     })
         .catch(async (error) => {
-        // No session will ever use the fresh worktree, and nothing records it, so it goes now.
         if (worktree)
             await dropWorktree(ports, worktree);
         throw error;
@@ -119,10 +102,6 @@ async function create(ports, parentID, input) {
         ...(model && (!parent || modelName(model) !== modelName(parent)) ? { model: modelName(model) } : {}),
     };
 }
-/**
- * The worktree and HEAD an isolated parent hands its isolated child, by the reverse index alone; undefined for any
- * other parent. An unreadable HEAD fails the spawn rather than start the child without the parent's work.
- */
 async function parentWork(ports, parentID) {
     const parent = await childStore(ports.storage).indexedEntry(parentID);
     if (!parent?.isolated)
@@ -133,21 +112,13 @@ async function parentWork(ports, parentID) {
     const uncommitted = (await ports.dirty(parent.directory).catch(() => undefined)) === true;
     return { directory: parent.directory, head, uncommitted };
 }
-/**
- * Records the child on the roster, before the prompt, so a child that exists is on the roster even if prompting
- * fails, then in its group. A failed write must not keep the child from its task: each is reported, not thrown.
- */
 async function enrol(ports, entry, group) {
     const rosterError = await childStore(ports.storage).record(entry).then(() => undefined, (error) => describeFailure("roster", error).message);
     const groupError = group && !rosterError ? await join(ports, entry, group) : undefined;
     return { rosterError, groupError };
 }
-/**
- * Hands the child its task. `rostered` says whether its report state is kept, which a child off the roster has none
- * of, and `grouped` whether it is in its group; a child that never got its task leaves both, as it will never report.
- */
 async function handOver(ports, entry, depth, task, rostered, grouped) {
-    // A baseline, until OpenCode's event for the prompt's delivery moves it on; written first, so it never overtakes that.
+    // the prompt's inbox.delivered event moves this on; so written first
     const children = childStore(ports.storage);
     if (rostered)
         await children.prompted(entry.sessionID, ports.now()).catch(() => undefined);
@@ -162,10 +133,6 @@ async function handOver(ports, entry, depth, task, rostered, grouped) {
         throw error;
     }
 }
-/**
- * Joins a child to its group; one that cannot be joined is recorded in no group, so it reports on its own,
- * and the result says so. Returns the error's message, if any.
- */
 async function join(ports, entry, group) {
     const groups = groupStore(ports.storage);
     try {
@@ -174,7 +141,6 @@ async function join(ports, entry, group) {
     }
     catch (error) {
         const { group: _, ...ungrouped } = entry;
-        // A write that failed may have landed all the same: a member left there would hold its group up for good.
         await Promise.all([
             childStore(ports.storage).record(ungrouped).catch(() => undefined),
             groups.remove(entry.parentID, group, entry.sessionID).catch(() => undefined),
@@ -182,10 +148,7 @@ async function join(ports, entry, group) {
         return describeFailure("group", error).message;
     }
 }
-/**
- * The child's role and the other modules' entries before its prompt, so its first request carries them, and a root's own at
- * its first spawn, remembered for the `context` hook; a parent that is no root is forgotten there, as its depth may have changed.
- */
+// entries put before the first step are in its baseline (api-notes)
 async function nameBoth(ports, parentID, childID, depth) {
     const extra = await extraEntries(ports);
     await nameRole(ports, childID, depth);
@@ -200,7 +163,6 @@ async function nameBoth(ports, parentID, childID, depth) {
     else
         ports.roles.delete(parentID);
 }
-/** The entries the other modules give a spawned session, the memory's lessons; none when they cannot be read, logged. */
 async function extraEntries(ports) {
     if (!ports.entries || !ports.session.instructions)
         return [];
@@ -212,10 +174,7 @@ async function extraEntries(ports) {
         return [];
     }
 }
-/**
- * Writes a session's role part to its `role` entry: a child's system prompt carries it from its first request, a root's
- * transcript as an update. False on a host without entries, or when the put failed, logged: the `context` hook adds the part.
- */
+// a host before 2.2.0 has no entries; the context hook adds the part
 async function nameRole(ports, sessionID, depth) {
     const entries = ports.session.instructions?.entry;
     if (!entries)

package/dist/tree/standing.d.ts

@@ -1,17 +1,9 @@
 import type { Entry, ReportNote, RosterStorage, StandingPorts } from "./ports.js";
 import { type ChildState, type StandingRow } from "./text.js";
-/** A child's state from its report notes, as `reportOf` and the silent-turn rule read them. */
 export declare function stateOf(notes: {
     readonly [K in "prompt" | "settled" | "progress" | "told" | "stopped"]: ReportNote;
 }): ChildState;
-/** The rows of a parent's standing entry: its unexpired children, oldest first, each with its state and group standing. */
 export declare function standingRows(storage: RosterStorage, parentID: string, now: number): Promise<StandingRow[]>;
-/** What `syncStanding` did to the parent's entry. */
 export type Synced = "put" | "unchanged" | "removed" | "absent" | "skipped";
-/**
- * Writes a parent's `standing` entry once something of it changed: put when its text differs from the entry's, removed when
- * the parent has no children left; skipped without the keyed entries. A failure is logged, never thrown.
- */
 export declare function syncStanding(ports: StandingPorts, parentID: string): Promise<Synced>;
-/** Writes `given` entries to a session, each put logged on failure and never thrown: the session gets its task all the same. */
 export declare function putEntries(ports: StandingPorts, sessionID: string, given: ReadonlyArray<Entry>): Promise<void>;

package/dist/tree/standing.js

@@ -4,9 +4,7 @@ import { isNotFound } from "../platform/json.js";
 import { isExpired, standingOf } from "./domain.js";
 import { childStore, groupStore } from "./store.js";
 import { STANDING_KEY, standingEntry } from "./text.js";
-/** Whether `at` is known and no earlier than the prompt at `prompt`. */
 const since = (at, prompt) => at !== undefined && at >= prompt;
-/** A child's state from its report notes, as `reportOf` and the silent-turn rule read them. */
 export function stateOf(notes) {
     const prompt = notes.prompt.at;
     if (notes.stopped.at !== undefined && (prompt === undefined || notes.stopped.at >= prompt))
@@ -21,10 +19,8 @@ export function stateOf(notes) {
         return { kind: by };
     return { kind: "reported", status: isStatus(status) ? status : "done", ...progressed };
 }
-/** The rows of a parent's standing entry: its unexpired children, oldest first, each with its state and group standing. */
 export async function standingRows(storage, parentID, now) {
     const children = childStore(storage);
-    // The groups read best effort, as courier_children reads them: a member's standing is `unknown` when they cannot be.
     const [entries, members] = await Promise.all([children.children(parentID), groupStore(storage).ofParent(parentID).catch(() => undefined)]);
     const current = entries.filter((entry) => !isExpired(entry, now, existsSync));
     return Promise.all(current.map(async (entry) => {
@@ -39,12 +35,7 @@ export async function standingRows(storage, parentID, now) {
         };
     }));
 }
-/** The syncs under way in this process, by parent, each run after the one before it: a sync that read earlier never writes last. */
 const inTurn = new Map();
-/**
- * Writes a parent's `standing` entry once something of it changed: put when its text differs from the entry's, removed when
- * the parent has no children left; skipped without the keyed entries. A failure is logged, never thrown.
- */
 export function syncStanding(ports, parentID) {
     const entries = ports.session?.instructions?.entry;
     if (!entries)
@@ -75,13 +66,12 @@ async function sync(ports, parentID, entries) {
         return "put";
     }
     catch (error) {
-        // A parent OpenCode no longer knows has no entry to keep: a child deleted after it is a normal path.
+        // a put on a session OpenCode deleted fails NotFound (api-notes)
         if (!isNotFound(error))
             ports.log?.(`courier: the standing entry of ${parentID} could not be written, so it may be behind courier_children: ${String(error)}`);
         return "skipped";
     }
 }
-/** Writes `given` entries to a session, each put logged on failure and never thrown: the session gets its task all the same. */
 export async function putEntries(ports, sessionID, given) {
     const entries = ports.session?.instructions?.entry;
     if (!entries)

package/dist/tree/status.d.ts

@@ -7,7 +7,6 @@ export interface StatusInput {
 export interface ChildrenInput {
     readonly sessionID?: string;
 }
-/** One session's state and last reply, as courier_children shows each child. */
 export declare function status(ports: CourierPorts, input: StatusInput): Promise<Partial<{
     sessionID: string;
     title: string | undefined;
@@ -19,12 +18,7 @@ export declare function status(ports: CourierPorts, input: StatusInput): Promise
     lastText: string | undefined;
     pending: readonly import("./ports.js").Pending[] | undefined;
 }>>;
-/** The text of a session's last reply, from its context's messages, or undefined when it has none. */
 export declare function lastReply(messages: Awaited<ReturnType<Context["session"]["context"]>>): string | undefined;
-/**
- * The sessions a parent started, each with its state and last reply, or the error it gave; a child in a
- * group with the group's name and its standing there: `held`, `out`, how it left, `released` or `unknown`.
- */
 export declare function listChildren(ports: CourierPorts, parentID: string): Promise<({
     group: {
         name: string;
@@ -84,7 +78,6 @@ export declare function listChildren(ports: CourierPorts, parentID: string): Pro
     sessionID: string;
     title: string;
 })[]>;
-/** One roster entry as courier_children shows it: the session's state with its directory and group standing, or the error it gave. */
 export declare function described(ports: CourierPorts, entry: RosterEntry): Promise<{
     group: {
         name: string;
@@ -144,6 +137,5 @@ export declare function described(ports: CourierPorts, entry: RosterEntry): Prom
     sessionID: string;
     title: string;
 }>;
-/** A child's standing in the join group its roster entry names, `unknown` when that cannot be read. */
 export declare function standingIn(ports: Pick<CourierPorts, "storage">, entry: RosterEntry, group: string): Promise<"failed" | "interrupted" | "out" | "unknown" | "deleted" | "dropped" | "held" | "released">;
 export {};

package/dist/tree/status.js

@@ -2,7 +2,6 @@ import { describeFailure } from "../kernel/protocol.js";
 import { standingOf, startedAs } from "./domain.js";
 import { current } from "./roster.js";
 import { groupStore } from "./store.js";
-/** One session's state and last reply, as courier_children shows each child. */
 export async function status(ports, input) {
     const [info, messages, pending] = await Promise.all([
         ports.session.get({ sessionID: input.sessionID }),
@@ -22,22 +21,16 @@ export async function status(ports, input) {
         pending: pending.length ? pending : undefined,
     });
 }
-/** The text of a session's last reply, from its context's messages, or undefined when it has none. */
 export function lastReply(messages) {
     const last = messages.findLast((message) => message.type === "assistant");
     return last?.type === "assistant"
         ? last.content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("")
         : undefined;
 }
-/**
- * The sessions a parent started, each with its state and last reply, or the error it gave; a child in a
- * group with the group's name and its standing there: `held`, `out`, how it left, `released` or `unknown`.
- */
 export async function listChildren(ports, parentID) {
     const entries = await current(ports.storage, parentID, ports.now());
     return Promise.all(entries.map((entry) => described(ports, entry)));
 }
-/** One roster entry as courier_children shows it: the session's state with its directory and group standing, or the error it gave. */
 export async function described(ports, entry) {
     const group = entry.group ? { group: { name: entry.group, report: await standingIn(ports, entry, entry.group) } } : {};
     const roster = { directory: entry.directory, ...startedAs(entry), created: entry.createdAt, ...group };
@@ -53,11 +46,10 @@ export async function described(ports, entry) {
         };
     }
 }
-/** A child's standing in the join group its roster entry names, `unknown` when that cannot be read. */
 export function standingIn(ports, entry, group) {
     return groupStore(ports.storage).member(entry.parentID, group, entry.sessionID).then(standingOf, () => "unknown");
 }
-/** OpenCode leaves a tool call hanging when its metadata holds `undefined`, so results drop those keys. */
+// metadata with an undefined value never completes the call (api-notes)
 function withoutUndefined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
 }

package/dist/tree/stop.d.ts

@@ -3,31 +3,24 @@ export interface StopInput {
     readonly sessionID: string;
     readonly cleanup?: boolean;
 }
-/** What happened to one session: its turn was interrupted, it was not running, OpenCode no longer knows it, or the interrupt failed. */
 export interface Stopped {
     readonly sessionID: string;
     readonly title: string;
     readonly depth: number;
     readonly outcome: "interrupted" | "idle" | "gone" | "failed";
     readonly error?: string;
+    readonly subagent?: true;
 }
 export interface StopResult {
     readonly sessionID: string;
-    /** Every session stopped, deepest first; the target is the last. */
     readonly stopped: ReadonlyArray<Stopped>;
-    /** The ids of the courier_later messages cancelled. */
     readonly cancelled: ReadonlyArray<string>;
-    /** With `cleanup`: what became of each isolated session's worktree, deepest first. */
     readonly cleanup?: ReadonlyArray<CleanupResult | {
         readonly sessionID: string;
         readonly outcome: "failed";
         readonly error: string;
     }>;
-    /** The session told that the target was stopped, when that is not the caller. */
     readonly told?: string;
 }
-/**
- * Stops a session and everything under it, deepest first, and cancels the messages scheduled for them; only a session above the target may.
- * The caller is not told; the target's parent is, unless that is the caller.
- */
+export declare const SETTLE_MS = 2000;
 export declare function stop(ports: StopPorts, callerID: string, input: StopInput): Promise<StopResult>;

package/dist/tree/stop.js

@@ -6,15 +6,12 @@ import { childStore } from "./store.js";
 import { subtree } from "./subtree.js";
 import { stoppedNotice } from "./text.js";
 import { forgetWakes } from "./wake.js";
-/** Rounds of looking again for sessions started while others were being stopped. */
 const ROUNDS = 3;
-/**
- * Stops a session and everything under it, deepest first, and cancels the messages scheduled for them; only a session above the target may.
- * The caller is not told; the target's parent is, unless that is the caller.
- */
+export const SETTLE_MS = 2_000;
 export async function stop(ports, callerID, input) {
-    const { storage } = ports.courier;
+    const { storage, session } = ports.courier;
     const { sessionID } = input;
+    const startedAt = Date.now();
     const chain = await childStore(storage).lineage(sessionID);
     if (!chain.length)
         throw new Error(`${sessionID} was not started with courier_spawn, so courier_stop cannot stop it.`);
@@ -31,15 +28,17 @@ export async function stop(ports, callerID, input) {
         for (const node of pending)
             seen.add(node.entry.sessionID);
         nodes.push(...pending);
-        // Before any interrupt, so nothing scheduled wakes a session that was just stopped.
-        await Promise.all(pending.map((node) => silence(ports, node.entry.sessionID, cancelled)));
+        await Promise.all(pending.map((node) => silence(ports, node, cancelled)));
         results.push(...(await eachDeepestFirst(pending, (node) => interrupt(ports, node))));
-        const meanwhile = (await subtree(storage, sessionID)).nodes.filter((node) => !seen.has(node.entry.sessionID));
+        const meanwhile = (await subtree(storage, sessionID, undefined, session)).nodes.filter((node) => !seen.has(node.entry.sessionID));
         return round(meanwhile, left - 1);
     };
-    await round([{ entry: target, depth: 0 }, ...(await subtree(storage, sessionID)).nodes], ROUNDS);
-    // Each parent among them reads its stopped children at its next step; the caller's own entry, when it is the target's parent, too.
-    await Promise.all([...new Set(nodes.map((node) => node.entry.parentID))].map((parentID) => syncStanding(ports.courier, parentID)));
+    const first = (await subtree(storage, sessionID, undefined, session)).nodes;
+    const background = await backgroundSubagents(ports, first);
+    await round([{ entry: target, depth: 0 }, ...first], ROUNDS);
+    await settle(ports, nodes, results, background, startedAt);
+    const parents = new Set(nodes.flatMap((node) => (node.subagent ? [] : [node.entry.parentID])));
+    await Promise.all([...parents].map((parentID) => syncStanding(ports.courier, parentID)));
     const told = target.parentID !== callerID && results.find((one) => one.sessionID === sessionID)?.outcome === "interrupted"
         ? await tell(ports, callerID, target)
         : undefined;
@@ -51,15 +50,15 @@ export async function stop(ports, callerID, input) {
         ...(told ? { told } : {}),
     };
 }
-/** Runs `act` on the nodes level by level, the deepest level first and the level's nodes at once; the results in that order. */
 function eachDeepestFirst(nodes, act) {
     const depths = [...new Set(nodes.map((node) => node.depth))].sort((a, b) => b - a);
     return depths.reduce((before, depth) => before.then(async (done) => [...done, ...(await Promise.all(nodes.filter((node) => node.depth === depth).map(act)))]), Promise.resolve([]));
 }
-/** Notes that a session was stopped, so the failure and silent-end notices stay quiet for it, and cancels its pending messages. */
-async function silence(ports, sessionID, cancelled) {
+async function silence(ports, { entry, subagent }, cancelled) {
     const { storage, now, log } = ports.courier;
-    await childStore(storage).stopped(sessionID, now()).catch((error) => log(`courier_stop: could not note that ${sessionID} was stopped: ${String(error)}`));
+    const { sessionID } = entry;
+    if (!subagent)
+        await childStore(storage).stopped(sessionID, now()).catch((error) => log(`courier_stop: could not note that ${sessionID} was stopped: ${String(error)}`));
     try {
         cancelled.push(...(await ports.cancelScheduled(sessionID)));
     }
@@ -68,23 +67,59 @@ async function silence(ports, sessionID, cancelled) {
     }
     await forgetWakes(ports.courier, sessionID).catch((error) => log(`courier_stop: could not drop the wake watch of ${sessionID}: ${String(error)}`));
 }
-async function interrupt(ports, { entry, depth }) {
+async function interrupt(ports, { entry, depth, subagent }) {
     const { sessionID, title } = entry;
     const { storage, session, now } = ports.courier;
+    const one = { sessionID, title, depth, ...(subagent ? { subagent } : {}) };
     try {
         const { interrupted } = await session.interrupt({ sessionID });
-        // The event for it says so too; noted here as well, so the end is settled when this returns.
-        if (interrupted)
+        // the interrupted event may arrive after this returns
+        if (interrupted && !subagent)
             await childStore(storage).settled(sessionID, "interrupted", now()).catch(() => undefined);
-        return { sessionID, title, depth, outcome: interrupted ? "interrupted" : "idle" };
+        return { ...one, outcome: interrupted ? "interrupted" : "idle" };
     }
     catch (error) {
         if (isNotFound(error))
-            return { sessionID, title, depth, outcome: "gone" };
-        return { sessionID, title, depth, outcome: "failed", error: describeFailure("session.interrupt", error).message };
+            return { ...one, outcome: "gone" };
+        return { ...one, outcome: "failed", error: describeFailure("session.interrupt", error).message };
     }
 }
-/** Tells the target's parent, which is below the caller, that it was stopped; undefined when that could not be done. */
+// a completed background subagent call names its child (api-notes)
+async function backgroundSubagents(ports, nodes) {
+    const parents = [...new Set(nodes.flatMap((node) => (node.subagent ? [node.entry.parentID] : [])))];
+    const found = await Promise.all(parents.map(async (parentID) => {
+        const messages = await ports.courier.session.context({ sessionID: parentID }).catch(() => []);
+        const returned = messages.flatMap((message) => message.type === "assistant" ? message.content.flatMap((part) => (part.type === "tool" && part.name === "subagent" && part.state.status === "completed" ? [part] : [])) : []);
+        const named = (id) => returned.some((part) => part.state.status === "completed" && JSON.stringify([part.state.content, part.state.metadata ?? null]).includes(id));
+        const ids = nodes.filter((node) => node.subagent && node.entry.parentID === parentID && named(node.entry.sessionID)).map((node) => node.entry.sessionID);
+        return [parentID, new Set(ids)];
+    }));
+    return new Map(found.filter(([, ids]) => ids.size));
+}
+// a background subagent's end wakes its parent (api-notes)
+async function settle(ports, nodes, results, background, since) {
+    const ended = new Set(results.flatMap((one) => (one.subagent && one.outcome === "interrupted" ? [one.sessionID] : [])));
+    await Promise.all([...background].map(async ([parentID, ids]) => {
+        const waited = new Set([...ids].filter((id) => ended.has(id)));
+        if (!waited.size || !(await told(ports, parentID, waited, since)))
+            return;
+        const parent = nodes.find((node) => node.entry.sessionID === parentID);
+        if (parent && !parent.subagent)
+            await childStore(ports.courier.storage).stopped(parentID, ports.courier.now()).catch(() => undefined);
+        if (parent)
+            await interrupt(ports, parent);
+    }));
+}
+async function told(ports, parentID, ids, since) {
+    const messages = await ports.courier.session.context({ sessionID: parentID }).catch(() => []);
+    const noticed = new Set(messages.flatMap((message) => (message.type === "synthetic" && message.time.created >= since && typeof message.metadata?.childID === "string" ? [message.metadata.childID] : [])));
+    if ([...ids].every((id) => noticed.has(id)))
+        return true;
+    if (Date.now() - since >= SETTLE_MS)
+        return false;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    return told(ports, parentID, ids, since);
+}
 async function tell(ports, callerID, target) {
     const { session, log } = ports.courier;
     try {
@@ -102,9 +137,7 @@ async function tell(ports, callerID, target) {
         return undefined;
     }
 }
-/** Removes the isolated sessions' worktrees, deepest first, through courier_cleanup's checks; a failure is reported, not thrown. */
 async function removeWorktrees(ports, nodes) {
-    // One at a time: git locks the repository's worktree list while it removes one.
     const removeNext = async (queue, done) => {
         const [next, ...rest] = queue;
         if (!next)

package/dist/tree/store.d.ts

@@ -1,9 +1,5 @@
 import { type Storage } from "../platform/storage.js";
 import type { ChildStore, GroupStore, WakeStore } from "./ports.js";
-/**
- * What the reverse index holds for a child: the sessions above it, its parent first and the top
- * session, which courier_spawn did not start, last; each is the parent of the one before it.
- */
 export interface ReverseEntry {
     readonly ancestors: ReadonlyArray<string>;
 }
@@ -16,13 +12,9 @@ export declare const toldKey: (sessionID: string) => string;
 export declare const stoppedKey: (sessionID: string) => string;
 export declare const nudgedKey: (sessionID: string) => string;
 export declare const memberKey: (parentID: string, group: string, sessionID: string) => string;
-/** The key prefix of a parent's groups, and of one group's members. */
 export declare const groupsPrefix: (parentID: string) => string;
 export declare const groupPrefix: (parentID: string, group: string) => string;
 export declare const wakeKey: (sessionID: string, inboxID: string) => string;
-/** The `ChildStore` over the plugin's storage. */
 export declare function childStore(storage: Storage): ChildStore;
-/** The `GroupStore` over the plugin's storage. */
 export declare function groupStore(storage: Storage): GroupStore;
-/** The `WakeStore` over the plugin's storage. */
 export declare function wakeStore(storage: Storage): WakeStore;