opencode-courier 0.14.0 → 0.16.0

package/dist/tree/limits.d.ts

@@ -4,3 +4,4 @@ export declare function admit(ports: LimitPorts, parentID: string): Promise<{
     reservation: Reservation;
     release: () => void;
 }>;
+export declare function liveBelow(ports: Pick<LimitPorts, "session" | "storage">, sessionID: string): Promise<import("./domain.js").RosterEntry[]>;

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)));
@@ -45,8 +52,15 @@ async function check(ports, parentID) {
     if (mine >= maxChildren)
         throw new Error(childrenRefusal(mine, maxChildren));
     if (counted.length + pending.length >= maxTotal)
-        throw new Error(totalRefusal(counted.length + pending.length, maxTotal));
+        throw new Error(totalRefusal(counted.length + pending.length, maxTotal, mine));
     const reservation = { parentID, top };
     ports.gate.reserved.add(reservation);
     return { depth: chain.length + 1, reservation };
 }
+export async function liveBelow(ports, sessionID) {
+    const entries = await childStore(ports.storage).all();
+    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] === "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/ports.d.ts

@@ -93,6 +93,7 @@ export interface Sent {
 export interface Role {
     readonly depth: number | null;
     readonly entry: boolean;
+    readonly subagent?: true;
 }
 export type Instructions = Partial<Pick<Context["session"], "instructions">>;
 export type Lister = Partial<Pick<Context["session"], "list">>;
@@ -211,7 +212,7 @@ export interface StopPorts {
 }
 export interface GroupPorts {
     readonly storage: Storage;
-    readonly session: Pick<Context["session"], "synthetic" | "get"> & Instructions;
+    readonly session: Pick<Context["session"], "synthetic" | "get" | "context"> & Instructions;
     readonly now: () => number;
     readonly log: (message: string) => void;
 }
@@ -239,6 +240,7 @@ export interface ContextPorts {
     readonly storage: RosterStorage;
     readonly limits: Limits;
     readonly roles: Map<string, Role>;
+    readonly session: Pick<Context["session"], "get">;
     readonly instructions?: Context["session"]["instructions"];
     readonly hiddenFromLeaf?: ReadonlyArray<string>;
     readonly log: (message: string) => void;

package/dist/tree/report.d.ts

@@ -2,13 +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, 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,6 +4,11 @@ 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, after = -Infinity) {
+    const { prompt, settled } = await children.notes(sessionID, ["prompt", "settled"]);
+    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;
     return isStatus(status) ? status : undefined;
@@ -20,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/spawn.d.ts

@@ -10,6 +10,7 @@ export interface SpawnInput {
     readonly native?: boolean;
 }
 export declare function spawn(ports: CourierPorts, parentID: string, input: SpawnInput): Promise<{
+    belowTop?: boolean | undefined;
     native?: boolean | undefined;
     model?: string | undefined;
     uncommitted?: boolean | undefined;

package/dist/tree/spawn.js

@@ -60,17 +60,18 @@ async function start(ports, parentID, input, admitted, group) {
         ...(group && !rosterError && !groupError ? { group } : {}),
         ...(rosterError ? { rosterError } : {}),
         ...(groupError ? { groupError } : {}),
-        ...(handedDown ? { fromParent: true } : {}),
+        ...(handedDown?.from ? { fromParent: true } : {}),
         ...(handedDown?.uncommitted ? { uncommitted: true } : {}),
         ...(model ? { model } : {}),
         ...(entry.native ? { native: true } : {}),
+        ...(admitted.depth > 1 ? { belowTop: true } : {}),
     };
 }
 async function create(ports, parentID, input) {
     const { model, parent } = await chooseModel(ports, parentID, input, input.agent);
     const handedDown = input.isolate ? await parentWork(ports, parentID) : undefined;
     const worktree = input.isolate
-        ? (await ports.worktree.create({ projectID: ports.projectID, ...(handedDown ? { from: handedDown.directory, branch: handedDown.head } : {}) })).directory
+        ? (await ports.worktree.create({ projectID: ports.projectID, ...(handedDown?.from ? { from: handedDown.from.directory, branch: handedDown.from.head } : {}) })).directory
         : undefined;
     const base = worktree ? await ports.head(worktree) : undefined;
     const title = input.title ?? titleOf(input.task);
@@ -104,13 +105,12 @@ async function create(ports, parentID, input) {
 }
 async function parentWork(ports, parentID) {
     const parent = await childStore(ports.storage).indexedEntry(parentID);
-    if (!parent?.isolated)
-        return undefined;
-    const head = await ports.head(parent.directory);
-    if (!head)
-        throw new Error(`the HEAD of your worktree ${parent.directory} could not be read, so an isolated session cannot start from it; nothing was started. Start it without isolate, or fix the worktree.`);
-    const uncommitted = (await ports.dirty(parent.directory).catch(() => undefined)) === true;
-    return { directory: parent.directory, head, uncommitted };
+    const directory = parent?.directory ?? ports.directory;
+    const head = parent?.isolated ? await ports.head(directory) : undefined;
+    if (parent?.isolated && !head)
+        throw new Error(`the HEAD of your worktree ${directory} could not be read, so an isolated session cannot start from it; nothing was started. Start it without isolate, or fix the worktree.`);
+    const uncommitted = (await ports.dirty(directory).catch(() => undefined)) === true;
+    return { ...(head ? { from: { directory, head } } : {}), uncommitted };
 }
 async function enrol(ports, entry, group) {
     const rosterError = await childStore(ports.storage).record(entry).then(() => undefined, (error) => describeFailure("roster", error).message);

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

@@ -28,7 +28,7 @@ export interface StandingRow {
 export declare function standingEntry(rows: ReadonlyArray<StandingRow>): 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 const totalRefusal: (running: number, maxTotal: number, yours: number) => string;
 export declare const modelFormatRefusal: (given: string) => string;
 export declare function unknownModelRefusal(model: ModelRef, known: ReadonlyArray<Pick<ModelRef, "providerID" | "id">>, named: boolean): string;
 export declare function unknownVariantRefusal(model: ModelRef, variants: ReadonlyArray<string>): string;
@@ -44,6 +44,7 @@ export declare function spawnText(child: {
     readonly fromParent?: boolean;
     readonly uncommitted?: boolean;
     readonly model?: string;
+    readonly belowTop?: boolean;
 }): string;
 export declare function sendText(sessionID: string, sent?: Pick<Sent, "status" | "report" | "held" | "dropped">): string;
 export declare const childrenText: (listed: ReadonlyArray<unknown>) => string;
@@ -69,11 +70,13 @@ 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[];
 }): string | undefined;
-export declare function failureNotice(title: string, error: ExecutionError, group?: string, at?: number): string;
+export declare function failureNotice(title: string, error: ExecutionError, group?: string, at?: number, below?: ReadonlyArray<string>): string;
 export declare function reportReminder(parentID: string): string;
 export declare function silentNotice(title: string, lastText: string | undefined, progressed?: boolean, group?: string): string;
 export declare function groupNotice(group: string, reports: ReadonlyArray<HeldReport & {

package/dist/tree/text.js

@@ -16,10 +16,13 @@ export function childBrief(parentID, task, depth, limits, branch) {
             "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 find something the other parts of the job need (an assumption of the split that is wrong, a shared file or API " +
             "that behaves otherwise), send it to the parent at once with courier_send without a status, then carry on: it passes " +
-            "it on to the sessions it affects. Progress alone is not worth a message.",
+            "it on to the sessions it affects. Do the same with one a session you started sends you, when it reaches past your own " +
+            "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.",
-        "If you need the person to decide something, use your question tool; it reaches them through the session that started you.",
+            "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. " +
+            "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), ""] : []),
         ...splitRule(parentID, depth, limits),
@@ -68,12 +71,13 @@ export function rolePart(depth, limits) {
             `${SKILL_ID} skill, call courier_recall once for how earlier trees in this project were split and how they went, ` +
             `and decide whether to split it across sessions (doing it yourself is fine; so is handing a heavy task, with long ` +
             `reading, many edits or long runs, whole to one session to keep your context, but never a small one), and say ` +
-            `which in one line of your reply: ${ROOT_SPLIT_LINE}`);
+            `which in one line of your reply: ${ROOT_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.`);
+            `down to ${maxDepth} levels below you. ${budget} Check and integrate what each one reports yourself. ` +
+            `Load the ${SKILL_ID} skill if it is not in your context.`);
     if (depth < maxDepth)
-        return (`${ROLE_PREFIX} sub-orchestrator, at depth ${depth} of at most ${maxDepth}. Before you split, load the ${SKILL_ID} ` +
+        return (`${ROLE_PREFIX} sub-orchestrator, at depth ${depth} of at most ${maxDepth}. Before you decide whether to split, load the ${SKILL_ID} ` +
             `skill. 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.");
@@ -132,11 +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.`;
-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.`;
+    `(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 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)}. ` +
@@ -184,15 +193,19 @@ export const nativeIsolateRefusal = () => "Not started: native: true and isolate
 export function spawnText(child) {
     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."
+            ? " Your working tree 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 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, 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.";
+            `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, ` +
         `end your turn: reply without calling more tools. That does not drop the task; you carry on with it when the reports arrive.${warning}`);
@@ -219,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.`,
@@ -240,14 +254,18 @@ export function treeText(tree) {
     const note = `\n${older} not listed: at most maxTotal are, the live ones first, then the newest; courier_tree on a listed session lists what is under it.`;
     return JSON.stringify(tree, null, 2) + note;
 }
+const IDLE_STOPPED = "Stopping an idle session does not settle it: one that owed a report still owes it, stays in its join group and " +
+    "counts toward maxChildren and maxTotal until the session that started it drops it with courier_cleanup.";
 export function stopText(result) {
     const interrupted = result.stopped.filter((one) => one.outcome === "interrupted").length;
     const failed = result.stopped.filter((one) => one.outcome === "failed");
+    const idle = result.stopped.some((one) => one.outcome === "idle" && !one.subagent);
     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.subagent ? " (subagent)" : ""}: ${one.outcome}${one.error ? " (" + one.error + ")" : ""}`),
         ...(failed.length ? ["Those that failed may still run: try courier_stop again."] : []),
+        ...(idle ? [IDLE_STOPPED] : []),
         result.cancelled.length
             ? `Cancelled ${count(result.cancelled.length, "scheduled message")}: ${result.cancelled.join(", ")}.`
             : "No scheduled messages were pending for them.",
@@ -255,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)})` : "",
@@ -297,17 +330,24 @@ function waitLine(delay, at) {
     const until = at === undefined ? "" : `, until about ${clock(at + delay, at)}`;
     return `The provider asked to wait about ${wait(delay)} before trying again${until}.`;
 }
-export function failureNotice(title, error, group, at) {
+function belowLine(below) {
+    const titles = below.map((title) => `"${title}"`).join(", ");
+    return (`It has ${count(below.length, "session")} of its own still running (${titles}), whose reports will wake it, and it still counts ` +
+        "toward your limits: message it rather than replace it, or stop it with courier_stop first, which stops the sessions under it too.");
+}
+export function failureNotice(title, error, group, at, below = []) {
     const status = error.status === undefined ? "" : `, status ${error.status}`;
     const delay = retryDelay(error);
+    const replace = below.length ? "" : " start a replacement,";
     return [
         `This session, "${title}", which you started with courier_spawn, failed: ${error.message} (${error.type}${status}).`,
         ...(delay === undefined ? [] : [waitLine(delay, at)]),
-        "Its turn ended without finishing, so it will not report back on its own.",
+        below.length ? "Its turn ended without finishing." : "Its turn ended without finishing, so it will not report back on its own.",
         delay === undefined
-            ? "Message it with courier_send to have it try again, start a replacement, or carry on without it."
-            : "Do not message it with courier_send before then, as the turn would fail again. Message it after, start a replacement, or carry on without it; " +
+            ? `Message it with courier_send to have it try again,${replace} or carry on without it.`
+            : `Do not message it with courier_send before then, as the turn would fail again. Message it after,${replace} or carry on without it; ` +
                 "courier_later can remind you when the wait is over.",
+        ...(below.length ? [belowLine(below)] : []),
         ...(group
             ? [
                 `It is a member of group "${group}", which no longer waits for it: its other members' reports reach you once they have ` +
@@ -334,8 +374,10 @@ export function silentNotice(title, lastText, progressed = false, group) {
             : []),
         ...(reply ? ["Its last reply:", defuse(clipText(reply, QUOTED_REPLY_MAX))] : ["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.",
+        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, 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

@@ -21,21 +21,23 @@ export const SpawnInput = Schema.Struct({
             "it unset for the chosen model's own; with a model of your own choosing, that is the model's default. Refused when " +
             "the model has no such variant.",
     })),
-    isolate: Schema.optional(Schema.Boolean.annotate({ description: "Run the session in its own git worktree so parallel sessions don't share files. From a session that is itself " +
-            "isolated, the worktree starts from your current commit, not your uncommitted changes: commit first. The session " +
+    isolate: Schema.optional(Schema.Boolean.annotate({ description: "Run the session in its own git worktree so parallel sessions don't share files. Commit first: its worktree " +
+            "starts from your last commit and sees only committed files and project skills, not your uncommitted changes. The session " +
             "commits on a branch named courier/<its session ID> and names it in its report; merge that branch yourself.",
     })),
     native: Schema.optional(Schema.Boolean.annotate({
         description: "true starts the session as your OpenCode subagent: it leaves OpenCode's session lists for your subagent tab, the " +
             "person answers its permission requests and questions in the view of the nearest session above it that is not a " +
-            "subagent, usually the top one, and deleting your session deletes it. false starts a standalone session, whatever the " +
+            "subagent, usually the top one (only OpenCode's TUI or paired app shows them; under opencode run without --auto " +
+            "or a bare API client they are rejected or wait unseen), and deleting your session deletes it. false starts a standalone session, whatever the " +
             "plugin's nativeChildren option says; unset, that option decides. Refused with isolate: true, as a subagent runs in " +
             "its parent's directory.",
     })),
     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, a question, a permission request or a failed turn still reaches you at once. 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.",
     })),
 });
@@ -83,11 +85,13 @@ export function addTreeTools(tools, ports) {
         description: "Start a new OpenCode session on a task and return immediately. It runs on your model, unless you name a model or a " +
             "variant (reasoning effort) fit for the task. The session reports " +
             "back with courier_send, which wakes this session, and you are told if its turn fails or ends without a report " +
-            "instead, it waits for a permission or it asks a question. Give a batch of parallel sessions one group name to " +
+            "instead, or it waits for a permission or asks a question (at the top of the tree; below it they go to the top). " +
+            "Give a batch of parallel sessions one group name to " +
             "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 long tasks, also courier_later a " +
-            "check-in for yourself in case it never reports, and courier_cancel it when it does.",
+            "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, 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"));
@@ -142,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) => {
@@ -155,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

@@ -62,8 +62,8 @@ var memoryRpc = Rpc.define({
 
 // src/kernel/protocol.ts
 var STATUSES = ["done", "partial", "blocked", "failed"];
-var SPLIT_LINE = "split: no, because \u2026; considered: <the parts you weighed> or split: <n> parts: \u2026 (one phrase per part)";
-var ONE_PART_LINE = "split: 1 part: <the task>, to keep my context";
+var SPLIT_LINE = "`split: no, because \u2026; considered: <the parts you weighed>` or `split: <n> parts: \u2026` (one phrase per part)";
+var ONE_PART_LINE = "`split: 1 part: <the task>, to keep my context`";
 var ROOT_SPLIT_LINE = `${SPLIT_LINE} or ${ONE_PART_LINE}`;
 
 // src/memory/domain.ts
@@ -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.14.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>",