opencode-courier 0.2.3 → 0.3.0

package/dist/notices.d.ts

@@ -1,25 +1,88 @@
 /** Closes a tool result after which the caller most likely has nothing left to do. */
 export declare const END_TURN = "If nothing else is left to do now, end your turn by replying without calling more tools.";
-export declare function childBrief(parentID: string, task: string): string;
+/** 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;
+}
+/** The statuses a report carries: the task is done, partly done, waits on the parent, or failed. */
+export declare const STATUSES: readonly ["done", "partial", "blocked", "failed"];
+export type Status = (typeof STATUSES)[number];
+export declare const isStatus: (value: unknown) => value is Status;
+/** The one line a session states its split decision in, so a transcript tells a decision from one never made. */
+export declare const SPLIT_LINE = "split: no, because \u2026; considered: <the parts you weighed> or split: <n> parts: \u2026 (one phrase per part)";
+/** The branch an isolated child commits its work on, and names in the `branch` of its report. */
+export declare const childBranch: (sessionID: string) => string;
+/** What a spawned session at `depth` is told; `depth` 1 is a child of a session nobody spawned. `branch` is for an isolated one. */
+export declare function childBrief(parentID: string, task: string, depth: number, limits: Limits, branch?: string): string;
+/** How every part the context hook adds begins, so a second copy of the plugin does not add its own. */
+export declare const ROLE_PREFIX = "opencode-courier role:";
+/**
+ * The system part naming a session's place in its tree: `depth` 0 for a session nobody spawned that
+ * has started one, `null` for one that has started none, which is pointed to the skill. The same on every request.
+ */
+export declare function rolePart(depth: number | null, limits: Limits): string;
+export declare const SKILL_ID = "courier-orchestrate";
+/** Why a model loads the skill, listed with every session's available skills. */
+export declare const SKILL_DESCRIPTION: string;
+/** The skill's text; it names no limits, which the role part and the brief give for the session's own tree. */
+export declare const SKILL_CONTENT: string;
+export declare const depthRefusal: (depth: number, maxDepth: number) => string;
+export declare const childrenRefusal: (running: number, maxChildren: number) => string;
+export declare const totalRefusal: (running: number, maxTotal: number) => string;
 export declare function envelope(from: string, message: string, attributes?: Record<string, string>): 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;
+    }>;
+}
+/**
+ * The body of a report: its text, then the artifacts in a fixed layout, the same for every report,
+ * so a parent finds the branch, the commits, the files and the checks without reading prose.
+ */
+export declare function reportBody(message: string, artifacts: Artifacts | undefined): string;
 export declare function spawnText(child: {
     readonly sessionID: string;
     readonly directory: string;
+    readonly group?: string;
     readonly rosterError?: string;
+    readonly groupError?: string;
+    readonly fromParent?: boolean;
+    readonly uncommitted?: boolean;
 }): string;
-export declare const sendText: (sessionID: string) => string;
+/** A report held with its group: which group, and how many of its members have reported so far, when that could be read. */
+export interface Held {
+    readonly group: string;
+    readonly reported?: number;
+    readonly members?: number;
+}
+/**
+ * What courier_send did; `report` says whether the message was noted as the sender's report to the session
+ * that started it, and `held` that it was held with the sender's group rather than delivered, with no `messageID`.
+ */
+export interface Sent {
+    readonly messageID?: string;
+    readonly status?: Status;
+    readonly report?: boolean;
+    readonly held?: Held;
+}
+/** courier_send's result: for a message to the session that started the sender, whether it was its report. */
+export declare function sendText(sessionID: string, sent?: Pick<Sent, "status" | "report" | "held">): string;
 /** courier_status's result: the session's state, as JSON. */
 export declare const statusText: (status: unknown) => string;
 export declare const childrenText: (listed: ReadonlyArray<unknown>) => string;
-/** What courier_cleanup did: removed the worktree, found it gone, or kept it and why. */
+/** What courier_cleanup did: removed the worktree, found it gone, kept it and why, or forgot a child with none; `group`, one it dropped the child from. */
 export type CleanupResult = {
     readonly sessionID: string;
     readonly directory: string;
-    readonly outcome: "removed";
-} | {
-    readonly sessionID: string;
-    readonly directory: string;
-    readonly outcome: "gone";
+    readonly outcome: "removed" | "gone" | "forgotten";
+    readonly group?: string;
 } | {
     readonly sessionID: string;
     readonly directory: string;
@@ -29,6 +92,29 @@ export type CleanupResult = {
     readonly commits: readonly string[];
 };
 export declare function cleanupText(result: CleanupResult): string;
+/** courier_tree's result: the sessions under a session, drawn depth first, as JSON. */
+export declare function treeText(tree: {
+    readonly sessions: ReadonlyArray<unknown>;
+    readonly truncated?: number;
+}): string;
+/** What courier_stop did to each session, and to the messages and worktrees. */
+export declare function stopText(result: {
+    readonly sessionID: string;
+    readonly stopped: ReadonlyArray<{
+        readonly sessionID: string;
+        readonly outcome: string;
+        readonly error?: string;
+    }>;
+    readonly cancelled: ReadonlyArray<string>;
+    readonly cleanup?: ReadonlyArray<CleanupResult | {
+        readonly sessionID: string;
+        readonly outcome: "failed";
+        readonly error: string;
+    }>;
+    readonly told?: string;
+}): string;
+/** What the parent of a stopped session is told when the stop was ordered by a session above both. */
+export declare const stoppedNotice: (title: string, by: string) => string;
 /** Why a worktree in this state must be kept, or undefined when removing it loses nothing. */
 export declare function keepReason(state: {
     readonly changes: readonly string[];
@@ -40,9 +126,8 @@ export declare function keepReason(state: {
  */
 export type AnswerResult = PermissionAnswered | QuestionAnswered;
 /**
- * What answering a permission request did; `answered` is false when no location loaded in this
- * server held the request: it was answered, the session stopped waiting, or it waits in another
- * OpenCode server on the same data directory.
+ * What answering a permission request did; `answered` is false when no location loaded here held the
+ * request: answered already, no longer waited for, or waiting in another server on the same data dir.
  */
 export interface PermissionAnswered {
     readonly sessionID: string;
@@ -78,7 +163,33 @@ export interface ExecutionError {
     readonly message: string;
     readonly status?: number;
 }
-export declare function failureNotice(title: string, error: ExecutionError): string;
+export declare function failureNotice(title: string, error: ExecutionError, group?: string): string;
+/**
+ * What the parent is told when a session it started ends its turn without a report to it;
+ * `progressed` when it messaged the parent without a status since its last prompt.
+ */
+export declare function silentNotice(title: string, lastText: string | undefined, progressed?: boolean, group?: string): 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";
+}
+/**
+ * What the parent gets when a group it named is released: every report, with its status, text and artifacts in
+ * `reportBody`'s layout, and the members that left without one, in the order they joined.
+ */
+export declare function groupNotice(group: string, reports: ReadonlyArray<HeldReport & {
+    readonly sessionID: string;
+    readonly title: string;
+}>, left?: ReadonlyArray<LeftMember>): string;
 /** The answers to a permission request, as OpenCode's own prompt offers them. */
 export declare const REPLIES: readonly ["once", "always", "reject"];
 export type Reply = (typeof REPLIES)[number];
@@ -215,9 +326,8 @@ export declare function unlinkedNote(waiting: ReadonlyArray<Pick<Asked, "session
 /** The result of a linked call withdrawn because its question was settled without it. */
 export declare function withdrawnText(linked: Asked, how: Withdrawal): string;
 /**
- * What a linked call adds to the person's answers about passing them on: `passed` is what passing
- * them on gave ("result", "message", or undefined when it no longer waited), or the error as
- * `error: <message>`.
+ * What a linked call adds to the person's answers about passing them on: `passed` is "result",
+ * "message", undefined when it no longer waited, or the error as `error: <message>`.
  */
 export declare function passedNote(linked: Asked, passed: string | undefined): string;
 export declare function clipText(text: string, max?: number): string;

package/dist/notices.js

@@ -1,53 +1,267 @@
 /**
- * Every model-facing text the plugin builds: tool results, the child brief, and the notices sessions
- * are woken with. With the tool descriptions in `tools.ts`, it is the plugin's real user interface;
- * `test/notices.test.ts` snapshots both, so a wording change shows up as a snapshot diff (and calls
- * for the real-model rerun CLAUDE.md asks for). Plain error messages, thrown where the check is and
- * passed on through `describeFailure`, are the exception: they stay with their checks, unsnapshotted.
- *
- * Pure functions on plain data; it imports nothing of the plugin's but `json.ts`, so any module
- * can use it without an import cycle.
+ * Every model-facing text the plugin builds; `test/notices.test.ts` snapshots them with the tool
+ * descriptions. Pure functions on plain data, importing nothing of the plugin's but `json.ts`.
  */
 import { num, obj, str } from "./json.js";
 // The envelope and the child brief.
 /** Closes a tool result after which the caller most likely has nothing left to do. */
 export const END_TURN = "If nothing else is left to do now, end your turn by replying without calling more tools.";
-export function childBrief(parentID, task) {
+/** The statuses a report carries: the task is done, partly done, waits on the parent, or failed. */
+export const STATUSES = ["done", "partial", "blocked", "failed"];
+export const isStatus = (value) => typeof value === "string" && STATUSES.includes(value);
+/** How a text names the statuses a report may carry. */
+const STATUS_LIST = `${STATUSES.slice(0, -1).join(", ")} or ${STATUSES.at(-1)}`;
+/** The one line a session states its split decision in, so a transcript tells a decision from one never made. */
+export const SPLIT_LINE = "split: no, because …; considered: <the parts you weighed> or split: <n> parts: … (one phrase per part)";
+/** The branch an isolated child commits its work on, and names in the `branch` of its report. */
+export const childBranch = (sessionID) => `courier/${sessionID}`;
+/** What a spawned session at `depth` is told; `depth` 1 is a child of a session nobody spawned. `branch` is for an isolated one. */
+export function childBrief(parentID, task, depth, limits, branch) {
     return [
         `You were started by session ${parentID} through opencode-courier.`,
         "",
-        `When you finish, or need a decision you cannot make yourself, call courier_send with sessionID "${parentID}" and a short report.`,
-        "That message wakes the parent. It is the only way the parent hears from you, so do not end without sending it.",
+        `When you finish, send exactly one report: call courier_send with sessionID "${parentID}", a short account of what you did and ` +
+            "status done, partial (say what is left and why) or failed (say what went wrong). Add artifacts where there are any: " +
+            "branch, commits, files, checks (each command you ran and its result).",
+        "If you need a decision from the session that started you, which you cannot make yourself, send status blocked with a " +
+            "concrete ask, then end your turn and wait for its answer; never end quietly.",
+        "A report with a status wakes the parent and is the only way it hears from you, so do not end without sending one. " +
+            "A message without a status is progress, not your report: if you end your turn without a report, the parent is told so.",
         "If you need the person to decide something, use your question tool; it reaches them through the session that started you.",
         "",
+        ...(branch ? [...isolationRule(branch, depth < limits.maxDepth), ""] : []),
+        ...splitRule(parentID, depth, limits),
+        "",
         "Task:",
         task,
     ].join("\n");
 }
+function isolationRule(branch, mayPass) {
+    return [
+        "You work in a git worktree of your own, on a detached HEAD. Commit your work on the branch " +
+            `${branch}: create it first (git switch -c ${branch}), and name it in the branch of your report's artifacts, so the ` +
+            "session that started you can merge it. Uncommitted work is not in your report.",
+        ...(mayPass
+            ? [
+                `If you split your task and start a session with isolate: true, commit first: its worktree starts from your current HEAD, ` +
+                    "not from your uncommitted changes. Merge each branch it reports into yours before you report.",
+            ]
+            : []),
+    ];
+}
+function splitRule(parentID, depth, limits) {
+    if (depth >= limits.maxDepth)
+        return [`You are at depth ${depth}, the deepest the session tree goes, so you cannot start sessions: do the task yourself.`];
+    return [
+        `You are at depth ${depth} of a session tree that goes at most ${limits.maxDepth} deep. Split your task or do it yourself:`,
+        "- Split it when it has 2 or more independent parts, each substantial and touching separate files or areas: start one " +
+            `session per part with courier_spawn, at most ${limits.maxChildren} of yours running at once and ${limits.maxTotal} in the whole tree.`,
+        "- Do it yourself when it is small, sequential or tightly coupled. Never start exactly one session.",
+        `- Say which in one line of your reply: ${SPLIT_LINE}.`,
+        "- If you split, you orchestrate: end your turn while they work, check and integrate each part yourself when it " +
+            `reports (never hand that checking to another session), then send ${parentID} one combined report.`,
+    ];
+}
+/** How every part the context hook adds begins, so a second copy of the plugin does not add its own. */
+export const ROLE_PREFIX = "opencode-courier role:";
+/**
+ * The system part naming a session's place in its tree: `depth` 0 for a session nobody spawned that
+ * has started one, `null` for one that has started none, which is pointed to the skill. The same on every request.
+ */
+export function rolePart(depth, limits) {
+    const { maxDepth, maxChildren, maxTotal } = limits;
+    const budget = `At most ${maxChildren} of the sessions you start run at once, and ${maxTotal} in the whole tree.`;
+    if (depth === null)
+        return (`${ROLE_PREFIX} root, no sessions started yet. Before a task that touches several files or areas, load the ` +
+            `${SKILL_ID} skill and decide whether to split it across sessions (doing it yourself is fine), and say ` +
+            `which in one line of your reply: ${SPLIT_LINE}`);
+    if (depth === 0)
+        return (`${ROLE_PREFIX} root orchestrator. You started sessions with courier_spawn, and they may start their own, ` +
+            `down to ${maxDepth} levels below you. ${budget} Check and integrate what each one reports yourself.`);
+    if (depth < maxDepth)
+        return (`${ROLE_PREFIX} sub-orchestrator, at depth ${depth} of at most ${maxDepth}. Split your task with courier_spawn or ` +
+            `do it yourself, as your brief says; sessions can be started ${count(maxDepth - depth, "level")} below you. ${budget}`);
+    return (`${ROLE_PREFIX} leaf, at depth ${depth}, the deepest the session tree goes. You cannot start sessions: do your ` +
+        "task yourself and report with courier_send to the session that started you.");
+}
+// The courier-orchestrate skill: the playbook a session loads with its skill tool.
+export const SKILL_ID = "courier-orchestrate";
+/** Why a model loads the skill, listed with every session's available skills. */
+export const SKILL_DESCRIPTION = "Load at the start of any implementation task that may have independent parts, or when a session started you, to " +
+    "decide whether to split it across OpenCode sessions with courier_spawn and state the decision, and how: plan the " +
+    "parts, start them, end your turn, read the reports, verify the work, integrate it and report upward, and what to do " +
+    "when a part goes wrong.";
+/** The skill's text; it names no limits, which the role part and the brief give for the session's own tree. */
+export const SKILL_CONTENT = [
+    "How to split a task across OpenCode sessions with opencode-courier, and bring the results back up. Your brief, or the " +
+        "opencode-courier role line in your system prompt, names your depth in the session tree and its limits.",
+    "",
+    "1. Decide: split or do. Split when the task has 2 or more independent, substantial parts touching separate files or " +
+        "areas; do it yourself when it is small, sequential or tightly coupled. Never start exactly one session. " +
+        "An implementation task with one tightly coupled core usually still has independent parts: its e2e scenario, its " +
+        "documentation, sometimes a second test file, and a review of the core by a session with fresh context, which reads the " +
+        "committed diff against the task and the repository's rules and reports its findings (isolate: false, it edits nothing). " +
+        "Weigh each of them: do the core yourself first and commit it, so that the names and texts the other parts depend on are " +
+        "fixed, then, if 2 or more remain, start one session per remaining part, in one group. A part that is itself big and " +
+        "divisible is split again by the session that gets it; at the deepest level a session does its part itself. " +
+        `Say which in one line of your reply, before you start: ${SPLIT_LINE}, so that a reasoned decision to do it ` +
+        "yourself can be told from one never made.",
+    "2. Plan the parts so that no two edit the same files. Write each task so the session can do it without you: what to " +
+        "produce and where, how to check it, what to report. Say if it may split its part further.",
+    "3. Start them: one courier_spawn per part, all with the same group name, so you are woken once with every report; " +
+        "isolate: true for each part that edits files in parallel with another (commit your own work first if you are isolated " +
+        "yourself). For long work, courier_later a check-in for yourself, and courier_cancel it when the reports arrive.",
+    "4. End your turn: reply without calling more tools. Do not poll with courier_status, courier_children, courier_tree or " +
+        "sleep. The group's reports, a blocked report, a question, a permission request, a failed turn or a silent end each start " +
+        "a new turn for you.",
+    "5. Read each report by its status and its artifacts (branch, commits, files, checks). done: verify it. partial: what is " +
+        "left and why; have the session finish it with a courier_send, or do it yourself. blocked: make the decision it asks for " +
+        "and send it with courier_send; if only the person can make it, ask them with your question tool and pass the answer on. " +
+        "failed: read the error; message the session to try again, start a replacement, or carry on without it.",
+    "6. Verify first-hand: open the files, run the checks. Never hand the checking to another session: a review session's " +
+        "findings are a report to act on, and running the checks is still yours. Run checks through " +
+        "the project's scripts (bun run <script>, npm run <script>), not ./node_modules/.bin/<tool>, so that one permission " +
+        "rule covers them: your own permission prompts are relayed nowhere, and each one stalls the whole tree.",
+    "7. Integrate: merge each reported branch into your own checkout (git merge courier/<session>), resolve conflicts " +
+        "yourself, run the checks once more, then courier_cleanup the isolated sessions you are done with.",
+    "8. Report upward if a session started you: one courier_send to it, with one status for the whole (done only when every " +
+        "part is verified and integrated; partial, blocked or failed otherwise) and the artifacts. At the top, reply to the person.",
+    "",
+    "When a part goes wrong:",
+    "- A failed turn (failed=\"...\") or a silent end (ended=\"without-report\", quoting the session's last reply): message " +
+        "the session with courier_send to carry on, to report, or to try again; or start a replacement. Until it reports, it " +
+        "counts toward the limits.",
+    "- A refusal from courier_spawn naming maxDepth, maxChildren or maxTotal: do that part yourself, or end your turn and " +
+        "start it once a report has arrived. Do not retry it in a loop.",
+    "- Lost track, after a compaction or a restart: one courier_tree shows every session under you with its depth, its " +
+        "parent and whether it still owes a report; one look, not a loop.",
+    "- A subtree that went wrong or is no longer needed: courier_stop its top session; everything under it is stopped too, " +
+        "and nothing in it reports back. cleanup: true removes their worktrees.",
+].join("\n");
+// courier_spawn's refusals, one per limit.
+export const depthRefusal = (depth, maxDepth) => `Not started: this session is at depth ${depth} of its session tree, and the tree goes at most ${maxDepth} deep ` +
+    "(maxDepth), so it cannot start sessions. Do the task yourself, and report with courier_send.";
+/** How a refusal names sessions that count against a limit: those running, and those that have not reported yet. */
+const live = (n) => (n === 1 ? "is running or has not reported yet" : "are running or have not reported yet");
+export const childrenRefusal = (running, maxChildren) => `Not started: ${count(running, "session")} you started ${live(running)}, the most allowed at once ` +
+    `(maxChildren ${maxChildren}). Do this part yourself, or end your turn and start it once one of them has reported.`;
+export const totalRefusal = (running, maxTotal) => `Not started: ${count(running, "session")} in this session tree ${live(running)}, the most allowed at once ` +
+    `(maxTotal ${maxTotal}). Do this part yourself, or end your turn and try again once a report has arrived.`;
 export function envelope(from, message, attributes = {}) {
     const extra = Object.entries(attributes)
         .map(([name, value]) => ` ${name}="${value}"`)
         .join("");
     return `<courier from="${from}"${extra}>\n${message}\n</courier>`;
 }
+/** The strings of a list given as artifacts, whatever else the model put in it. */
+const strings = (value) => (Array.isArray(value) ? value.flatMap((item) => (typeof item === "string" ? [item.trim()] : [])) : []).filter(Boolean);
+/** A list's line in the artifacts block, or none when it is empty. */
+const listed = (name, items) => (items.length ? [`- ${name}: ${items.join(", ")}`] : []);
+/**
+ * The body of a report: its text, then the artifacts in a fixed layout, the same for every report,
+ * so a parent finds the branch, the commits, the files and the checks without reading prose.
+ */
+export function reportBody(message, artifacts) {
+    const given = obj(artifacts);
+    const checks = (Array.isArray(given.checks) ? given.checks : []).flatMap((check) => {
+        const command = str(obj(check).command)?.trim();
+        return command ? [`  - ${command}: ${str(obj(check).result)?.trim() || "(no result given)"}`] : [];
+    });
+    const lines = [
+        ...listed("branch", strings([given.branch])),
+        ...listed("commits", strings(given.commits)),
+        ...listed("files", strings(given.files)),
+        ...(checks.length ? ["- checks:", ...checks] : []),
+    ];
+    return lines.length ? [message, "", "Artifacts:", ...lines].join("\n") : message;
+}
 // Tool results.
 export function spawnText(child) {
-    const warning = child.rosterError ? ` It is not on your courier_children list: ${child.rosterError}` : "";
-    return (`Started session ${child.sessionID} in ${child.directory}. It will report back with courier_send, which ` +
-        "starts a new turn for you. Once you have started every session you need, end your turn: reply without " +
-        `calling more tools. That does not drop the task; you carry on with it when the reports arrive.${warning}`);
+    const warning = (child.fromParent ? " Its worktree starts from the commit your own worktree is on." : "") +
+        (child.uncommitted
+            ? " Your worktree has uncommitted changes, which it does not see: commit them and tell it, or send them to it, if it needs them."
+            : "") +
+        (child.rosterError ? ` It is not on your courier_children list: ${child.rosterError}` : "") +
+        (child.groupError ? ` It is in no group, so its report comes on its own: ${child.groupError}` : "");
+    const reports = child.group
+        ? `Its report is held with group "${child.group}": once every session you started in that group has reported and your ` +
+            "turn has ended, you get their reports in one message, which starts a new turn for you; a blocked report, a question " +
+            "or a failed turn still reaches you at once."
+        : "It will report back with courier_send, which starts a new turn for you.";
+    return (`Started session ${child.sessionID} in ${child.directory}. ${reports} Once you have started every session you need, ` +
+        `end your turn: reply without calling more tools. That does not drop the task; you carry on with it when the reports arrive.${warning}`);
+}
+/** courier_send's result: for a message to the session that started the sender, whether it was its report. */
+export function sendText(sessionID, sent = {}) {
+    const status = sent.status ? `, status ${sent.status}` : "";
+    if (sent.held) {
+        const { group, reported, members } = sent.held;
+        const counted = reported !== undefined && members !== undefined;
+        let when = `once ${sessionID}'s turn has ended, yours being the last.`;
+        if (!counted || reported < members) {
+            const have = counted ? ` (${reported} of ${members} have)` : "";
+            when = `once every member of the group has reported${have}. Nothing more is needed from you for it.`;
+        }
+        return `Recorded as your report${status}. It is held with group "${group}" and goes to ${sessionID} in one message with the group's other reports, ${when} ${END_TURN}`;
+    }
+    if (sent.report === true)
+        return `Delivered to ${sessionID} as your report${status}. ${END_TURN}`;
+    if (sent.report === false)
+        return `Delivered to ${sessionID}. Without a status it is progress, not your report: when you finish, send one with status ${STATUS_LIST}.`;
+    return `Delivered to ${sessionID}.`;
 }
-export const sendText = (sessionID) => `Delivered to ${sessionID}.`;
 /** courier_status's result: the session's state, as JSON. */
 export const statusText = (status) => JSON.stringify(status, null, 2);
 export const childrenText = (listed) => listed.length ? JSON.stringify(listed, null, 2) : "No sessions started with courier_spawn.";
 export function cleanupText(result) {
-    if (result.outcome === "removed")
-        return `Removed the worktree ${result.directory} of ${result.sessionID}.`;
-    if (result.outcome === "gone")
-        return `The worktree ${result.directory} of ${result.sessionID} was already gone; dropped it from courier_children.`;
-    return `Kept the worktree ${result.directory} of ${result.sessionID}: it has ${result.reason}. Commit or branch what you want to keep, or call courier_cleanup again with force: true to discard it.`;
+    if (result.outcome === "kept")
+        return `Kept the worktree ${result.directory} of ${result.sessionID}: it has ${result.reason}. Commit or branch what you want to keep, or call courier_cleanup again with force: true to discard it.`;
+    const done = {
+        removed: `Removed the worktree ${result.directory} of ${result.sessionID}.`,
+        gone: `The worktree ${result.directory} of ${result.sessionID} was already gone; dropped it from courier_children.`,
+        forgotten: `${result.sessionID} ran in ${result.directory}, with no worktree of its own to remove; dropped it from courier_children.`,
+    }[result.outcome];
+    if (!result.group)
+        return done;
+    return `${done} Dropped it from group "${result.group}" without a report: the group's other reports reach you once they are in and your turn has ended, the message naming it, and a report it sends after all comes on its own.`;
+}
+/** courier_tree's result: the sessions under a session, drawn depth first, as JSON. */
+export function treeText(tree) {
+    if (!tree.sessions.length)
+        return "No sessions started with courier_spawn.";
+    const note = tree.truncated === undefined ? "" : `\nOnly the first ${tree.truncated} sessions are listed (maxTotal); courier_tree on one of them lists what is under it.`;
+    return JSON.stringify(tree, null, 2) + note;
+}
+/** What courier_stop did to each session, and to the messages and worktrees. */
+export function stopText(result) {
+    const interrupted = result.stopped.filter((one) => one.outcome === "interrupted").length;
+    const failed = result.stopped.filter((one) => one.outcome === "failed");
+    return [
+        `Stopped ${result.sessionID} and ${count(result.stopped.length - 1, "session")} under it, deepest first: ${interrupted} had a turn running and was interrupted, ` +
+            `${result.stopped.filter((one) => one.outcome === "idle" || one.outcome === "gone").length} did not run.`,
+        ...result.stopped.map((one) => `- ${one.sessionID}: ${one.outcome}${one.error ? " (" + one.error + ")" : ""}`),
+        ...(failed.length ? ["Those that failed may still run: try courier_stop again."] : []),
+        result.cancelled.length
+            ? `Cancelled ${count(result.cancelled.length, "scheduled message")}: ${result.cancelled.join(", ")}.`
+            : "No scheduled messages were pending for them.",
+        ...(result.told ? [`Told ${result.told}, which started ${result.sessionID}, that it was stopped.`] : []),
+        ...(result.cleanup ? worktreeLines(result.cleanup) : []),
+    ].join("\n");
 }
+const FORCE_HINT = " Commit or branch what you want to keep, or call courier_cleanup again with force: true to discard it.";
+/** courier_stop's lines on the worktrees it was asked to remove. */
+function worktreeLines(cleanup) {
+    if (!cleanup.length)
+        return ["None of them ran in a worktree of its own."];
+    return cleanup.map((one) => one.outcome === "failed"
+        ? `Worktree of ${one.sessionID}: not removed (${one.error}).`
+        : cleanupText(one).replace(FORCE_HINT, " Kept; courier_cleanup with force: true discards it."));
+}
+/** What the parent of a stopped session is told when the stop was ordered by a session above both. */
+export const stoppedNotice = (title, by) => [
+    `This session, "${title}", which you started with courier_spawn, was stopped by ${by}, a session above you, together with the sessions under it.`,
+    "It was not a failure and it will not report back. Carry on without it, or start a replacement if you still need what it was doing.",
+].join("\n");
 /** Why a worktree in this state must be kept, or undefined when removing it loses nothing. */
 export function keepReason(state) {
     const reasons = [
@@ -99,12 +313,78 @@ export function subscribeText(sessionID, topic, receiving) {
     return `Subscribed ${sessionID} to ${topic}.${note}`;
 }
 export const unsubscribeText = (sessionID, dropped) => dropped.length ? `Unsubscribed ${sessionID} from ${dropped.join(", ")}.` : `${sessionID} had no matching subscription.`;
-export function failureNotice(title, error) {
+export function failureNotice(title, error, group) {
     const status = error.status === undefined ? "" : `, status ${error.status}`;
     return [
         `This session, "${title}", which you started with courier_spawn, failed: ${error.message} (${error.type}${status}).`,
         "Its turn ended without finishing, so it will not report back on its own.",
         "Message it with courier_send to have it try again, start a replacement, or carry on without it.",
+        ...(group
+            ? [
+                `It is a member of group "${group}", which no longer waits for it: its other members' reports reach you once they have ` +
+                    "reported and your turn has ended, and if it reports after all before then, its report joins them.",
+            ]
+            : []),
+    ].join("\n");
+}
+/** Longest last reply a notice that a session ended its turn without reporting quotes. */
+const MAX_REPLY = 2000;
+/**
+ * What the parent is told when a session it started ends its turn without a report to it;
+ * `progressed` when it messaged the parent without a status since its last prompt.
+ */
+export function silentNotice(title, lastText, progressed = false, group) {
+    const reply = lastText?.trim();
+    return [
+        `This session, "${title}", which you started with courier_spawn, ended its turn without reporting back with courier_send, and does nothing more on its own.`,
+        ...(progressed
+            ? [`Its last message to you had no status, so it was progress, not its report: a report carries status ${STATUS_LIST}.`]
+            : []),
+        ...(reply ? ["Its last reply:", defuse(clipText(reply, MAX_REPLY))] : ["It ended without a reply."]),
+        "",
+        "Decide what it needs: message it with courier_send to have it carry on, or to report if its last reply is what you needed; or start a replacement.",
+        "Until it reports, it counts toward your limits on the sessions you run at once.",
+        ...(group
+            ? [
+                `It is a member of group "${group}", whose other reports are held until it reports: have it report, as above, so the group ` +
+                    "reaches you, or, if you no longer need its report, drop it with courier_cleanup, which releases the group without it.",
+            ]
+            : []),
+    ].join("\n");
+}
+/** How a release names each status among its reports: `2 done, 1 failed`. */
+function statusCounts(reports) {
+    return STATUSES.flatMap((status) => {
+        const n = reports.filter((report) => report.status === status).length;
+        return n ? [`${n} ${status}`] : [];
+    }).join(", ");
+}
+const LEFT_HOW = {
+    failed: "its turn failed",
+    interrupted: "its turn was interrupted",
+    deleted: "it was deleted",
+    dropped: "you dropped it with courier_cleanup",
+};
+/**
+ * What the parent gets when a group it named is released: every report, with its status, text and artifacts in
+ * `reportBody`'s layout, and the members that left without one, in the order they joined.
+ */
+export function groupNotice(group, reports, left = []) {
+    const total = reports.length + left.length;
+    const listed = reports.flatMap((report, index) => [
+        "",
+        `[${index + 1}/${reports.length}] ${report.sessionID} "${report.title}": ${report.status}`,
+        reportBody(report.message, report.artifacts),
+    ]);
+    const named = left.map((member) => `${member.sessionID} "${member.title}" (${LEFT_HOW[member.by]})`).join(", ");
+    const without = left.length ? ["", `Without a report: ${named}.`] : [];
+    const missing = left.length ? `, ${count(left.length, "member")} without a report, named at the end` : "";
+    return [
+        `Group "${group}" is complete: ${count(reports.length, "report")} of ${count(total, "member")} (${statusCounts(reports)})${missing}. Each report follows, with its status.`,
+        ...listed,
+        ...without,
+        "",
+        "Check and integrate each one yourself. The sessions that reported are idle; message one with courier_send if it has more to do.",
     ].join("\n");
 }
 // Permission requests.
@@ -302,9 +582,8 @@ export function withdrawnText(linked, how) {
     return `Session ${linked.sessionID} no longer waits on this question: it was ${withdrawnHow(linked, how)}. There is nothing to pass on; tell the person it is settled.`;
 }
 /**
- * What a linked call adds to the person's answers about passing them on: `passed` is what passing
- * them on gave ("result", "message", or undefined when it no longer waited), or the error as
- * `error: <message>`.
+ * What a linked call adds to the person's answers about passing them on: `passed` is "result",
+ * "message", undefined when it no longer waited, or the error as `error: <message>`.
  */
 export function passedNote(linked, passed) {
     if (passed === "result")

package/dist/question/answer.js

@@ -57,9 +57,8 @@ const holding = (id, ms, effect) => Effect.acquireUseRelease(Effect.sync(() => {
 export const deliver = (ports, asked, outcome) => Effect.suspend(() => {
     const id = asked.requestID;
     const wait = ports.timing.passingWaitMs;
-    // One answer at a time, and once, per question in this process: storage cannot be claimed
-    // atomically. A second answer waits for the first, and is passed on if the first was not.
-    // While one is under way, nobody is told that the question was cut off, nor links to it.
+    // One answer at a time, and once, per question in this process, since storage cannot be claimed
+    // atomically: a second waits, going only if the first did not; meanwhile no cut-off notice or link.
     const since = ports.now();
     const left = () => wait - (ports.now() - since);
     const turn = holding(id, wait, Effect.gen(function* () {
@@ -73,9 +72,8 @@ export const deliver = (ports, asked, outcome) => Effect.suspend(() => {
             return undefined;
         const passing = passOn(ports, asked, outcome);
         shared.passing.set(id, passing);
-        // Held while it is passed on. One that hangs, on a notice that never returns, gives way
-        // after a while, so the question can be answered again; should it still go through, the
-        // child is told twice.
+        // Held while it is passed on; one that hangs on a notice that never returns gives way after a
+        // while, so the question can be answered again, and the child may then be told twice.
         yield* within(passing, wait).pipe(Effect.ensuring(Effect.sync(() => {
             if (shared.passing.get(id) === passing)
                 shared.passing.delete(id);
@@ -96,9 +94,8 @@ async function passOn(ports, asked, outcome) {
         known.link?.({ by: "top", outcome });
         return "result";
     }
-    // Its call has just ended: whether it was cut off, and so stays registered, or was settled, and
-    // so is dropped, is known once settle is through. The registry decides, not storage, which a
-    // question whose record could not be written is missing from.
+    // Its call just ended: whether it was cut off and stays or was settled and is dropped is known once
+    // settle is through, from the registry, not storage, which lacks a question whose write failed.
     if (known) {
         await known.settling;
         if (shared.questions.get(id) !== known)