opencode-courier 0.3.0 → 0.4.0

package/dist/{cleanup.js → tree/cleanup.js}

@@ -1,9 +1,9 @@
 import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { isAbsolute } from "node:path";
-import { markLeft, membershipOf } from "./group.js";
-import { keepReason } from "./notices.js";
-import { remove, rosterKey } from "./roster.js";
+import { forgetDropped } from "./forget.js";
+import { childStore } from "./store.js";
+import { keepReason } from "./text.js";
 /** At most this many changes and commits are returned; the reason still counts them all. */
 export const MAX_LISTED = 50;
 /**
@@ -11,11 +11,15 @@ export const MAX_LISTED = 50;
  * or commits found nowhere else is kept unless `force` is set; the result says so.
  */
 export async function cleanup(ports, parentID, input) {
-    const entry = (await ports.storage.get(rosterKey(parentID, input.sessionID)));
+    const entry = await childStore(ports.storage).entry(parentID, input.sessionID);
     if (!entry)
         throw new Error(`${input.sessionID} is not on the courier_children list of ${parentID}.`);
     const { directory } = entry;
-    const forget = () => forgetChild(ports, entry);
+    // A member still out is dropped from its group, so the group is released without it; the result names that group.
+    const forget = async () => {
+        const group = await forgetDropped(ports, entry);
+        return group ? { group } : {};
+    };
     if (!entry.isolated)
         return { sessionID: input.sessionID, directory, outcome: "forgotten", ...(await forget()) };
     // With force the state only decides whether there is anything left to remove, so a worktree git
@@ -42,17 +46,6 @@ export async function cleanup(ports, parentID, input) {
     });
     return { sessionID: input.sessionID, directory, outcome: "removed", ...(await forget()) };
 }
-/**
- * Drops a member still out from its group as `dropped`, so the group is released without it, then the roster entry
- * and report state. A held report stays with its group. Returns the group it was dropped from.
- */
-async function forgetChild(ports, entry) {
-    const member = entry.group ? await membershipOf(ports.storage, entry.parentID, entry.group, entry.sessionID) : undefined;
-    if (member?.out && (await markLeft(ports.storage, member, "dropped", ports.now())))
-        ports.nudge();
-    await remove(ports.storage, entry.parentID, entry.sessionID);
-    return member?.out ? { group: member.group } : {};
-}
 /** Names the git to run, by absolute path, overriding the places `GIT_LOCATIONS` lists. */
 export const GIT_ENV = "OPENCODE_COURIER_GIT";
 /**

package/dist/tree/context.d.ts

@@ -0,0 +1,15 @@
+import type { ContextPorts } from "./ports.js";
+/** The part of a session context this hook changes. */
+export interface Shaped {
+    readonly sessionID: string;
+    tools: Record<string, unknown>;
+    system: Array<{
+        type: "text";
+        text: string;
+    }>;
+}
+/**
+ * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn
+ * from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ */
+export declare function shapeContext(ports: ContextPorts, event: Shaped): Promise<void>;

package/dist/tree/context.js

@@ -0,0 +1,34 @@
+import { setBounded } from "../platform/bounded.js";
+import { childStore } from "./store.js";
+import { ROLE_PREFIX, rolePart } from "./text.js";
+/** How many sessions' depths an instance remembers. */
+const ROLES_MAX = 1000;
+/**
+ * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn
+ * from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ */
+export async function shapeContext(ports, event) {
+    try {
+        const depth = await depthOf(ports, event.sessionID);
+        if (depth === null && !event.tools.courier_spawn)
+            return;
+        if (depth !== null && depth >= ports.limits.maxDepth)
+            delete event.tools.courier_spawn;
+        if (!event.system.some((part) => part.text.startsWith(ROLE_PREFIX)))
+            event.system.push({ type: "text", text: rolePart(depth, ports.limits) });
+    }
+    catch (error) {
+        ports.log(`courier: cannot tell the role of session ${event.sessionID}: ${String(error)}`);
+    }
+}
+async function depthOf(ports, sessionID) {
+    const known = ports.roles.get(sessionID);
+    if (known !== undefined)
+        return known;
+    // The reverse index alone: a scan here would run for every session's first request, courier or not.
+    const children = childStore(ports.storage);
+    const chain = await children.indexedLineage(sessionID);
+    const depth = chain.length || ((await children.children(sessionID)).length ? 0 : null);
+    setBounded(ports.roles, sessionID, depth, ROLES_MAX);
+    return depth;
+}

package/dist/tree/domain.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The tree's pure rules, on plain data: the limits, a session's lineage, whether it runs, and a group
+ * member's standing. Imports nothing of the plugin's but `kernel/` and `platform/json.ts`.
+ */
+import type { Plugin } from "@opencode/plugin";
+import type { Status } from "../kernel/protocol.js";
+type Context = Plugin.Context;
+/** The limits on the tree of sessions courier_spawn builds, from the plugin's options. */
+export interface Limits {
+    readonly maxDepth: number;
+    readonly maxChildren: number;
+    readonly maxTotal: number;
+}
+export declare const DEFAULT_LIMITS: Limits;
+/** The limits in the plugin's options; one that is not a positive integer keeps its default and is named in `problems`. */
+export declare function readLimits(options: unknown): {
+    limits: Limits;
+    problems: string[];
+};
+/** The `nativeChildren` option: whether a child started without isolate gets OpenCode's own `parentID`; off unless `true`. */
+export declare function readNativeChildren(options: unknown): {
+    nativeChildren: boolean;
+    problems: string[];
+};
+/** A session's times, as `session.get` gives them. */
+type Times = Awaited<ReturnType<Context["session"]["get"]>>["time"];
+/** Whether a session with these times runs: it has never finished a turn, or something reached it after the last one ended. */
+export declare const busy: (time: Pick<Times, "updated" | "idle">) => boolean;
+/** A session started with courier_spawn, recorded under the session that started it. */
+export interface RosterEntry {
+    readonly sessionID: string;
+    readonly parentID: string;
+    readonly title: string;
+    readonly directory: string;
+    readonly isolated: boolean;
+    readonly createdAt: number;
+    /** For an isolated child, the directory its worktree was made from; for the record, nothing acts on it. */
+    readonly source?: string;
+    /** For an isolated child, the project its worktree belongs to; courier_cleanup removes it from there. */
+    readonly project?: string;
+    /** For an isolated child, the commit its worktree was made from; its own work is what came after. */
+    readonly base?: string;
+    /** `"status"` when its brief asked for a report with a status; absent for a child an earlier release briefed. */
+    readonly reports?: "status";
+    /** The join group courier_spawn put it in, whose release holds its report; absent for a child in none. */
+    readonly group?: string;
+    /** Created with OpenCode's own `parentID` (the `nativeChildren` option), so OpenCode shows its asks in its parent's view. */
+    readonly native?: true;
+}
+/** `lineage` over roster entries already read. */
+export declare function lineageIn(entries: ReadonlyArray<RosterEntry>, sessionID: string): RosterEntry[];
+/** Roster entries by their session, for `lineageBy`. */
+export declare function bySession(entries: ReadonlyArray<RosterEntry>): Map<string, RosterEntry>;
+/** `lineage` over roster entries already read and mapped by `bySession`. */
+export declare function lineageBy(bySession: ReadonlyMap<string, RosterEntry>, sessionID: string): RosterEntry[];
+/**
+ * The session whose view OpenCode shows the asks of a lineage's first session in: up its native parents, to the
+ * first session that is not a native child (an isolated one, or the top). The session itself when it is not native.
+ */
+export declare function nativeRootOf(chain: ReadonlyArray<RosterEntry>): string;
+/** What a report lists besides its text; `checks` are the commands the session ran and what each gave. */
+export interface Artifacts {
+    readonly branch?: string;
+    readonly commits?: ReadonlyArray<string>;
+    readonly files?: ReadonlyArray<string>;
+    readonly checks?: ReadonlyArray<{
+        readonly command: string;
+        readonly result: string;
+    }>;
+}
+/** A report held with its group: its status, text and artifacts, as courier_send was given them, and when. */
+export interface HeldReport {
+    readonly at: number;
+    readonly status: Status;
+    readonly message: string;
+    readonly artifacts?: Artifacts;
+}
+/** A member of a group that left it without a report, and why: its turn failed or was interrupted, it was deleted, or courier_cleanup dropped it. */
+export interface LeftMember {
+    readonly sessionID: string;
+    readonly title: string;
+    readonly by: "failed" | "interrupted" | "deleted" | "dropped";
+}
+export declare const isGroupName: (value: unknown) => value is string;
+/** A member of a group, as stored: its title for the release notice, and its report or how it left. */
+export interface Member {
+    readonly title: string;
+    readonly joinedAt: number;
+    readonly report?: HeldReport;
+    readonly left?: {
+        readonly at: number;
+        readonly by: LeftMember["by"];
+    };
+}
+/** What is known of a member's standing: its report is held, still out, or it left, or it is no longer in an open group. */
+export type Standing = "held" | "out" | LeftMember["by"] | "released";
+/** A member's standing from its stored value, or `released` when there is none. */
+export declare function standingOf(member: Member | undefined): Standing;
+/** Whether every member of a group has a held report or has left: released once the parent's turn has ended. */
+export declare const complete: (members: ReadonlyArray<Member>) => boolean;
+export {};

package/dist/tree/domain.js

@@ -0,0 +1,68 @@
+import { millis, obj } from "../platform/json.js";
+export const DEFAULT_LIMITS = { maxDepth: 3, maxChildren: 5, maxTotal: 20 };
+/** The limits in the plugin's options; one that is not a positive integer keeps its default and is named in `problems`. */
+export function readLimits(options) {
+    const given = obj(options);
+    const problems = [];
+    const read = (name) => {
+        const value = given[name];
+        if (value === undefined)
+            return DEFAULT_LIMITS[name];
+        if (typeof value === "number" && Number.isInteger(value) && value > 0)
+            return value;
+        problems.push(`${name} must be a positive integer, not ${JSON.stringify(value)}; using ${DEFAULT_LIMITS[name]}`);
+        return DEFAULT_LIMITS[name];
+    };
+    const limits = { maxDepth: read("maxDepth"), maxChildren: read("maxChildren"), maxTotal: read("maxTotal") };
+    return { limits, problems };
+}
+/** The `nativeChildren` option: whether a child started without isolate gets OpenCode's own `parentID`; off unless `true`. */
+export function readNativeChildren(options) {
+    const value = obj(options).nativeChildren;
+    if (value === undefined || typeof value === "boolean")
+        return { nativeChildren: value === true, problems: [] };
+    return { nativeChildren: false, problems: [`nativeChildren must be true or false, not ${JSON.stringify(value)}; using false`] };
+}
+/** Whether a session with these times runs: it has never finished a turn, or something reached it after the last one ended. */
+export const busy = (time) => time.idle === undefined || millis(time.updated) > millis(time.idle);
+/** `lineage` over roster entries already read. */
+export function lineageIn(entries, sessionID) {
+    return lineageBy(bySession(entries), sessionID);
+}
+/** Roster entries by their session, for `lineageBy`. */
+export function bySession(entries) {
+    return new Map(entries.map((entry) => [entry.sessionID, entry]));
+}
+/** `lineage` over roster entries already read and mapped by `bySession`. */
+export function lineageBy(bySession, sessionID) {
+    const chain = [];
+    for (let entry = bySession.get(sessionID); entry && !chain.includes(entry); entry = bySession.get(entry.parentID))
+        chain.push(entry);
+    return chain;
+}
+/**
+ * The session whose view OpenCode shows the asks of a lineage's first session in: up its native parents, to the
+ * first session that is not a native child (an isolated one, or the top). The session itself when it is not native.
+ */
+export function nativeRootOf(chain) {
+    let root = chain[0].sessionID;
+    for (const entry of chain) {
+        if (!entry.native)
+            break;
+        root = entry.parentID;
+    }
+    return root;
+}
+/** What a group may be called: short, and with no `/`, which separates the parts of its keys, or `"`, which closes an attribute. */
+const NAME = /^[\w.-]{1,60}$/;
+export const isGroupName = (value) => typeof value === "string" && NAME.test(value);
+/** A member's standing from its stored value, or `released` when there is none. */
+export function standingOf(member) {
+    if (!member)
+        return "released";
+    if (member.report)
+        return "held";
+    return member.left?.by ?? "out";
+}
+/** Whether every member of a group has a held report or has left: released once the parent's turn has ended. */
+export const complete = (members) => members.every((member) => member.report || member.left);

package/dist/{watch.d.ts → tree/events.d.ts}

@@ -1,9 +1,5 @@
-import type { Hub, WatchPorts, WatchState } from "./hub.js";
-import { type ExecutionError } from "./notices.js";
-import { type FormCreated, type FormSettled, type PermissionAsked, type PermissionReplied } from "./relay.js";
-export type { FormsTold, WatchPorts, WatchState } from "./hub.js";
-/** How long to wait before subscribing again after the event stream ended or broke. */
-export declare const RESUBSCRIBE_MS = 5000;
+import type { EventModule } from "../platform/events.js";
+import type { ExecutionError, Waits, WatchPorts, WatchState } from "./ports.js";
 /** The part of OpenCode's `session.execution.failed` event the notice is made from. */
 export interface ExecutionFailed {
     readonly id: string;
@@ -59,40 +55,17 @@ export declare function noteInterrupted(ports: WatchPorts, event: SessionEvent):
  * started, whose reports can no longer be delivered; it leaves its own group. Returns the sessions forgotten.
  */
 export declare function noteDeleted(ports: WatchPorts, event: SessionEvent): Promise<string[]>;
+/** A `Waits` asking `suppliers` one after another, cheapest first: the first that waits answers. */
+export declare const waitsOn: (...suppliers: Waits[]) => Waits;
+/** A `Waits` asking `suppliers` at once, as cheap as each other: it waits when one does, and fails when one fails. */
+export declare const together: (...suppliers: Waits[]) => Waits;
 /**
  * Tells the parent of a spawned session whose turn ended without reporting to it since its last
  * prompt, unless it waits; finds the session by the reverse index alone. Returns the parents told.
  */
-export declare function reportSilent(ports: WatchPorts, seen: Set<string>, event: SessionEvent): Promise<string[]>;
+export declare function reportSilent(ports: WatchPorts, seen: Set<string>, event: SessionEvent, outside: Waits): Promise<string[]>;
 /**
- * Tells the session at the top, the parent of a child or the session a chain of children started
- * from, what a waiting child asks and which answers there are, waking it. Returns the sessions told.
+ * Tells parents of a child's failed or silent turn, unless it waits on what `outside` says, and notes
+ * its prompts, interruptions and deletion; `after` a turn's end, seals the groups of its session.
  */
-export declare function reportAsked(ports: WatchPorts, state: WatchState, event: PermissionAsked): Promise<string[]>;
-/**
- * Tells the session told about a request that it was answered some other way, so it does not pass on
- * a stale question; requests answered through courier_answer no longer wait and are skipped.
- */
-export declare function reportReplied(ports: WatchPorts, state: WatchState, event: PermissionReplied): Promise<string[]>;
-/**
- * Tells the top session about a form OpenCode shows in a spawned session, such as web search asking
- * for its provider, which only the person can answer; question forms are left to the question relay.
- */
-export declare function reportForm(ports: WatchPorts, state: WatchState, event: FormCreated): Promise<string[]>;
-/** Tells the session told about a form that it was answered or withdrawn, so it does not send the person to a form that is gone. */
-export declare function reportFormSettled(ports: WatchPorts, state: WatchState, event: FormSettled): Promise<string[]>;
-/**
- * Relays the requests that spawned sessions already wait on, in every loaded location, which the
- * event stream does not repeat: those asked while it was down, before the watcher (re)subscribed.
- */
-export declare function relayPending(ports: WatchPorts, state: WatchState): Promise<void>;
-/**
- * Follows OpenCode's events until `signal` aborts: tells parents of a spawned child's failed or silent
- * turn, its pending permission or form, notes forms and shutdowns for the relay; ends after its current event.
- */
-export declare function watchChildren(ports: WatchPorts, state: WatchState, signal: AbortSignal, retryMs?: number): Promise<void>;
-/**
- * Makes the hub start its subscriptions to OpenCode's events with this copy's watcher, the one loaded
- * last; `join` starts them. The second is a standby, connected before the first's member leaves.
- */
-export declare function watchFromHub(hub: Pick<Hub, "subscribe">, state: WatchState, retryMs?: number): void;
+export declare function treeEvents(state: WatchState, outside: Waits): EventModule<WatchPorts>;

package/dist/tree/events.js

@@ -0,0 +1,204 @@
+import { envelope } from "../kernel/protocol.js";
+import { claim, SEEN_MAX, setBounded } from "../platform/bounded.js";
+import { forgetDeleted } from "./forget.js";
+import { hasCompleteGroup, leave, outIn } from "./group.js";
+import { awaited, reportOf, stoppedSincePrompt } from "./report.js";
+import { childStore, groupStore } from "./store.js";
+import { lastReply } from "./status.js";
+import { failureNotice, silentNotice } from "./text.js";
+/**
+ * Tells the parent of a child whose turn failed, since a child that cannot reach its model cannot
+ * call courier_send. Returns the parents told.
+ */
+export async function reportFailure(ports, seen, event) {
+    if (!claim(seen, event.id))
+        return [];
+    const { sessionID, error } = event.data;
+    const children = childStore(ports.storage);
+    const entries = await children.entriesOf(sessionID);
+    const at = event.created ?? ports.now();
+    // Not in the way of the notice: kept only so the limits stop counting the child.
+    if (entries.length)
+        await children.settled(sessionID, "failed", at).catch((error) => ports.log(`courier watch: could not note the failed turn of ${sessionID}: ${String(error)}`));
+    const out = await Promise.all(entries.map((entry) => outIn(ports, entry)));
+    // Left before the notice, so the parent waits on the group meanwhile; nudged after it, so the group's
+    // message does not overtake the notice, short of an interval tick falling in between.
+    const completed = await Promise.all(out.map((member) => (member ? leave(ports, member, "failed", at) : Promise.resolve(false))));
+    // A session courier_stop stopped is not a failure to tell: its parent was told of the stop, or ordered it.
+    const quiet = entries.length > 0 && (await stoppedSincePrompt(children, sessionID).catch(() => false));
+    try {
+        if (quiet)
+            return [];
+        await Promise.all(entries.map((entry, index) => ports.session.synthetic({
+            sessionID: entry.parentID,
+            text: envelope(sessionID, failureNotice(entry.title, error, out[index]?.group), { failed: error.type }),
+            description: `Session ${sessionID} failed`,
+            metadata: { source: "courier", from: sessionID, failed: true },
+            delivery: "steer",
+        })));
+    }
+    finally {
+        if (completed.includes(true))
+            ports.nudge();
+    }
+    return entries.map((entry) => entry.parentID);
+}
+/** Inbox items that are not courier's or the parent's business: the person's own prompts, compactions and moves. */
+const UNOWED = new Set(["user", "compaction", "move"]);
+/** Remembers the type of an item enqueued for a spawned session, for `notePrompt`; other sessions cost one read. */
+export async function noteEnqueued(ports, inbox, event) {
+    const { sessionID, inboxID, item } = event.data;
+    if ((await childStore(ports.storage).indexedParent(sessionID)) === undefined)
+        return false;
+    setBounded(inbox, inboxID, item.type, SEEN_MAX);
+    return true;
+}
+/**
+ * Notes that a message reached a spawned session, which then owes its parent a report, unless `inbox` knows it for one of
+ * `UNOWED` (`spawn` notes the task itself); reads the reverse index alone, and claims nothing: the note is the same twice.
+ */
+export async function notePrompt(ports, event, inbox) {
+    const { sessionID, inboxID } = event.data;
+    // Kept, not deleted: the hub's other subscription looks it up for the same delivery.
+    if (inboxID !== undefined && UNOWED.has(inbox?.get(inboxID) ?? ""))
+        return false;
+    const children = childStore(ports.storage);
+    if ((await children.indexedParent(sessionID)) === undefined)
+        return false;
+    await children.prompted(sessionID, event.created ?? ports.now());
+    return true;
+}
+/**
+ * Notes that a spawned session's turn was stopped, which takes it out of its group without a report; one
+ * stopped by a shutdown resumes on the next start.
+ */
+export async function noteInterrupted(ports, event) {
+    if (event.data.reason === "shutdown")
+        return false;
+    const { sessionID } = event.data;
+    const children = childStore(ports.storage);
+    const entry = await children.indexedEntry(sessionID);
+    if (entry === undefined)
+        return false;
+    const at = event.created ?? ports.now();
+    await children.settled(sessionID, "interrupted", at);
+    const member = await outIn(ports, entry);
+    if (member && (await leave(ports, member, "interrupted", at)))
+        ports.nudge();
+    return true;
+}
+/**
+ * Drops the report state, and the groups, of a session OpenCode deleted, and the report state of the sessions it
+ * started, whose reports can no longer be delivered; it leaves its own group. Returns the sessions forgotten.
+ */
+export async function noteDeleted(ports, event) {
+    const { sessionID } = event.data;
+    const children = childStore(ports.storage);
+    const [parentID, started] = await Promise.all([children.indexedParent(sessionID), children.children(sessionID)]);
+    const forgotten = [...(parentID === undefined ? [] : [sessionID]), ...started.map((child) => child.sessionID)];
+    const entry = parentID === undefined ? undefined : await children.entry(parentID, sessionID);
+    const member = entry && (await outIn(ports, entry));
+    await forgetDeleted(ports, sessionID, forgotten, member, event.created);
+    return forgotten;
+}
+/** A `Waits` asking `suppliers` one after another, cheapest first: the first that waits answers. */
+export const waitsOn = (...suppliers) => async (ports, sessionID, since) => {
+    for (const supplier of suppliers)
+        if (await supplier(ports, sessionID, since))
+            return true;
+    return false;
+};
+/** A `Waits` asking `suppliers` at once, as cheap as each other: it waits when one does, and fails when one fails. */
+export const together = (...suppliers) => async (ports, sessionID, since) => (await Promise.all(suppliers.map((supplier) => supplier(ports, sessionID, since)))).includes(true);
+/**
+ * Whether a session prompted at `prompt` waits: on an untold report of a session it started, a complete group of
+ * its about to be delivered, or what `outside` says it waits on. Cheapest first.
+ */
+async function waits(ports, outside, sessionID, prompt) {
+    const children = childStore(ports.storage);
+    const started = await children.children(sessionID);
+    if ((await Promise.all(started.map((entry) => awaited(children, entry.sessionID)))).includes(true))
+        return true;
+    // A group with a member still out is waited on through that member, above; one whose every out member was told of is not.
+    if (started.some((entry) => entry.group) && (await hasCompleteGroup(groupStore(ports.storage), sessionID)))
+        return true;
+    return outside(ports, sessionID, prompt);
+}
+/**
+ * Tells the parent of a spawned session whose turn ended without reporting to it since its last
+ * prompt, unless it waits; finds the session by the reverse index alone. Returns the parents told.
+ */
+export async function reportSilent(ports, seen, event, outside) {
+    const { sessionID } = event.data;
+    const children = childStore(ports.storage);
+    const entry = await children.indexedEntry(sessionID);
+    // Claimed after the lookup, so other sessions' turns do not crowd `seen`, and before anything is told.
+    if (!entry || !claim(seen, event.id))
+        return [];
+    const report = await reportOf(children, sessionID);
+    if (!report?.owes || (await waits(ports, outside, sessionID, report.prompt)))
+        return [];
+    if (await stoppedSincePrompt(children, sessionID).catch(() => false))
+        return [];
+    // The notice goes out without the reply rather than not at all.
+    const lastText = await ports.session.context({ sessionID }).then(lastReply, () => undefined);
+    const group = (await outIn(ports, entry))?.group;
+    // Before the notice, which may end the parent's turn at once: once told, it no longer waits for this one.
+    const toldAt = event.created ?? ports.now();
+    await children.told(sessionID, toldAt).catch((error) => ports.log(`courier watch: could not note that the parent of ${sessionID} was told: ${String(error)}`));
+    try {
+        await ports.session.synthetic({
+            sessionID: entry.parentID,
+            text: envelope(sessionID, silentNotice(entry.title, lastText, report.progressed, group), { ended: "without-report" }),
+            description: `Session ${sessionID} ended without a report`,
+            metadata: { source: "courier", from: sessionID, ended: "without-report" },
+            delivery: "steer",
+        });
+    }
+    catch (error) {
+        // Not told after all: the parent still waits for it.
+        await children.untold(sessionID, toldAt).catch(() => undefined);
+        throw error;
+    }
+    return [entry.parentID];
+}
+const TURN_ENDS = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"]);
+/** A session's turn ended, sealing its groups: one that is complete has the scheduler deliver it now. */
+async function sealGroups(ports, event) {
+    if (event.data.reason === "shutdown")
+        return;
+    try {
+        if (await hasCompleteGroup(groupStore(ports.storage), event.data.sessionID))
+            ports.nudge();
+    }
+    catch (error) {
+        ports.log(`courier watch: could not read the groups of ${event.data.sessionID}: ${String(error)}`);
+    }
+}
+/** The events of spawned sessions' turns and inboxes, and their deletion: the tree's. */
+function routeTree(ports, state, outside, event) {
+    if (event.type === "session.execution.failed")
+        return reportFailure(ports, state.seen, event);
+    if (event.type === "session.execution.succeeded")
+        return reportSilent(ports, state.seen, event, outside);
+    if (event.type === "session.execution.interrupted")
+        return noteInterrupted(ports, event);
+    if (event.type === "session.inbox.enqueued")
+        return noteEnqueued(ports, state.inbox, event);
+    if (event.type === "session.inbox.delivered")
+        return notePrompt(ports, event, state.inbox);
+    if (event.type === "session.deleted")
+        return noteDeleted(ports, event);
+    return undefined;
+}
+/**
+ * Tells parents of a child's failed or silent turn, unless it waits on what `outside` says, and notes
+ * its prompts, interruptions and deletion; `after` a turn's end, seals the groups of its session.
+ */
+export function treeEvents(state, outside) {
+    return {
+        handle: (ports, event) => routeTree(ports, state, outside, event),
+        // After: a silent end is judged while the group the nudge may deliver is still there to wait on.
+        after: (ports, event) => (TURN_ENDS.has(event.type) ? sealGroups(ports, event) : undefined),
+    };
+}

package/dist/tree/forget.d.ts

@@ -0,0 +1,24 @@
+import type { CleanupPorts, GroupStore, Membership, ReportKeys, RosterEntry, RosterStorage, WatchPorts } from "./ports.js";
+/** Drops a member from its group as its roster entry goes, unless its report is held: that still goes to the parent. True when dropped. */
+export declare function dropMember(groups: GroupStore, parentID: string, group: string, sessionID: string): Promise<boolean>;
+/** Drops every group of a parent, whose members' reports can no longer be delivered. */
+export declare function dropGroups(groups: GroupStore, parentID: string): Promise<void>;
+/**
+ * Forgets a child: its roster entry, its reverse key, its report state and, given its group, its membership. Only
+ * the entry's removal can fail it: keys left behind lead nowhere, and the next load drops them.
+ */
+export declare function forgetChild(storage: RosterStorage, parentID: string, sessionID: string, group?: string): Promise<{
+    droppedFromGroup: boolean;
+}>;
+/**
+ * Drops a member still out from its group as `dropped`, so the group is released without it, then the roster entry
+ * and report state. A held report stays with its group. Returns the group it was dropped from.
+ */
+export declare function forgetDropped(ports: Pick<CleanupPorts, "storage" | "now" | "nudge">, entry: RosterEntry): Promise<string | undefined>;
+/**
+ * Forgets what a session OpenCode deleted leaves: the report state of `forgotten`, itself and the sessions it started,
+ * and its groups; `member`, its place in its own group, it leaves at `created`, or now.
+ */
+export declare function forgetDeleted(ports: WatchPorts, sessionID: string, forgotten: ReadonlyArray<string>, member: Membership | undefined, created?: number): Promise<void>;
+/** Removes report keys of sessions with no roster entry; a key that will not go is left for the next load. */
+export declare function forgetReports(storage: RosterStorage, keys: ReportKeys, sessions: ReadonlyArray<string>): Promise<void>;

package/dist/tree/forget.js

@@ -0,0 +1,59 @@
+import { leave, markLeft, membershipFor } from "./group.js";
+import { childStore, groupStore } from "./store.js";
+// Forgetting a child and what it leaves behind. Its roster entry and report state go together; its group is another
+// aggregate, left best effort and alongside, so a report held there outlives the entry and still reaches the parent.
+/** Drops a member from its group as its roster entry goes, unless its report is held: that still goes to the parent. True when dropped. */
+export async function dropMember(groups, parentID, group, sessionID) {
+    const member = await groups.member(parentID, group, sessionID);
+    if (!member || member.report)
+        return false;
+    await groups.remove(parentID, group, sessionID);
+    return true;
+}
+/** Drops every group of a parent, whose members' reports can no longer be delivered. */
+export async function dropGroups(groups, parentID) {
+    const members = await groups.ofParent(parentID);
+    await Promise.all(members.map((member) => groups.remove(parentID, member.group, member.sessionID)));
+}
+/**
+ * Forgets a child: its roster entry, its reverse key, its report state and, given its group, its membership. Only
+ * the entry's removal can fail it: keys left behind lead nowhere, and the next load drops them.
+ */
+export async function forgetChild(storage, parentID, sessionID, group) {
+    const [, dropped] = await Promise.all([
+        childStore(storage).remove(parentID, sessionID),
+        group ? dropMember(groupStore(storage), parentID, group, sessionID).catch(() => false) : false,
+    ]);
+    return { droppedFromGroup: dropped };
+}
+/**
+ * Drops a member still out from its group as `dropped`, so the group is released without it, then the roster entry
+ * and report state. A held report stays with its group. Returns the group it was dropped from.
+ */
+export async function forgetDropped(ports, entry) {
+    const groups = groupStore(ports.storage);
+    const member = await membershipFor(groups, entry);
+    if (member?.out && (await markLeft(groups, member, "dropped", ports.now())))
+        ports.nudge();
+    await forgetChild(ports.storage, entry.parentID, entry.sessionID);
+    return member?.out ? member.group : undefined;
+}
+/**
+ * Forgets what a session OpenCode deleted leaves: the report state of `forgotten`, itself and the sessions it started,
+ * and its groups; `member`, its place in its own group, it leaves at `created`, or now.
+ */
+export async function forgetDeleted(ports, sessionID, forgotten, member, created) {
+    const children = childStore(ports.storage);
+    // Its groups go whether or not it has children on the roster: a held report outlives the member's entry.
+    const [completed] = await Promise.all([
+        member ? leave(ports, member, "deleted", created ?? ports.now()) : Promise.resolve(false),
+        ...forgotten.map((id) => children.forgetReport(id)),
+        dropGroups(groupStore(ports.storage), sessionID),
+    ]);
+    if (completed)
+        ports.nudge();
+}
+/** Removes report keys of sessions with no roster entry; a key that will not go is left for the next load. */
+export async function forgetReports(storage, keys, sessions) {
+    await childStore(storage).dropReported(sessions.flatMap((sessionID) => keys.get(sessionID) ?? []));
+}