opencode-courier 0.2.3 → 0.3.0

package/dist/question/lifecycle.d.ts

@@ -6,25 +6,18 @@ import type { QuestionPorts } from "../hub.js";
  */
 export declare const shutdownReportedAt: (directory?: string) => number | undefined;
 /**
- * Called for OpenCode's `location.shutdown`: the location at `directory` is closing, which
- * withdraws its open forms as if the person had dismissed them (before unloading the plugin
- * there, since OpenCode 2.0.22). The event's location is optional in the schema; without it,
- * the shutdown counts for every location. `at` is when, by the watcher's clock (epoch milliseconds).
+ * Called for `location.shutdown`: the location at `directory` is closing, which withdraws its open
+ * forms as if dismissed; with no location it counts for all. `at` is the watcher's clock, epoch ms.
  */
 export declare function locationClosing(at: number, directory?: string): void;
 /**
- * Whether a dismissal just seen in the location at `directory` was that location closing rather
- * than the person: true when it shut down within the dismissal grace before, or does so, or this
- * instance unloads, within the grace from now, by the clock of `ports`. A shutdown reported without a location counts for every
- * location, and with the directory unknown, any location's shutdown counts.
+ * Whether a dismissal just seen at `directory` was the location closing rather than the person: it
+ * shut down within the grace, before or after, or this instance unloads in it; unknown matches any.
  */
 export declare const closingSoon: (ports: QuestionPorts, loaded: () => boolean, directory: string | undefined) => Effect.Effect<boolean>;
 /**
- * Adds a plugin instance's ports to `loaded`, which copies of other versions read to tell a cut-off
- * question through it, until the returned function is called. A location loading again forgets the
- * shutdown recorded for it, so a dismissal there is not mistaken for that shutdown. One recorded for
- * every location is left alone, since a dismissal held in another location may still need it; it
- * ages out with the grace.
+ * Adds an instance's ports to `loaded`, which other copies tell cut-off questions through, until the
+ * returned function is called. A location loading again forgets the shutdown recorded for it alone.
  */
 export declare function joinRelay(ports: QuestionPorts): () => void;
 /** Called for OpenCode's `form.created`: a question call's form is shown, so its question can be relayed. */
@@ -37,15 +30,13 @@ export declare function formShown(event: {
     };
 }): void;
 /**
- * Called when an event stream may have missed forms being shown: every call still waiting for its
- * form is taken as shown. One still waiting for its permission check is relayed early, which is the
- * lesser harm.
+ * Called when an event stream may have missed forms shown: every call still waiting for its form is
+ * taken as shown; one still waiting for its permission check is relayed early, the lesser harm.
  */
 export declare function formsMayHaveBeenMissed(): void;
 /**
- * Called when an instance starts following OpenCode's events. Every instance is sent every event,
- * so a form shown is missed only while none follows them; then the calls waiting are released, and
- * true is returned, for the caller to release them again on its first event, once it is connected.
+ * Called when an instance starts following OpenCode's events: a shown form is missed only while none
+ * follows, so waiting calls are released; true tells the caller to release again on its first event.
  */
 export declare function eventsFollowed(): boolean;
 /** Called when an instance's event stream ended or broke. */

package/dist/question/lifecycle.js

@@ -12,10 +12,8 @@ const shutdownAt = (directory) => directory === undefined
  */
 export const shutdownReportedAt = (directory) => shutdownAt(directory) || undefined;
 /**
- * Called for OpenCode's `location.shutdown`: the location at `directory` is closing, which
- * withdraws its open forms as if the person had dismissed them (before unloading the plugin
- * there, since OpenCode 2.0.22). The event's location is optional in the schema; without it,
- * the shutdown counts for every location. `at` is when, by the watcher's clock (epoch milliseconds).
+ * Called for `location.shutdown`: the location at `directory` is closing, which withdraws its open
+ * forms as if dismissed; with no location it counts for all. `at` is the watcher's clock, epoch ms.
  */
 export function locationClosing(at, directory) {
     shared.shutdowns.set(directory ?? ANYWHERE, at);
@@ -23,10 +21,8 @@ export function locationClosing(at, directory) {
         wake();
 }
 /**
- * Whether a dismissal just seen in the location at `directory` was that location closing rather
- * than the person: true when it shut down within the dismissal grace before, or does so, or this
- * instance unloads, within the grace from now, by the clock of `ports`. A shutdown reported without a location counts for every
- * location, and with the directory unknown, any location's shutdown counts.
+ * Whether a dismissal just seen at `directory` was the location closing rather than the person: it
+ * shut down within the grace, before or after, or this instance unloads in it; unknown matches any.
  */
 export const closingSoon = (ports, loaded, directory) => Effect.suspend(() => {
     const ms = ports.timing.dismissalGraceMs;
@@ -47,11 +43,8 @@ export const closingSoon = (ports, loaded, directory) => Effect.suspend(() => {
     }), () => (Deferred.isDoneUnsafe(closed) ? Effect.succeed(true) : Effect.raceFirst(Deferred.await(closed), Effect.as(Effect.sleep(ms), false))), () => Effect.sync(() => shared.closingWaiters.delete(wake)));
 });
 /**
- * Adds a plugin instance's ports to `loaded`, which copies of other versions read to tell a cut-off
- * question through it, until the returned function is called. A location loading again forgets the
- * shutdown recorded for it, so a dismissal there is not mistaken for that shutdown. One recorded for
- * every location is left alone, since a dismissal held in another location may still need it; it
- * ages out with the grace.
+ * Adds an instance's ports to `loaded`, which other copies tell cut-off questions through, until the
+ * returned function is called. A location loading again forgets the shutdown recorded for it alone.
  */
 export function joinRelay(ports) {
     shared.loaded.add(ports);
@@ -72,9 +65,8 @@ export function formShown(event) {
     shared.shown.delete(key);
 }
 /**
- * Called when an event stream may have missed forms being shown: every call still waiting for its
- * form is taken as shown. One still waiting for its permission check is relayed early, which is the
- * lesser harm.
+ * Called when an event stream may have missed forms shown: every call still waiting for its form is
+ * taken as shown; one still waiting for its permission check is relayed early, the lesser harm.
  */
 export function formsMayHaveBeenMissed() {
     for (const shown of shared.shown.values())
@@ -82,9 +74,8 @@ export function formsMayHaveBeenMissed() {
     shared.shown.clear();
 }
 /**
- * Called when an instance starts following OpenCode's events. Every instance is sent every event,
- * so a form shown is missed only while none follows them; then the calls waiting are released, and
- * true is returned, for the caller to release them again on its first event, once it is connected.
+ * Called when an instance starts following OpenCode's events: a shown form is missed only while none
+ * follows, so waiting calls are released; true tells the caller to release again on its first event.
  */
 export function eventsFollowed() {
     const missed = shared.following === 0 && shared.followed;

package/dist/question/pure.d.ts

@@ -28,11 +28,10 @@ export type CallExit = Exit.Exit<{
 /** How a relayed call that the top session did not answer was settled in the asking session. */
 export declare function settledIn(exit: CallExit): Elsewhere;
 /**
- * Orders strings by their UTF-16 code units, the default sort's order, stated. The order is never
- * shown; it only has to come out the same on both sides of a comparison, which a locale-aware
- * compare would not promise: it can rank two different labels as equal and leave them as listed.
+ * Orders strings by UTF-16 code units, the default sort's order, stated: it only has to come out the
+ * same on both sides of a comparison; a locale-aware compare may rank two different labels as equal.
  */
-export declare function byCodeUnit(a: string, b: string): 1 | 0 | -1;
+export declare function byCodeUnit(a: string, b: string): 0 | 1 | -1;
 export declare const choices: (questions: ReadonlyArray<Prompt>) => string;
 export declare const wording: (questions: ReadonlyArray<Prompt>) => string;
 /** The result of a linked call withdrawn because its question was settled without it. */

package/dist/question/pure.js

@@ -40,9 +40,8 @@ export function settledIn(exit) {
     return { by: "failed", error: String(Cause.squash(exit.cause)) };
 }
 /**
- * Orders strings by their UTF-16 code units, the default sort's order, stated. The order is never
- * shown; it only has to come out the same on both sides of a comparison, which a locale-aware
- * compare would not promise: it can rank two different labels as equal and leave them as listed.
+ * Orders strings by UTF-16 code units, the default sort's order, stated: it only has to come out the
+ * same on both sides of a comparison; a locale-aware compare may rank two different labels as equal.
  */
 export function byCodeUnit(a, b) {
     if (a === b)

package/dist/question/relay.js

@@ -8,8 +8,7 @@ import { background, run, within } from "./runtime.js";
 import { anyLoaded, isPassing, keyOf, QUESTION_TOOL, shared, storedOf } from "./shared.js";
 /**
  * Tells the top session about a question its closing location cut off, after the closing grace of
- * `ports` (the instance whose call was cut off), through an instance still loaded then, if any (any will do: a notice reaches a session in any location).
- * Without one, the next load tells it.
+ * `ports`, through any instance still loaded then; without one, the next load tells it.
  */
 function tellLater(ports, question) {
     const tellNow = Effect.suspend(() => {
@@ -44,9 +43,8 @@ const settle = (ports, question, exit, loaded) => Effect.gen(function* () {
     // A dismissal is held from now, alongside the wait below, so the grace is not spent waiting.
     const dismissed = Exit.isFailure(exit) && isDismissal(exit.cause);
     const held = dismissed && !unloaded ? yield* Effect.forkChild(closingSoon(ports, loaded, question.directory), { startImmediately: true }) : undefined;
-    // Telling the top session first, so what follows does not overtake the notice or come before it
-    // is stored; for a while only, so a notice that never returns does not hold everything else up.
-    // `told` is false when the top session was not told, or not yet.
+    // The top session is told first, for a while only, so what follows neither overtakes the notice
+    // nor waits forever on one that never returns; `told` is false when it was not told, or not yet.
     const told = (yield* within(question.relaying, ports.timing.relayWaitMs)) === true;
     // Answered by the top session.
     if (Exit.isSuccess(exit) && exit.value.by === "top") {
@@ -58,15 +56,8 @@ const settle = (ports, question, exit, loaded) => Effect.gen(function* () {
     if (shared.questions.get(question.requestID) !== question) {
         return yield* Effect.promise(() => forget(ports, question));
     }
-    // Cut off: the turn was stopped, or OpenCode is closing the location, which withdraws every open
-    // form there as if the person had dismissed it (on a server shutdown, say), before unloading the
-    // plugin there (since 2.0.22) or after (the beta). So a dismissal is held for a moment, to see
-    // whether the location's shutdown or this instance's unload follows it. The question stays,
-    // answered by message from now on; a top session already asking the person passes their answer
-    // on that way. A closing location is not told now: the next load tells it, in this process or
-    // after a restart, or an instance still loaded does, a little later, when the process is still
-    // running then. The unload is looked at again here: it may have come during the wait above, after
-    // a held dismissal had already been taken for the person's.
+    // Cut off: the turn was stopped, or the closing location withdrew its forms as if dismissed, so a
+    // dismissal is held for a following shutdown or unload; the question stays, answered by message.
     const closing = unloaded || !loaded() || (held !== undefined && (yield* Fiber.join(held)));
     if (Exit.isFailure(exit) && (closing || (!dismissed && Exit.hasInterrupts(exit))))
         return closing ? tellLater(ports, question) : yield* Effect.promise(() => stopped(ports, question));
@@ -103,9 +94,8 @@ function startSettling(ports, question, exit, loaded) {
     });
 }
 /**
- * The question call of a session started with courier_spawn: once its form is shown, the session at
- * the top is told, and whichever answer comes first ends the call, the other side's question being
- * withdrawn. Other sessions' calls run unchanged.
+ * A spawned session's question call: once its form is shown the top session is told, and whichever
+ * answer comes first ends the call, the other side's question withdrawn. Other calls run unchanged.
  */
 function asking(ports, directory, original) {
     return (input, context) => Effect.gen(function* () {
@@ -180,9 +170,8 @@ function asking(ports, directory, original) {
     });
 }
 /**
- * The waiting question a top session's call asks again, the oldest if several: the same questions
- * with the same choices, in any order. Matching choices alone are not enough, or an unrelated
- * yes-or-no question of the top session would answer a child's.
+ * The waiting question a top session's call asks again, the oldest if several: the same question with
+ * the same choices, in any order. Choices alone would let an unrelated yes-or-no answer a child's.
  */
 function linkFor(sessionID, questions) {
     const asked = { choices: choices(questions), wording: wording(questions) };
@@ -195,9 +184,8 @@ function linkFor(sessionID, questions) {
         .sort((a, b) => a.askedAt - b.askedAt)[0];
 }
 /**
- * The result of a top session's question call that no waiting question was linked to: when one
- * waits with the same choices, reworded or asked before that session asked, it says how to pass
- * the answers on.
+ * The result of a top session's question call that no waiting question was linked to: when one waits
+ * with the same choices, reworded or asked earlier, it says how to pass the answers on.
  */
 function unlinkedResult(result, sessionID, questions) {
     if (typeof result.content !== "string")
@@ -209,10 +197,8 @@ function unlinkedResult(result, sessionID, questions) {
     return { ...result, content: `${result.content}\n${unlinkedNote(similar)}` };
 }
 /**
- * After a linked call failed, its location still loaded: a dismissal by the person, unless the
- * location is closing (see settle), dismisses the question they were asked for too, or is logged
- * when the question was answered meanwhile; a call stopped while the asking call was cut off as
- * well tells the top session, which nobody has told yet.
+ * After a linked call failed with its location still loaded: a dismissal by the person dismisses the
+ * child's question too, or is logged if answered meanwhile; a stop while cut off tells the top.
  */
 const linkedCallFailed = (ports, linked, cause, loaded, directory) => Effect.gen(function* () {
     if (isDismissal(cause)) {

package/dist/question/runtime.d.ts

@@ -1,8 +1,7 @@
 import { Clock, Effect } from "effect";
 /**
- * Runs an effect of the relay in a fiber of its own, by the relay's clock, which is the clock of
- * its ports (`ports.now`): the promise settles as the effect ends, and is rejected if it fails or
- * is interrupted. Interrupting what waits on the promise does not stop the fiber.
+ * Runs a relay effect in its own fiber by the relay's clock (`ports.now`): the promise settles as the
+ * effect ends, rejecting on failure or interruption; interrupting the waiter does not stop the fiber.
  */
 export declare function run<A, E>(effect: Effect.Effect<A, E>): Promise<A>;
 /**

package/dist/question/runtime.js

@@ -38,9 +38,8 @@ let scope = Scope.makeUnsafe();
  */
 const start = (effect) => Effect.runFork(Effect.provideService(effect, Clock.Clock, clock)).pipe(Fiber.runIn(scope));
 /**
- * Runs an effect of the relay in a fiber of its own, by the relay's clock, which is the clock of
- * its ports (`ports.now`): the promise settles as the effect ends, and is rejected if it fails or
- * is interrupted. Interrupting what waits on the promise does not stop the fiber.
+ * Runs a relay effect in its own fiber by the relay's clock (`ports.now`): the promise settles as the
+ * effect ends, rejecting on failure or interruption; interrupting the waiter does not stop the fiber.
  */
 export function run(effect) {
     return Effect.runPromise(Fiber.join(start(effect)));

package/dist/relay.d.ts

@@ -45,10 +45,8 @@ export declare function listEverywhere<D extends Pick<Permissions, "list">>(perm
     requests: import("@opencode/client").PermissionRequest[];
 })[]>;
 /**
- * Answers a permission request of a session started, directly or through others, from the
- * caller, which must be the session at the top: requests go there, to the person, so a session
- * started with courier_spawn cannot approve what its own children ask. `answered` is false when
- * no location loaded in this server holds the request, which may then wait in another server.
+ * Answers a permission request of a session started, directly or through others, from the caller,
+ * which must be the top session; `answered` is false when no location loaded here holds the request.
  */
 export declare function answer(ports: AnswerPorts, waiting: Waiting, callerID: string, input: AnswerInput): Promise<PermissionAnswered>;
 /** The requests a session waits on, in whichever location holds them, for courier_status. */

package/dist/relay.js

@@ -19,10 +19,8 @@ async function locate(ports, sessionID, requestID) {
     return undefined;
 }
 /**
- * Answers a permission request of a session started, directly or through others, from the
- * caller, which must be the session at the top: requests go there, to the person, so a session
- * started with courier_spawn cannot approve what its own children ask. `answered` is false when
- * no location loaded in this server holds the request, which may then wait in another server.
+ * Answers a permission request of a session started, directly or through others, from the caller,
+ * which must be the top session; `answered` is false when no location loaded here holds the request.
  */
 export async function answer(ports, waiting, callerID, input) {
     const reply = input.reply;

package/dist/report.d.ts

@@ -0,0 +1,48 @@
+import { type Status } from "./notices.js";
+import type { Storage } from "./storage.js";
+export declare const promptKey: (sessionID: string) => string;
+export declare const settledKey: (sessionID: string) => string;
+export declare const progressKey: (sessionID: string) => string;
+export declare const toldKey: (sessionID: string) => string;
+export declare const stoppedKey: (sessionID: string) => string;
+/** How a session's wait for a report ended: it reported to its parent, or its turn failed or was interrupted. */
+export type Settled = "report" | "failed" | "interrupted";
+/**
+ * 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 declare function prompted(storage: Pick<Storage, "get" | "set">, sessionID: string, at: number): Promise<void>;
+/**
+ * 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 declare function settled(storage: Pick<Storage, "get" | "set">, sessionID: string, by: Settled, at: number, status?: Status): Promise<void>;
+/** Notes that a spawned session messaged its parent without a status at `at`, which is progress, not its report. */
+export declare function progressed(storage: Pick<Storage, "get" | "set">, sessionID: string, at: number): Promise<void>;
+/** 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 declare function told(storage: Pick<Storage, "get" | "set">, sessionID: string, at: number): Promise<void>;
+/** 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 declare function untold(storage: Pick<Storage, "get" | "remove">, sessionID: string, at: number): Promise<void>;
+/** Notes that courier_stop stopped a spawned session at `at`, so the failure and silent-end notices stay quiet for it. */
+export declare function stopped(storage: Pick<Storage, "set">, sessionID: string, at: number): Promise<void>;
+/** Whether courier_stop stopped a session after its last prompt, or with none noted, at all. */
+export declare function stoppedSincePrompt(storage: Pick<Storage, "get">, sessionID: string): Promise<boolean>;
+/** The status of a spawned session's last report to its parent, if it has reported with one. */
+export declare function lastStatus(storage: Pick<Storage, "get">, sessionID: string): Promise<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 declare function reportOf(storage: Pick<Storage, "get">, sessionID: string): Promise<{
+    prompt: number;
+    owes: boolean;
+    progressed: boolean;
+    ended: boolean;
+} | undefined>;
+/**
+ * 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 declare function awaited(storage: Pick<Storage, "get">, sessionID: string): Promise<boolean>;
+/** Drops what is kept about a session, with its roster entry. */
+export declare function forgetReport(storage: Pick<Storage, "remove">, sessionID: string): Promise<void>;

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,11 +18,14 @@ 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 session
- * at the top, which courier_spawn did not start, last. Its roster entry is under the first, and each
- * of the others is the parent of the one before it.
+ * 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>;
@@ -36,10 +39,12 @@ export declare function reverseKey(sessionID: string): string;
  */
 export declare function record(storage: RosterStorage, entry: RosterEntry): Promise<void>;
 /**
- * Removes a child's roster entry and its reverse key. Only the entry's removal can fail it: a
- * reverse key left behind leads nowhere, and the next load drops it.
+ * 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): Promise<void>;
+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. */
@@ -48,19 +53,28 @@ 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. */
@@ -73,9 +87,7 @@ export declare function current(storage: RosterStorage, parentID: string, now: n
  */
 export declare function pruneExpired(storage: RosterStorage, now: number, exists?: Exists): Promise<void>;
 /**
- * Writes the reverse keys missing for the given entries, or naming another parent, all of the roster, such as those an older
- * copy of the plugin recorded, and drops the reverse keys whose entry is gone, such as those of an
- * entry an older copy removed. Keys that lead to their entry are left as they are, so running it
- * again changes nothing.
+ * 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>;