opencode-courier 0.15.0 → 0.16.0

package/README.md

@@ -85,7 +85,7 @@ name, without a version: OpenCode offers updates only for an entry without an ex
 <!-- compat-table:start rows=3: generated by script/compat-table.ts from the release tags -->
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
-| 0.14.0, 0.15.0 | 2.2.6 |
+| 0.14.0, 0.15.0, 0.16.0 | 2.2.6 |
 | 0.13.7, 0.13.8 | 2.2.5 |
 | 0.13.6 | 2.2.4 |
 <!-- compat-table:end -->

package/dist/person/text.d.ts

@@ -1,7 +1,7 @@
 import type { Asked, Elsewhere, Form, Outcome, PermissionAnswered, PermissionRequest, Prompt, QuestionAnswered, Reply, Withdrawal } from "./ports.js";
 export type AnswerResult = PermissionAnswered | QuestionAnswered;
 export declare function answerText(result: AnswerResult): string;
-export declare const REJECTED = "Refused by the session that started you. Do without it, or report back why you cannot.";
+export declare const REJECTED = "Refused by the person or the top session of the tree. Do without it, or report back why you cannot.";
 export declare function refusedText(sessionID: string, requestID: string, reason: string): string;
 export declare const origin: (startedBy?: string) => string;
 export declare const STAYS_QUIET = "and then it does not report back on its own: if it stays quiet, message it with courier_send to have it carry on.";

package/dist/person/text.js

@@ -18,7 +18,7 @@ export function answerText(result) {
     return `Passed the answers to question ${result.requestID} on to ${result.sessionID}${how}; it carries on and reports back with courier_send. ${END_TURN}`;
 }
 // a bare rejection ends the child's turn (api-notes)
-export const REJECTED = "Refused by the session that started you. Do without it, or report back why you cannot.";
+export const REJECTED = "Refused by the person or the top session of the tree. Do without it, or report back why you cannot.";
 export function refusedText(sessionID, requestID, reason) {
     return `not allowed in your session (${reason}). The refusal was passed on with that reason to request ${requestID} of ${sessionID}, so its call fails and it carries on; it reports back with courier_send. Tell the person, and do not propose it again unless they ask.`;
 }

package/dist/person/tools.js

@@ -48,8 +48,9 @@ export function addPersonTools(tools, ports) {
             "working with in your session, as its own permission prompt for what that session asked, under your permission " +
             "rules, and the call returns once they have answered; what they allow is passed on, and a refusal with a reason " +
             "fails this call and is passed on with the reason. Do not ask them in your reply or with your question tool first. " +
-            "For a question, answers is what the person chose: ask them first, with your question tool if you have one, and " +
-            "never answer for them. The session carries on once it has the answer.",
+            "For a question, the question tool call the notice asks for passes the person's answer on by itself; use answers " +
+            "only when they answered some other way, or the notice or that call's result tells you to, and never answer for " +
+            "them. The session carries on once it has the answer.",
         input: AnswerInput,
         execute: async (input, context) => {
             const call = { messageID: context.messageID, callID: context.id };

package/dist/scheduling/later.js

@@ -76,7 +76,7 @@ export async function deliverDue(ports, claimed) {
                 sessionID: due.sessionID,
                 text: envelope(due.from, due.message, { scheduled: new Date(due.createdAt).toISOString() }),
                 description: `Scheduled message from ${due.from}`,
-                metadata: { source: "courier", from: due.from, scheduled: due.id },
+                metadata: { source: "courier", from: due.from, scheduled: due.id, scheduledAt: due.createdAt },
                 delivery: "queue",
             })
                 .catch((error) => ports.log(`courier_later ${due.id} to ${due.sessionID} not delivered: ${String(error)}`));

package/dist/scheduling/text.js

@@ -1,8 +1,8 @@
 export function laterText(entry, fireAt, own) {
     const next = own
         ? "It arrives when due, after your current turn if one is running, so do not wait for it: once nothing " +
-            "else is left to do now, end your turn by replying without calling more tools. If what it checks on " +
-            "reports first, cancel it then with courier_cancel."
+            "else is left to do now, end your turn by replying without calling more tools. Once the last report " +
+            "it covers arrives, cancel it with courier_cancel."
         : "Cancel it with courier_cancel if it is no longer needed.";
     return `Scheduled ${entry.id} for ${fireAt}, to ${entry.sessionID}. ${next}`;
 }

package/dist/scheduling/tools.js

@@ -18,9 +18,9 @@ export function addSchedulingTools(tools, later) {
         name: "courier_later",
         options: { codemode: false },
         description: "Schedule a message for a session (this one by default), delivered when due and waking it if idle. " +
-            "Use it as a safety net when you start sessions: schedule one check-in per group (per session " +
-            "when ungrouped), end your turn by replying without calling more tools, and cancel it with courier_cancel " +
-            "when the reports arrive, as a report does not cancel it. Survives server restarts; " +
+            "For a long task or batch of sessions you start, use it as a safety net: schedule one check-in per group, and " +
+            "one for the ungrouped sessions, end your turn by replying without calling more tools, and cancel each with " +
+            "courier_cancel when its last report arrives, as a report does not cancel it. Survives server restarts; " +
             "may arrive up to ~15 seconds late.",
         input: LaterInput,
         execute: async (input, context) => {

package/dist/skill.js

@@ -30,15 +30,16 @@ export const SKILL_CONTENT = [
     "",
     "## 3. End your turn",
     "",
-    "- Reply without calling more tools; reports and notices wake you. For a long task or batch, one courier_later " +
-        "check-in per group (per session when ungrouped); courier_cancel it when its reports arrive.",
+    "- Reply without calling more tools; reports and notices wake you.",
     "- At the root, a permission request or question from below arrives with its own instructions: follow them, and never " +
         "answer for the person.",
     "- When a message changes what other parts need (a wrong assumption of the split, a shared file or API that behaves " +
-        "otherwise, a decision of the person's), courier_send it at once, only to the sessions it affects; if it breaks the " +
-        "split, courier_stop those parts or send them a corrected task. A session's account of what the person told it is " +
-        "the person's word: pass it on, do not judge it against the original task, and never tell a session to undo what " +
-        "the person asked.",
+        "otherwise, a decision of the person's), courier_send it at once, only to the sessions it affects, and, below " +
+        "the root, also to the session that started you when it reaches past your part or carries " +
+        "the person's words, as your brief says; if it breaks the split, courier_stop those parts or send them a " +
+        "corrected task. " +
+        "A session's account of what the person told it is the person's word: pass it on, do not " +
+        "judge it against the original task, and never tell a session to undo what the person asked.",
     "",
     "## 4. Verify first-hand",
     "",

package/dist/tree/events.js

@@ -48,16 +48,35 @@ export async function reportFailure(ports, seen, event) {
 }
 // only inbox.enqueued carries the item's type (api-notes)
 const UNOWED = new Set(["user", "compaction", "move"]);
-const GROUP = "group";
-function kindOf(item) {
+const OWN = "own";
+const OWN_SCHEDULED = "own-scheduled:";
+const MESSAGE_FROM = "from:";
+function kindOf(sessionID, item) {
     const metadata = item.payload?.metadata;
-    return item.type === "synthetic" && metadata?.source === "courier" && typeof metadata.group === "string" ? GROUP : item.type;
+    if (item.type !== "synthetic" || metadata?.source !== "courier")
+        return item.type;
+    if (typeof metadata.group === "string")
+        return OWN;
+    const ownCheckIn = typeof metadata.scheduled === "string" && metadata.from === sessionID && typeof metadata.scheduledAt === "number";
+    if (ownCheckIn)
+        return `${OWN_SCHEDULED}${metadata.scheduledAt}`;
+    const statusless = typeof metadata.from === "string" && Object.keys(metadata).length === 2;
+    return statusless ? `${MESSAGE_FROM}${metadata.from}` : item.type;
+}
+async function ownAfterReport(children, sessionID, kind) {
+    if (kind === OWN)
+        return reportedSincePrompt(children, sessionID);
+    if (kind?.startsWith(MESSAGE_FROM))
+        return (await children.indexedParent(kind.slice(MESSAGE_FROM.length))) === sessionID && reportedSincePrompt(children, sessionID);
+    if (!kind?.startsWith(OWN_SCHEDULED))
+        return false;
+    return reportedSincePrompt(children, sessionID, Number(kind.slice(OWN_SCHEDULED.length)));
 }
 export async function noteEnqueued(ports, inbox, event) {
     const { sessionID, inboxID, item } = event.data;
     if ((await childStore(ports.storage).indexedParent(sessionID)) === undefined)
         return false;
-    setBounded(inbox, inboxID, kindOf(item), SEEN_MAX);
+    setBounded(inbox, inboxID, kindOf(sessionID, item), SEEN_MAX);
     return true;
 }
 export async function notePrompt(ports, event, inbox) {
@@ -69,7 +88,7 @@ export async function notePrompt(ports, event, inbox) {
     const parentID = await children.indexedParent(sessionID);
     if (parentID === undefined)
         return false;
-    if (kind === GROUP && (await reportedSincePrompt(children, sessionID)))
+    if (await ownAfterReport(children, sessionID, kind))
         return false;
     // the idle hook's reminder still publishes inbox.delivered (api-notes)
     if (inboxID !== undefined && (await children.nudgeOf(sessionID)).inboxID === inboxID)

package/dist/tree/limits.js

@@ -1,4 +1,4 @@
-import { isNotFound } from "../platform/json.js";
+import { isNotFound, millis } from "../platform/json.js";
 import { bySession, lineageBy } from "./domain.js";
 import { reportOf } from "./report.js";
 import { runs } from "./running.js";
@@ -11,10 +11,13 @@ async function live(ports, sessionID) {
         reportOf(childStore(ports.storage), sessionID).catch(() => undefined),
     ]);
     if (time === null)
-        return false;
-    const running = time !== undefined && !report?.ended && (await runs(ports.session, sessionID, time));
+        return undefined;
+    const inTurn = report?.reportedAt !== undefined && !(millis(time?.idle) >= report.reportedAt);
+    const running = time !== undefined && !report?.ended && !inTurn && (await runs(ports.session, sessionID, time));
     // a waiting inbox item is in no transcript until delivered (api-notes)
-    return running || (report?.owes ?? false) || (await waitsInInbox(ports, sessionID, { stalled: false }).catch(() => true));
+    if (running || report?.owes || (await waitsInInbox(ports, sessionID, { stalled: false }).catch(() => true)))
+        return "live";
+    return report?.blocked ? "blocked" : undefined;
 }
 export async function admit(ports, parentID) {
     const gate = ports.gate;
@@ -37,7 +40,11 @@ async function check(ports, parentID) {
     const chains = new Map(entries.map((entry) => [entry.sessionID, lineageBy(parents, entry.sessionID)]));
     const tree = entries.filter((entry) => chains.get(entry.sessionID).at(-1)?.parentID === top);
     const counting = await Promise.all(tree.map((entry) => live(ports, entry.sessionID)));
-    const active = new Set(tree.filter((_, i) => counting[i]).flatMap((entry) => [entry.sessionID, ...chains.get(entry.sessionID).map((above) => above.parentID)]));
+    const active = new Set(tree.flatMap((entry, i) => counting[i] === "live"
+        ? [entry.sessionID, ...chains.get(entry.sessionID).map((above) => above.parentID)]
+        : counting[i] === "blocked"
+            ? [entry.sessionID]
+            : []));
     const counted = tree.filter((entry) => active.has(entry.sessionID));
     const recorded = new Set(tree.map((entry) => entry.sessionID));
     const pending = [...ports.gate.reserved].filter((held) => held.top === top && !(held.sessionID && recorded.has(held.sessionID)));
@@ -55,5 +62,5 @@ export async function liveBelow(ports, sessionID) {
     const parents = bySession(entries);
     const below = [...parents.values()].filter((entry) => entry.sessionID !== sessionID && lineageBy(parents, entry.sessionID).some((above) => above.parentID === sessionID));
     const counting = await Promise.all(below.map((entry) => live(ports, entry.sessionID)));
-    return below.filter((_, i) => counting[i]);
+    return below.filter((_, i) => counting[i] === "live");
 }

package/dist/tree/nudge.d.ts

@@ -8,10 +8,12 @@ export interface Idle {
 export type NudgePorts = Pick<WatchPorts, "storage" | "session" | "permissions" | "now" | "log">;
 export declare function owedUnwaited(ports: NudgePorts, children: ChildStore, outside: Waits, sessionID: string): Promise<{
     resumesAt?: number | undefined;
+    reportedAt?: number | undefined;
     prompt: number;
     owes: boolean;
     progressed: boolean;
     ended: boolean;
+    blocked: boolean;
 } | undefined>;
 export declare function nudgeSilent(ports: NudgePorts, seen: Set<string>, outside: Waits, idle: Idle): Promise<boolean>;
 export declare function onIdle(ports: NudgePorts, seen: Set<string>, outside: Waits, idle: Idle): Promise<boolean>;

package/dist/tree/report.d.ts

@@ -2,14 +2,16 @@ import { type Status } from "../kernel/protocol.js";
 import type { ChildStore } from "./ports.js";
 type Notes = Pick<ChildStore, "notes">;
 export declare function stoppedSincePrompt(children: Notes, sessionID: string): Promise<boolean>;
-export declare function reportedSincePrompt(children: Notes, sessionID: string): Promise<boolean>;
+export declare function reportedSincePrompt(children: Notes, sessionID: string, after?: number): Promise<boolean>;
 export declare function lastStatus(children: Notes, sessionID: string): Promise<Status | undefined>;
 export declare function reportOf(children: Notes, sessionID: string): Promise<{
     resumesAt?: number | undefined;
+    reportedAt?: number | undefined;
     prompt: number;
     owes: boolean;
     progressed: boolean;
     ended: boolean;
+    blocked: boolean;
 } | undefined>;
 export declare function awaited(children: Notes, sessionID: string): Promise<boolean>;
 export {};

package/dist/tree/report.js

@@ -4,9 +4,10 @@ export async function stoppedSincePrompt(children, sessionID) {
     const { stopped, prompt } = await children.notes(sessionID, ["stopped", "prompt"]);
     return stopped.at !== undefined && (prompt.at === undefined || stopped.at >= prompt.at);
 }
-export async function reportedSincePrompt(children, sessionID) {
+export async function reportedSincePrompt(children, sessionID, after = -Infinity) {
     const { prompt, settled } = await children.notes(sessionID, ["prompt", "settled"]);
-    return prompt.at !== undefined && settled.by === "report" && settled.status !== "blocked" && since(settled.at, prompt.at);
+    const at = settled.at;
+    return prompt.at !== undefined && settled.by === "report" && settled.status !== "blocked" && since(at, prompt.at) && at > after;
 }
 export async function lastStatus(children, sessionID) {
     const { status } = (await children.notes(sessionID, ["settled"])).settled;
@@ -24,6 +25,8 @@ export async function reportOf(children, sessionID) {
         owes: !done,
         progressed: since(progress.at, promptAt),
         ended: done && settled.by !== "report",
+        blocked: done && settled.by === "report" && settled.status === "blocked",
+        ...(done && settled.by === "report" && settled.status !== "blocked" ? { reportedAt: settled.at } : {}),
         ...(resumesAt === undefined ? {} : { resumesAt }),
     };
 }

package/dist/tree/stop.js

@@ -1,10 +1,11 @@
 import { isNotFound } from "../platform/json.js";
 import { describeFailure, envelope } from "../kernel/protocol.js";
 import { cleanup } from "./cleanup.js";
+import { lastStatus, reportOf } from "./report.js";
 import { syncStanding } from "./standing.js";
 import { childStore } from "./store.js";
 import { subtree } from "./subtree.js";
-import { stoppedNotice } from "./text.js";
+import { blockedStoppedNotice, idleStoppedNotice, stoppedNotice } from "./text.js";
 import { forgetWakes } from "./wake.js";
 const ROUNDS = 3;
 export const SETTLE_MS = 2_000;
@@ -39,9 +40,7 @@ export async function stop(ports, callerID, input) {
     await settle(ports, nodes, results, background, startedAt);
     const parents = new Set(nodes.flatMap((node) => (node.subagent ? [] : [node.entry.parentID])));
     await Promise.all([...parents].map((parentID) => syncStanding(ports.courier, parentID)));
-    const told = target.parentID !== callerID && results.find((one) => one.sessionID === sessionID)?.outcome === "interrupted"
-        ? await tell(ports, callerID, target)
-        : undefined;
+    const told = target.parentID === callerID ? undefined : await tellParent(ports, callerID, target, results);
     return {
         sessionID,
         stopped: results,
@@ -120,12 +119,25 @@ async function told(ports, parentID, ids, since) {
     await new Promise((resolve) => setTimeout(resolve, 50));
     return told(ports, parentID, ids, since);
 }
-async function tell(ports, callerID, target) {
+async function tellParent(ports, callerID, target, results) {
+    const outcome = results.find((one) => one.sessionID === target.sessionID)?.outcome;
+    if (outcome === "interrupted")
+        return tell(ports, target, stoppedNotice(target.title, callerID));
+    if (outcome !== "idle")
+        return undefined;
+    const children = childStore(ports.courier.storage);
+    const report = await reportOf(children, target.sessionID).catch(() => undefined);
+    if (report?.owes)
+        return tell(ports, target, idleStoppedNotice(target.title, callerID));
+    const status = report ? await lastStatus(children, target.sessionID).catch(() => undefined) : undefined;
+    return status === "blocked" ? tell(ports, target, blockedStoppedNotice(target.title, callerID)) : undefined;
+}
+async function tell(ports, target, notice) {
     const { session, log } = ports.courier;
     try {
         await session.synthetic({
             sessionID: target.parentID,
-            text: envelope(target.sessionID, stoppedNotice(target.title, callerID), { ended: "stopped" }),
+            text: envelope(target.sessionID, notice, { ended: "stopped" }),
             description: `Session ${target.sessionID} was stopped`,
             metadata: { source: "courier", from: target.sessionID, ended: "stopped" },
             delivery: "steer",

package/dist/tree/text.d.ts

@@ -70,6 +70,8 @@ export declare function stopText(result: {
     readonly told?: string;
 }): string;
 export declare const stoppedNotice: (title: string, by: string) => string;
+export declare const idleStoppedNotice: (title: string, by: string) => string;
+export declare const blockedStoppedNotice: (title: string, by: string) => string;
 export declare function keepReason(state: {
     readonly changes: readonly string[];
     readonly commits: readonly string[];

package/dist/tree/text.js

@@ -20,7 +20,8 @@ export function childBrief(parentID, task, depth, limits, branch) {
             "part. Progress alone is not worth a message.",
         "A message the person writes in your session, outside a <courier> envelope, is for the whole job: before you act on it, " +
             "send it to the parent at once with courier_send without a status, quoting it as the person's, then carry on. The " +
-            "person's words a session you started passes you are for the whole job too: send them on to the parent the same way.",
+            "person's words a session you started passes you are for the whole job too: send them on to the parent the same way. " +
+            "They are the person's word: do not judge them against your task, and never tell a session to undo them.",
         "If you need the person to decide something, use your question tool; it reaches them through the top session of the tree.",
         "",
         ...(branch ? [...isolationRule(branch, depth < limits.maxDepth), ""] : []),
@@ -135,13 +136,16 @@ export function standingEntry(rows) {
 }
 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.";
-const live = (n) => (n === 1 ? "is running or has not reported yet" : "are running or have not reported yet");
+const live = (n) => (n === 1 ? "is running, blocked or still owes a report" : "are running, blocked or still owe a report");
+const stillCounts = (whoDrops) => `A session also counts while one it started is live, and one that is blocked, or whose turn ended without a report unless it failed or was interrupted, counts until it reports or ${whoDrops} it with courier_cleanup.`;
 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, not in a loop.`;
+    `(maxChildren ${maxChildren}). Do this part yourself, or answer any of them that is blocked, end your turn and start it once one of them has reported, not in a loop. ` +
+    stillCounts("you drop");
 export const totalRefusal = (running, maxTotal, yours) => `Not started: ${count(running, "session")} in this session tree ${live(running)}, the most allowed at once (maxTotal ${maxTotal}). ` +
     (yours === 0
-        ? "Do this part yourself: none of the sessions you started is running, so no report will wake you."
-        : "Do this part yourself, or end your turn and try again once a report has arrived, not in a loop.");
+        ? "Do this part yourself: none of the sessions you started counts, so only reports already held for a group can still wake you."
+        : "Do this part yourself, or answer any session you started that is blocked, end your turn and try again once one of them has reported, not in a loop. " +
+            stillCounts("its parent drops"));
 const LISTED_MAX = 12;
 const some = (items) => (items.length > LISTED_MAX ? `${items.slice(0, LISTED_MAX).join(", ")} and ${items.length - LISTED_MAX} more` : items.join(", "));
 export const modelFormatRefusal = (given) => `Not started: model must be provider/model, as OpenCode names them (opencode/gpt-5-nano, anthropic/claude-sonnet-4-5), not ${JSON.stringify(given)}. ` +
@@ -196,10 +200,11 @@ export function spawnText(child) {
     const asks = child.belowTop
         ? " Its permission requests and questions go to the top session of the tree, not to you, so a child slow to report may be waiting on the person."
         : "";
+    const topAsks = child.belowTop ? "" : ", and so does a question or a permission request";
     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${child.belowTop ? "" : ", a question"} ` +
-            `or a failed turn still reaches you at once.${asks}`
+            `turn has ended, you get their reports in one message, which starts a new turn for you; a blocked report, a failed turn ` +
+            `or an end without a report still reaches you at once${topAsks}.${asks}`
         : `It will report back with courier_send, which starts a new turn for you.${asks}`;
     const on = child.model ? `, on ${child.model}` : "";
     return (`Started session ${child.sessionID} in ${child.directory}${on}. ${reports} Once you have started every session you need, ` +
@@ -227,9 +232,10 @@ export function sendText(sessionID, sent = {}) {
     return `Delivered to ${sessionID}.`;
 }
 export const childrenText = (listed) => listed.length ? JSON.stringify(listed, null, 2) : "No sessions started with courier_spawn.";
+const keptLine = (result) => `Kept the worktree ${result.directory} of ${result.sessionID}: it has ${result.reason}.`;
 export function cleanupText(result) {
     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.`;
+        return `${keptLine(result)} ${result.sessionID} is not dropped yet: commit what you want to keep to a branch, then call courier_cleanup again, or call it now with force: true to discard it. Either call drops ${result.sessionID}.`;
     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.`,
@@ -267,18 +273,33 @@ export function stopText(result) {
         ...(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.";
 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."));
+    return cleanup.map((one) => {
+        if (one.outcome === "failed")
+            return `Worktree of ${one.sessionID}: not removed (${one.error}).`;
+        if (one.outcome === "kept")
+            return `${keptLine(one)} Kept; courier_cleanup with force: true discards it.`;
+        return cleanupText(one);
+    });
 }
 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");
+const HOLDS_GROUP = "holds back its join group if it is in one";
+export const idleStoppedNotice = (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 running and still owed you a report, so it still counts toward maxChildren and maxTotal, and ${HOLDS_GROUP}. ` +
+        "Drop it with courier_cleanup if you no longer need it, or message it with courier_send to have it carry on.",
+].join("\n");
+export const blockedStoppedNotice = (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 running: it had sent you status blocked and was waiting on your answer. Do not send it that answer, since the work it asked about was stopped above you. " +
+        `It still ${HOLDS_GROUP}. ` +
+        "Drop it with courier_cleanup if you no longer need it, or message it with courier_send if you still need it to carry on.",
+].join("\n");
 export function keepReason(state) {
     const reasons = [
         state.changes.length ? `${count(state.changes.length, "uncommitted change")} (${preview(state.changes)})` : "",
@@ -356,7 +377,7 @@ export function silentNotice(title, lastText, progressed = false, group) {
         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."
             : "Decide what it needs: message it with courier_send to have it carry on; or start a replacement.",
-        "Until it reports, it counts toward your limits on the sessions you run at once.",
+        "Until it reports, it counts toward your limits on the sessions you run at once, or until you drop it with courier_cleanup.",
         ...(group
             ? [
                 `It is a member of group "${group}", whose other reports are held until it reports: have it report, as above, so the group ` +

package/dist/tree/tools.js

@@ -36,8 +36,8 @@ export const SpawnInput = Schema.Struct({
     group: Schema.optional(Schema.String.annotate({
         description: "A join group: start the sessions of one batch with the same name, and their reports are held and delivered " +
             "to you in one message once every one of them has reported and your turn has ended, instead of one turn per " +
-            "report. A blocked report or a failed turn still reaches you at once, and so do a question and a permission request " +
-            "(at the top of the tree; below it they go to the top). Letters, " +
+            "report. A blocked report, a failed turn or an end without a report still reaches you at once, and at the top of " +
+            "the tree so do a question and a permission request (below it they go to the top). Letters, " +
             "digits, dots, dashes and underscores, up to 60; the name is free again once the group has been delivered.",
     })),
 });
@@ -90,8 +90,8 @@ export function addTreeTools(tools, ports) {
             "be woken once, with all their reports, instead of once per report. DO NOT poll it or call courier_children in a " +
             "loop: once you have started the sessions you need, end your turn by replying without calling more tools; each " +
             "report, or each group's reports, starts a new turn in which you carry on. For a long task or batch, also " +
-            "courier_later one check-in for yourself per group (per session when ungrouped) in case the reports never come, " +
-            "and courier_cancel it when they arrive: a report does not cancel it.",
+            "courier_later one check-in for yourself per group, and one for the ungrouped sessions, in case the reports never " +
+            "come, and courier_cancel each when its last report arrives: a report does not cancel it.",
         input: SpawnInput,
         execute: async (input, context) => {
             const child = await spawn(ports.courier, context.sessionID, input).catch(rethrow("courier_spawn"));
@@ -146,7 +146,7 @@ export function addTreeTools(tools, ports) {
         description: "Stop a session you started, directly or through others, and every session under it, subagents included: each " +
             "running turn is interrupted, deepest first, and the messages scheduled for them with courier_later are cancelled. Use it when a " +
             "subtree went wrong or is no longer needed. They do not report back, and you are not told of what you stopped; a " +
-            "session between you and the target is. A stopped session can be woken again with courier_send. With " +
+            "session between you and the target is, when the target was running, still owed it a report or was waiting on its answer to a blocked report. A stopped session can be woken again with courier_send. With " +
             "cleanup: true their worktrees are removed too, unless they hold work that is on no branch.",
         input: StopInput,
         execute: async (input, context) => {
@@ -159,8 +159,9 @@ export function addTreeTools(tools, ports) {
         options: { codemode: false },
         description: "Remove the git worktree of a session you started with isolate: true, once you have what you need from it, " +
             "and drop it from courier_children. A worktree with uncommitted changes or commits on no branch is kept and " +
-            "the result lists them; commit or branch what you want, or pass force: true to discard it. A session without " +
-            "isolate has no worktree and is only dropped from courier_children. Either way, one in a join group that has not " +
+            "the result lists them, the session staying listed; commit what you want to a branch and call again, or pass " +
+            "force: true to discard it. A session without isolate has no worktree and is only dropped from " +
+            "courier_children. Once dropped, one in a join group that has not " +
             "reported is dropped from it, so the group's other reports reach you without it; use this for a member you no " +
             "longer need a report from. It never deletes the session itself, nor the sessions it started.",
         input: CleanupInput,

package/dist/tui.js

@@ -542,7 +542,7 @@ var personRpc = Rpc2.define({
 });
 
 // src/person/text.ts
-var REJECTED = "Refused by the session that started you. Do without it, or report back why you cannot.";
+var REJECTED = "Refused by the person or the top session of the tree. Do without it, or report back why you cannot.";
 
 // src/person/tui.tsx
 var QUESTION_FORM = "question";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-courier",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Multi-session orchestration for OpenCode V2: spawn child sessions, be woken by them. No polling.",
   "license": "MIT",
   "author": "Ivo Pogace <71701666+ivopogace@users.noreply.github.com>",