opencode-courier 0.2.2 → 0.3.0

package/dist/report.js

@@ -0,0 +1,88 @@
+import { obj } from "./json.js";
+import { isStatus } from "./notices.js";
+/**
+ * Whether a spawned session has reported since its last prompt, under `report/<sessionID>/`: `prompt`, `settled` (with
+ * the report's status), `progress` (a message to its parent without a status) and `told`; docs/reference.md has each.
+ */
+const PREFIX = "report/";
+export const promptKey = (sessionID) => `${PREFIX}${sessionID}/prompt`;
+export const settledKey = (sessionID) => `${PREFIX}${sessionID}/settled`;
+export const progressKey = (sessionID) => `${PREFIX}${sessionID}/progress`;
+export const toldKey = (sessionID) => `${PREFIX}${sessionID}/told`;
+export const stoppedKey = (sessionID) => `${PREFIX}${sessionID}/stopped`;
+const timeOf = (value) => {
+    const at = obj(value).at;
+    return typeof at === "number" && Number.isFinite(at) ? at : undefined;
+};
+/**
+ * Notes that a prompt or message reached a spawned session at `at`, in epoch milliseconds, unless a
+ * later one is noted: both of the hub's subscriptions note each event, one of them maybe behind.
+ */
+export async function prompted(storage, sessionID, at) {
+    if ((timeOf(await storage.get(promptKey(sessionID))) ?? -Infinity) < at)
+        await storage.set(promptKey(sessionID), { at });
+}
+/**
+ * Notes that a spawned session reported to its parent, with `status` when its report carried one, or
+ * its turn failed or was interrupted, at `at`, unless a later end is noted.
+ */
+export async function settled(storage, sessionID, by, at, status) {
+    if ((timeOf(await storage.get(settledKey(sessionID))) ?? -Infinity) <= at)
+        await storage.set(settledKey(sessionID), { at, by, ...(status ? { status } : {}) });
+}
+/** Notes that a spawned session messaged its parent without a status at `at`, which is progress, not its report. */
+export async function progressed(storage, sessionID, at) {
+    if ((timeOf(await storage.get(progressKey(sessionID))) ?? -Infinity) <= at)
+        await storage.set(progressKey(sessionID), { at });
+}
+/** Notes that a spawned session's parent was told, at `at`, that a turn of it ended without a report, unless a later telling is noted. */
+export async function told(storage, sessionID, at) {
+    if ((timeOf(await storage.get(toldKey(sessionID))) ?? -Infinity) <= at)
+        await storage.set(toldKey(sessionID), { at });
+}
+/** Takes back the note `told` made at `at`, whose notice did not go out; a later one stays, and one that cannot be read goes. */
+export async function untold(storage, sessionID, at) {
+    const stored = await storage.get(toldKey(sessionID)).then(timeOf, () => at);
+    if (stored === at)
+        await storage.remove(toldKey(sessionID));
+}
+/** Whether `at` is known and no earlier than the prompt at `prompt`. */
+const since = (at, prompt) => at !== undefined && at >= prompt;
+/** Notes that courier_stop stopped a spawned session at `at`, so the failure and silent-end notices stay quiet for it. */
+export async function stopped(storage, sessionID, at) {
+    await storage.set(stoppedKey(sessionID), { at });
+}
+/** Whether courier_stop stopped a session after its last prompt, or with none noted, at all. */
+export async function stoppedSincePrompt(storage, sessionID) {
+    const [stoppedAt, prompt] = await Promise.all([stoppedKey, promptKey].map((key) => storage.get(key(sessionID)).then(timeOf)));
+    return stoppedAt !== undefined && (prompt === undefined || stoppedAt >= prompt);
+}
+/** The status of a spawned session's last report to its parent, if it has reported with one. */
+export async function lastStatus(storage, sessionID) {
+    const status = obj(await storage.get(settledKey(sessionID))).status;
+    return isStatus(status) ? status : undefined;
+}
+/**
+ * What is known of a spawned session's report: when a prompt last reached it, and whether since then it owes one, has
+ * messaged its parent without a status, or failed or was interrupted. Undefined for one spawned before this was kept.
+ */
+export async function reportOf(storage, sessionID) {
+    const [prompt, settledValue, progress] = await Promise.all([promptKey, settledKey, progressKey].map((key) => storage.get(key(sessionID))));
+    const promptAt = timeOf(prompt);
+    if (promptAt === undefined)
+        return undefined;
+    const done = since(timeOf(settledValue), promptAt);
+    return { prompt: promptAt, owes: !done, progressed: since(timeOf(progress), promptAt), ended: done && obj(settledValue).by !== "report" };
+}
+/**
+ * Whether its parent still waits on a spawned session's report: it owes one, and the parent has not
+ * been told since its last prompt that it ended a turn without one.
+ */
+export async function awaited(storage, sessionID) {
+    const [prompt, settledAt, toldAt] = await Promise.all([promptKey, settledKey, toldKey].map((key) => storage.get(key(sessionID)).then(timeOf)));
+    return prompt !== undefined && !since(settledAt, prompt) && !since(toldAt, prompt);
+}
+/** Drops what is kept about a session, with its roster entry. */
+export async function forgetReport(storage, sessionID) {
+    await Promise.all([promptKey, settledKey, progressKey, toldKey, stoppedKey].map((key) => storage.remove(key(sessionID))));
+}

package/dist/roster.d.ts

@@ -18,10 +18,33 @@ export interface RosterEntry {
     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;
+}
+/**
+ * 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>;
 }
 export type RosterStorage = Storage;
 export declare function rosterKey(parentID: string, sessionID: string): string;
+export declare function reverseKey(sessionID: string): string;
+/**
+ * Records a child under its parent, then indexes it. The entry is what counts: a failed index
+ * write leaves it to be found by a scan, and to be indexed when the plugin is next loaded.
+ */
 export declare function record(storage: RosterStorage, entry: RosterEntry): Promise<void>;
+/**
+ * Removes a child's roster entry, its reverse key, its report state and, given its group, its membership. Only
+ * the entry's removal can fail it: a reverse key left behind leads nowhere, and the next load drops it.
+ */
+export declare function remove(storage: RosterStorage, parentID: string, sessionID: string, group?: string): Promise<{
+    droppedFromGroup: boolean;
+}>;
 /** Removes a child from its parent's roster; false when it was not there. */
 export declare function forget(storage: RosterStorage, parentID: string, sessionID: string): Promise<boolean>;
 /** A parent's children, oldest first. */
@@ -30,24 +53,41 @@ export declare function children(storage: RosterStorage, parentID: string): Prom
 export declare function allEntries(storage: RosterStorage): Promise<RosterEntry[]>;
 /** A session's roster entries: one for the parent that started it, none if courier_spawn did not. */
 export declare function entriesOf(storage: RosterStorage, sessionID: string): Promise<RosterEntry[]>;
+/** The session that started a session, by the reverse index alone, without scanning the roster. */
+export declare function indexedParent(storage: RosterStorage, sessionID: string): Promise<string | undefined>;
+/** A session's roster entry under a parent, if it is there. */
+export declare function entryUnder(storage: RosterStorage, parentID: string, sessionID: string): Promise<RosterEntry | undefined>;
+/** A session's roster entry, by the reverse index alone, without scanning the roster. */
+export declare function indexedEntry(storage: RosterStorage, sessionID: string): Promise<RosterEntry | undefined>;
 /**
- * The roster entries from a session up to the top, its own first: the session's, its parent's, and
- * so on, ending with the entry whose parent courier_spawn did not start. Empty when courier_spawn
- * did not start the session.
+ * The roster entries from a session up to the top, its own first, ending with the entry whose parent
+ * courier_spawn did not start; empty when courier_spawn did not start the session.
  */
 export declare function lineage(storage: RosterStorage, sessionID: string): Promise<RosterEntry[]>;
+/** `lineage` by the reverse index alone: empty, without scanning the roster, when it does not name the session. */
+export declare function indexedLineage(storage: RosterStorage, sessionID: string): Promise<never[] | RosterEntry[]>;
 /** `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 at the top of a spawned session's lineage, where its permission requests and
- * questions go, since that is where the person is; only it may answer them. Throws when the
- * session was not started with courier_spawn or `callerID` is another session. `what` names
- * what is being answered.
+ * The top of a spawned session's lineage, where its permission requests and questions go, since the
+ * person is there. Throws unless the session was spawned and `callerID` is that top; `what` names it.
  */
 export declare function answeringTop(storage: RosterStorage, sessionID: string, callerID: string, what: string): Promise<string>;
 /** Whether a directory still exists; tests pass a fake. */
 export type Exists = (directory: string) => boolean;
 /** A parent's children, oldest first, after dropping the expired ones. */
 export declare function current(storage: RosterStorage, parentID: string, now: number, exists?: Exists): Promise<RosterEntry[]>;
-/** Drops expired entries of every parent, so parents that never list their children don't keep them forever. */
+/**
+ * On loading: drops expired entries of every parent, so parents that never list their children
+ * don't keep them forever, then brings the reverse index in line with what is left (`backfill`).
+ */
 export declare function pruneExpired(storage: RosterStorage, now: number, exists?: Exists): Promise<void>;
+/**
+ * Writes the reverse keys missing or stale for the given entries, or the whole roster, and drops those
+ * whose entry is gone, as an older copy's writes and removals leave them; a rerun changes nothing.
+ */
+export declare function backfill(storage: RosterStorage, entries: ReadonlyArray<RosterEntry>): Promise<void>;

package/dist/roster.js

@@ -1,23 +1,60 @@
 import { existsSync } from "node:fs";
-import { scanAll } from "./storage.js";
+import { dropMember } from "./group.js";
+import { forgetReport } from "./report.js";
+import { scanAll, scanEntries } from "./storage.js";
 /**
  * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
  * except isolated children whose worktree is still there: those stay until courier_cleanup.
  */
 export const RETENTION_MS = 14 * 24 * 60 * 60_000;
 const PREFIX = "roster/";
+/**
+ * The reverse index: a child's `ReverseEntry` under `roster-by-child/<sessionID>`, written with its
+ * roster entry; only an index, so `roster/` is scanned for entries lacking one, and confirms a hit.
+ */
+const BY_CHILD = "roster-by-child/";
 export function rosterKey(parentID, sessionID) {
     return `${PREFIX}${parentID}/${sessionID}`;
 }
+export function reverseKey(sessionID) {
+    return `${BY_CHILD}${sessionID}`;
+}
+/**
+ * Records a child under its parent, then indexes it. The entry is what counts: a failed index
+ * write leaves it to be found by a scan, and to be indexed when the plugin is next loaded.
+ */
 export async function record(storage, entry) {
     await storage.set(rosterKey(entry.parentID, entry.sessionID), { ...entry });
+    await index(storage, entry).catch(() => undefined);
+}
+async function index(storage, entry) {
+    const above = await storage.get(reverseKey(entry.parentID));
+    const ancestors = isReverse(above) ? above.ancestors : (await lineage(storage, entry.parentID)).map((parent) => parent.parentID);
+    await storage.set(reverseKey(entry.sessionID), { ancestors: [entry.parentID, ...ancestors] });
+}
+function isReverse(value) {
+    const ancestors = value?.ancestors;
+    return Array.isArray(ancestors) && ancestors.length > 0 && ancestors.every((id) => typeof id === "string");
+}
+/**
+ * Removes a child's roster entry, its reverse key, its report state and, given its group, its membership. Only
+ * the entry's removal can fail it: a reverse key left behind leads nowhere, and the next load drops it.
+ */
+export async function remove(storage, parentID, sessionID, group) {
+    const [, , , dropped] = await Promise.all([
+        storage.remove(rosterKey(parentID, sessionID)),
+        storage.remove(reverseKey(sessionID)).catch(() => undefined),
+        forgetReport(storage, sessionID).catch(() => undefined),
+        group ? dropMember(storage, parentID, group, sessionID).catch(() => false) : false,
+    ]);
+    return { droppedFromGroup: dropped };
 }
 /** Removes a child from its parent's roster; false when it was not there. */
 export async function forget(storage, parentID, sessionID) {
-    const key = rosterKey(parentID, sessionID);
-    if ((await storage.get(key)) === undefined)
+    const entry = (await storage.get(rosterKey(parentID, sessionID)));
+    if (entry === undefined)
         return false;
-    await storage.remove(key);
+    await remove(storage, parentID, sessionID, entry.group);
     return true;
 }
 /** A parent's children, oldest first. */
@@ -31,29 +68,83 @@ export async function allEntries(storage) {
 }
 /** A session's roster entries: one for the parent that started it, none if courier_spawn did not. */
 export async function entriesOf(storage, sessionID) {
-    return (await scanAll(storage, PREFIX)).filter((entry) => entry.sessionID === sessionID);
+    const parentID = await indexedParent(storage, sessionID);
+    if (parentID === undefined)
+        return (await scanAll(storage, PREFIX)).filter((entry) => entry.sessionID === sessionID);
+    const entry = await storage.get(rosterKey(parentID, sessionID));
+    return entry === undefined ? [] : [entry];
+}
+/** The session that started a session, by the reverse index alone, without scanning the roster. */
+export async function indexedParent(storage, sessionID) {
+    const indexed = await storage.get(reverseKey(sessionID));
+    return isReverse(indexed) ? indexed.ancestors[0] : undefined;
+}
+/** A session's roster entry under a parent, if it is there. */
+export async function entryUnder(storage, parentID, sessionID) {
+    return (await storage.get(rosterKey(parentID, sessionID)));
+}
+/** A session's roster entry, by the reverse index alone, without scanning the roster. */
+export async function indexedEntry(storage, sessionID) {
+    const parentID = await indexedParent(storage, sessionID);
+    return parentID === undefined ? undefined : entryUnder(storage, parentID, sessionID);
 }
 /**
- * The roster entries from a session up to the top, its own first: the session's, its parent's, and
- * so on, ending with the entry whose parent courier_spawn did not start. Empty when courier_spawn
- * did not start the session.
+ * The roster entries from a session up to the top, its own first, ending with the entry whose parent
+ * courier_spawn did not start; empty when courier_spawn did not start the session.
  */
 export async function lineage(storage, sessionID) {
-    return lineageIn(await allEntries(storage), sessionID);
+    const first = await storage.get(reverseKey(sessionID));
+    if (!isReverse(first))
+        return lineageIn(await allEntries(storage), sessionID);
+    return walkIndex(storage, sessionID, first);
+}
+/** `lineage` by the reverse index alone: empty, without scanning the roster, when it does not name the session. */
+export async function indexedLineage(storage, sessionID) {
+    const first = await storage.get(reverseKey(sessionID));
+    return isReverse(first) ? walkIndex(storage, sessionID, first) : [];
+}
+async function walkIndex(storage, sessionID, first) {
+    let indexed = first;
+    const chain = [];
+    let below = sessionID;
+    // One read per level, all at once, and one more for the top's own reverse key, in case it was
+    // recorded after the key that names it; the chain ends where an entry is gone, as a scan's would.
+    for (;;) {
+        const { ancestors } = indexed;
+        const top = ancestors.at(-1);
+        const [entries, above] = await Promise.all([
+            Promise.all(ancestors.map((parentID, level) => storage.get(rosterKey(parentID, level ? ancestors[level - 1] : below)))),
+            storage.get(reverseKey(top)),
+        ]);
+        for (const entry of entries) {
+            if (!entry || chain.some((known) => known.sessionID === entry.sessionID))
+                return chain;
+            chain.push(entry);
+        }
+        if (!isReverse(above))
+            return chain;
+        below = top;
+        indexed = above;
+    }
 }
 /** `lineage` over roster entries already read. */
 export function lineageIn(entries, sessionID) {
-    const bySession = new Map(entries.map((entry) => [entry.sessionID, entry]));
+    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 at the top of a spawned session's lineage, where its permission requests and
- * questions go, since that is where the person is; only it may answer them. Throws when the
- * session was not started with courier_spawn or `callerID` is another session. `what` names
- * what is being answered.
+ * The top of a spawned session's lineage, where its permission requests and questions go, since the
+ * person is there. Throws unless the session was spawned and `callerID` is that top; `what` names it.
  */
 export async function answeringTop(storage, sessionID, callerID, what) {
     const chain = await lineage(storage, sessionID);
@@ -70,14 +161,46 @@ export async function answeringTop(storage, sessionID, callerID, what) {
  */
 async function dropExpired(storage, entries, now, exists) {
     const expired = new Set(entries.filter((entry) => now - entry.createdAt > RETENTION_MS && !(entry.isolated && exists(entry.directory))));
-    await Promise.all([...expired].map((entry) => storage.remove(rosterKey(entry.parentID, entry.sessionID))));
+    await Promise.all([...expired].map((entry) => remove(storage, entry.parentID, entry.sessionID, entry.group)));
     return entries.filter((entry) => !expired.has(entry));
 }
 /** A parent's children, oldest first, after dropping the expired ones. */
 export async function current(storage, parentID, now, exists = existsSync) {
     return dropExpired(storage, await children(storage, parentID), now, exists);
 }
-/** Drops expired entries of every parent, so parents that never list their children don't keep them forever. */
+/**
+ * On loading: drops expired entries of every parent, so parents that never list their children
+ * don't keep them forever, then brings the reverse index in line with what is left (`backfill`).
+ */
 export async function pruneExpired(storage, now, exists = existsSync) {
-    await dropExpired(storage, await scanAll(storage, PREFIX), now, exists);
+    await backfill(storage, await dropExpired(storage, await scanAll(storage, PREFIX), now, exists));
+}
+/** Whether a reverse key's value leads to this entry. */
+function indexes(value, entry) {
+    return isReverse(value) && value.ancestors[0] === entry.parentID;
+}
+/**
+ * Writes the reverse keys missing or stale for the given entries, or the whole roster, and drops those
+ * whose entry is gone, as an older copy's writes and removals leave them; a rerun changes nothing.
+ */
+export async function backfill(storage, entries) {
+    const indexed = new Map((await scanEntries(storage, BY_CHILD)).map(({ key, value }) => [key, value]));
+    const sessions = new Set(entries.map((entry) => entry.sessionID));
+    await Promise.all([
+        ...entries
+            .filter((entry) => !indexes(indexed.get(entry.sessionID), entry))
+            .map((entry) => storage.set(reverseKey(entry.sessionID), { ancestors: lineageIn(entries, entry.sessionID).map((above) => above.parentID) })),
+        ...[...indexed]
+            .filter(([sessionID]) => !sessions.has(sessionID))
+            .map(([sessionID, value]) => dropDangling(storage, sessionID, value)),
+    ]);
+}
+/**
+ * Drops a reverse key whose entry was not in the roster read, unless that entry is there now:
+ * another instance may have recorded the child since, and it writes the entry before the key.
+ */
+async function dropDangling(storage, sessionID, value) {
+    if (isReverse(value) && (await storage.get(rosterKey(value.ancestors[0], sessionID))) !== undefined)
+        return;
+    await storage.remove(reverseKey(sessionID));
 }

package/dist/skill.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from "@opencode/plugin";
+/** The editor OpenCode hands a skill transform. */
+export type SkillEditor = Parameters<Parameters<Plugin.Context["skill"]["transform"]>[0]>[0];
+/** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */
+export declare const orchestrateSkill: () => {
+    readonly id: "courier-orchestrate";
+    readonly name: "courier-orchestrate";
+    readonly description: string;
+    readonly path: "/opencode-courier/courier-orchestrate.md";
+    readonly content: string;
+};
+/** Adds the courier-orchestrate skill; every instance adds the same one, under the same id. */
+export declare function addSkill(skills: SkillEditor): void;

package/dist/skill.js

@@ -0,0 +1,9 @@
+import { SKILL_CONTENT, SKILL_DESCRIPTION, SKILL_ID } from "./notices.js";
+/** A skill's path is where OpenCode would look for its files; this one has none, so a path of the plugin's own. */
+const SKILL_PATH = `/opencode-courier/${SKILL_ID}.md`;
+/** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */
+export const orchestrateSkill = () => ({ id: SKILL_ID, name: SKILL_ID, description: SKILL_DESCRIPTION, path: SKILL_PATH, content: SKILL_CONTENT });
+/** Adds the courier-orchestrate skill; every instance adds the same one, under the same id. */
+export function addSkill(skills) {
+    skills.add(orchestrateSkill());
+}

package/dist/stop.d.ts

@@ -0,0 +1,41 @@
+import { type CleanupPorts } from "./cleanup.js";
+import { type CourierPorts } from "./courier.js";
+import { type LaterPorts } from "./later.js";
+import { type CleanupResult } from "./notices.js";
+export interface StopPorts {
+    readonly courier: CourierPorts;
+    readonly later: LaterPorts;
+    readonly cleanup: CleanupPorts;
+}
+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;
+}
+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 function stop(ports: StopPorts, callerID: string, input: StopInput): Promise<StopResult>;

package/dist/stop.js

@@ -0,0 +1,120 @@
+import { cleanup } from "./cleanup.js";
+import { describeFailure } from "./courier.js";
+import { isNotFound } from "./json.js";
+import { cancel, scheduledFor } from "./later.js";
+import { envelope, stoppedNotice } from "./notices.js";
+import { settled, stopped } from "./report.js";
+import { lineage } from "./roster.js";
+import { subtree } from "./tree.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 async function stop(ports, callerID, input) {
+    const { storage } = ports.courier;
+    const { sessionID } = input;
+    const chain = await lineage(storage, sessionID);
+    if (!chain.length)
+        throw new Error(`${sessionID} was not started with courier_spawn, so courier_stop cannot stop it.`);
+    const target = chain[0];
+    if (!chain.some((entry) => entry.parentID === callerID))
+        throw new Error(`${callerID} is not above ${sessionID}: only a session above it, in the line of sessions that started it with courier_spawn, can stop it.`);
+    const seen = new Set();
+    const nodes = [];
+    const results = [];
+    const cancelled = [];
+    const round = async (pending, left) => {
+        if (!pending.length || left === 0)
+            return;
+        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)));
+        results.push(...(await eachDeepestFirst(pending, (node) => interrupt(ports, node))));
+        const meanwhile = (await subtree(storage, sessionID)).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);
+    const told = target.parentID !== callerID && results.find((one) => one.sessionID === sessionID)?.outcome === "interrupted"
+        ? await tell(ports, callerID, target)
+        : undefined;
+    return {
+        sessionID,
+        stopped: results,
+        cancelled,
+        ...(input.cleanup ? { cleanup: await removeWorktrees(ports, nodes) } : {}),
+        ...(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) {
+    const { storage, now, log } = ports.courier;
+    await stopped(storage, sessionID, now()).catch((error) => log(`courier_stop: could not note that ${sessionID} was stopped: ${String(error)}`));
+    try {
+        const pending = await scheduledFor(storage, sessionID);
+        const dropped = await Promise.all(pending.map(async (later) => ((await cancel(ports.later, later.id)) ? later.id : undefined)));
+        cancelled.push(...dropped.filter((id) => id !== undefined));
+    }
+    catch (error) {
+        log(`courier_stop: could not cancel the messages scheduled for ${sessionID}: ${String(error)}`);
+    }
+}
+async function interrupt(ports, { entry, depth }) {
+    const { sessionID, title } = entry;
+    const { storage, session, now } = ports.courier;
+    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)
+            await settled(storage, sessionID, "interrupted", now()).catch(() => undefined);
+        return { sessionID, title, depth, 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 };
+    }
+}
+/** Tells the target's parent, which is below the caller, that it was stopped; undefined when that could not be done. */
+async function tell(ports, callerID, target) {
+    const { session, log } = ports.courier;
+    try {
+        await session.synthetic({
+            sessionID: target.parentID,
+            text: envelope(target.sessionID, stoppedNotice(target.title, callerID), { ended: "stopped" }),
+            description: `Session ${target.sessionID} was stopped`,
+            metadata: { source: "courier", from: target.sessionID, ended: "stopped" },
+            delivery: "steer",
+        });
+        return target.parentID;
+    }
+    catch (error) {
+        log(`courier_stop: could not tell ${target.parentID} that ${target.sessionID} was stopped: ${String(error)}`);
+        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)
+            return done;
+        const { entry } = next;
+        const result = await cleanup(ports.cleanup, entry.parentID, { sessionID: entry.sessionID }).catch((error) => ({
+            sessionID: entry.sessionID,
+            outcome: "failed",
+            error: describeFailure("courier_cleanup", error).message,
+        }));
+        return removeNext(rest, [...done, result]);
+    };
+    return removeNext(nodes.filter((node) => node.entry.isolated).sort((a, b) => b.depth - a.depth), []);
+}

package/dist/storage.d.ts

@@ -3,9 +3,16 @@ type Context = Plugin.Context;
 export type Storage = Pick<Context["storage"], "get" | "set" | "remove" | "scan">;
 /** Every value stored under `prefix`, following the scan's pages. */
 export declare function scanAll<T>(storage: Pick<Storage, "scan">, prefix: string): Promise<T[]>;
+/** Every key under `prefix`, without the prefix, with its value, following the scan's pages. */
+export declare function scanEntries<T>(storage: Pick<Storage, "scan">, prefix: string): Promise<{
+    key: string;
+    value: T;
+}[]>;
+/** Where process-wide values are kept: `globalThis`, or a stand-in for it in tests. */
+export type Registry = Record<symbol, unknown>;
 /**
  * The one value the whole process keeps under `Symbol.for(key)`, made by `create` the first time,
  * so every instance of the plugin, and every copy of it loaded later, gets the same one.
  */
-export declare function processWide<T>(key: string, create: () => T): T;
+export declare function processWide<T>(key: string, create: () => T, registry?: Registry): T;
 export {};

package/dist/storage.js

@@ -1,21 +1,24 @@
 /** Every value stored under `prefix`, following the scan's pages. */
 export async function scanAll(storage, prefix) {
-    const values = [];
+    return (await scanEntries(storage, prefix)).map((entry) => entry.value);
+}
+/** Every key under `prefix`, without the prefix, with its value, following the scan's pages. */
+export async function scanEntries(storage, prefix) {
+    const entries = [];
     let after;
     do {
         const page = await storage.scan({ prefix, ...(after ? { after } : {}) });
         for (const entry of page.entries)
-            values.push(entry.value);
+            entries.push({ key: entry.key.slice(prefix.length), value: entry.value });
         after = page.next;
     } while (after);
-    return values;
+    return entries;
 }
 /**
  * The one value the whole process keeps under `Symbol.for(key)`, made by `create` the first time,
  * so every instance of the plugin, and every copy of it loaded later, gets the same one.
  */
-export function processWide(key, create) {
-    const registry = globalThis;
+export function processWide(key, create, registry = globalThis) {
     const symbol = Symbol.for(key);
     registry[symbol] ??= create();
     return registry[symbol];