opencode-courier 0.14.0 → 0.15.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 | 2.2.6 |
+| 0.14.0, 0.15.0 | 2.2.6 |
 | 0.13.7, 0.13.8 | 2.2.5 |
 | 0.13.6 | 2.2.4 |
 <!-- compat-table:end -->

package/dist/index.js

@@ -115,7 +115,7 @@ export const courier = () => Plugin.define({
             .catch((error) => log(`courier rpc: not registered, the TUI part shows nothing and cannot stop: ${String(error)}`));
         // a host before 2.2.0 has no instructions entries (api-notes)
         const instructions = ctx.session.instructions;
-        await ctx.session.hook("context", (event) => shapeContext({ storage: ctx.storage, limits, roles, instructions, hiddenFromLeaf: [RECALL_TOOL, NOTE_TOOL], log }, event));
+        await ctx.session.hook("context", (event) => shapeContext({ storage: ctx.storage, session: ctx.session, limits, roles, instructions, hiddenFromLeaf: [RECALL_TOOL, NOTE_TOOL], log }, event));
         const pruned = pruneExpired(ctx.storage, Date.now()).catch((error) => log(`courier roster prune: ${String(error)}`));
         const swept = sweepRecords(ctx.storage, Date.now()).catch((error) => log(`courier memory sweep: ${String(error)}`));
         const windowed = ports

package/dist/kernel/protocol.d.ts

@@ -2,9 +2,9 @@ export declare const END_TURN = "If nothing else is left to do now, end your tur
 export declare const STATUSES: readonly ["done", "partial", "blocked", "failed"];
 export type Status = (typeof STATUSES)[number];
 export declare const isStatus: (value: unknown) => value is Status;
-export declare const SPLIT_LINE = "split: no, because \u2026; considered: <the parts you weighed> or split: <n> parts: \u2026 (one phrase per part)";
-export declare const ONE_PART_LINE = "split: 1 part: <the task>, to keep my context";
-export declare const ROOT_SPLIT_LINE = "split: no, because \u2026; considered: <the parts you weighed> or split: <n> parts: \u2026 (one phrase per part) or split: 1 part: <the task>, to keep my context";
+export declare const SPLIT_LINE = "`split: no, because \u2026; considered: <the parts you weighed>` or `split: <n> parts: \u2026` (one phrase per part)";
+export declare const ONE_PART_LINE = "`split: 1 part: <the task>, to keep my context`";
+export declare const ROOT_SPLIT_LINE = "`split: no, because \u2026; considered: <the parts you weighed>` or `split: <n> parts: \u2026` (one phrase per part) or `split: 1 part: <the task>, to keep my context`";
 export declare const SKILL_ID = "courier-orchestrate";
 export declare function envelope(from: string, message: string, attributes?: Record<string, string>): string;
 export declare function clipText(text: string, max?: number): string;

package/dist/kernel/protocol.js

@@ -1,8 +1,8 @@
 export const END_TURN = "If nothing else is left to do now, end your turn by replying without calling more tools.";
 export const STATUSES = ["done", "partial", "blocked", "failed"];
 export const isStatus = (value) => typeof value === "string" && STATUSES.includes(value);
-export const SPLIT_LINE = "split: no, because …; considered: <the parts you weighed> or split: <n> parts: … (one phrase per part)";
-export const ONE_PART_LINE = "split: 1 part: <the task>, to keep my context";
+export const SPLIT_LINE = "`split: no, because …; considered: <the parts you weighed>` or `split: <n> parts: …` (one phrase per part)";
+export const ONE_PART_LINE = "`split: 1 part: <the task>, to keep my context`";
 export const ROOT_SPLIT_LINE = `${SPLIT_LINE} or ${ONE_PART_LINE}`;
 export const SKILL_ID = "courier-orchestrate";
 export function envelope(from, message, attributes = {}) {

package/dist/memory/lessons.d.ts

@@ -1,4 +1,4 @@
 import { type Entry } from "../tree/index.js";
 import type { MemoryPorts } from "./ports.js";
 export declare function lessonsOf(ports: MemoryPorts): Promise<ReadonlyArray<Entry>>;
-export declare function relesson(ports: MemoryPorts, writerID: string, top: string): Promise<string[]>;
+export declare function relesson(ports: MemoryPorts, top: string): Promise<string[]>;

package/dist/memory/lessons.js

@@ -9,7 +9,7 @@ export async function lessonsOf(ports) {
     const value = lessonsEntry(pinnedFirst(await memoryStore(ports.storage).ofProject(ports.projectID)));
     return value === undefined ? [] : [{ key: LESSONS_KEY, value }];
 }
-export async function relesson(ports, writerID, top) {
+export async function relesson(ports, top) {
     const entries = ports.session.instructions?.entry;
     if (!entries)
         return [];
@@ -21,7 +21,7 @@ export async function relesson(ports, writerID, top) {
         if (!entry)
             return [];
         const children = ports.maxDepth > 1 ? await childrenOf(ports.storage, top) : [];
-        sessions = [...new Set([top, ...children.map((child) => child.sessionID), writerID])];
+        sessions = [top, ...children.map((child) => child.sessionID)];
     }
     catch (error) {
         ports.log(`courier_note: the lessons entry could not be read again: ${String(error)}`);

package/dist/memory/note.d.ts

@@ -6,9 +6,9 @@ export interface NoteInput {
 export type Refusal = {
     readonly kind: "off";
 } | {
-    readonly kind: "leaf";
+    readonly kind: "below";
     readonly depth: number;
-    readonly maxDepth: number;
+    readonly top: string;
 } | {
     readonly kind: "empty";
 } | {

package/dist/memory/note.js

@@ -6,22 +6,21 @@ export async function note(ports, callerID, input) {
     if (!ports.memory)
         return { kind: "off" };
     const chain = await lineage(ports.storage, callerID);
-    const depth = chain.length;
-    if (depth >= ports.maxDepth)
-        return { kind: "leaf", depth, maxDepth: ports.maxDepth };
+    const top = chain.at(-1)?.parentID ?? callerID;
+    if (chain.length)
+        return { kind: "below", depth: chain.length, top };
     const text = oneLine(typeof input.text === "string" ? input.text : "");
     if (!text)
         return { kind: "empty" };
     if (text.length > LESSON_MAX)
         return { kind: "long", length: text.length };
-    const top = chain.at(-1)?.parentID ?? callerID;
     const store = memoryStore(ports.storage);
     const { projectID } = ports;
     const record = await store.get(projectID, top);
     if (!record)
         return { kind: "unrecorded", top };
-    const lesson = { text, at: ports.now(), ...(depth ? { depth } : {}) };
+    const lesson = { text, at: ports.now() };
     await store.put(projectID, top, { ...record, lesson });
-    await relesson(ports, callerID, top);
+    await relesson(ports, top);
     return { kind: "noted", projectID, top, lesson, ...(record.lesson ? { replaced: record.lesson } : {}) };
 }

package/dist/memory/text.d.ts

@@ -11,7 +11,7 @@ export declare function recallRecordText(record: StoredRecord): string;
 export declare const recallMissingText: (sessionID: string) => string;
 export declare function noteText(top: string, lesson: Lesson, replaced: Lesson | undefined): string;
 export declare const NOTE_OFF = "Not noted: the plugin's memory option is false, so no record of a session tree is kept in this project to write a lesson on.";
-export declare const noteLeafRefusal: (depth: number, maxDepth: number) => string;
+export declare const noteBelowRefusal: (depth: number, top: string) => string;
 export declare const NOTE_EMPTY = "Not noted: text is empty. Write one line, what the next orchestrator in this project should know about running a tree like this one, with the job it comes from and the reason, or nothing.";
 export declare const noteLongRefusal: (length: number) => string;
 export declare const noteUnrecordedRefusal: (top: string) => string;

package/dist/memory/text.js

@@ -84,8 +84,8 @@ export function noteText(top, lesson, replaced) {
     ].join(" ");
 }
 export const NOTE_OFF = "Not noted: the plugin's memory option is false, so no record of a session tree is kept in this project to write a lesson on.";
-export const noteLeafRefusal = (depth, maxDepth) => `Not noted: this session is a leaf, at depth ${depth} of a session tree that goes at most ${maxDepth} deep (maxDepth). A lesson is ` +
-    "written by the session that verified the tree, the top or one that started sessions; put what you learned in your report instead.";
+export const noteBelowRefusal = (depth, top) => `Not noted: this session is at depth ${depth} of the session tree under ${top}, and only that top session writes the tree's ` +
+    "lesson, once the whole tree is verified. Put what you learned in your report instead: the top reads it and writes the tree's lesson.";
 const ONE_LINE = "what the next orchestrator in this project should know about running a tree like this one, with the job it comes from and the reason";
 export const NOTE_EMPTY = `Not noted: text is empty. Write one line, ${ONE_LINE}, or nothing.`;
 export const noteLongRefusal = (length) => `Not noted: the lesson is ${length} characters, at most ${LESSON_MAX}; write it shorter. Nothing was written, and the earlier lesson, ` +

package/dist/memory/tools.js

@@ -4,7 +4,7 @@ import { rethrow } from "../kernel/tool.js";
 import { LESSON_MAX } from "./domain.js";
 import { note } from "./note.js";
 import { recall } from "./recall.js";
-import { NOTE_EMPTY, NOTE_OFF, NOTE_TOOL, noteLeafRefusal, noteLongRefusal, noteText, noteUnrecordedRefusal, RECALL_OFF, RECALL_TOOL, recallListText, recallMissingText, recallRecordText } from "./text.js";
+import { NOTE_EMPTY, NOTE_OFF, NOTE_TOOL, noteBelowRefusal, noteLongRefusal, noteText, noteUnrecordedRefusal, RECALL_OFF, RECALL_TOOL, recallListText, recallMissingText, recallRecordText } from "./text.js";
 export const RecallInput = Schema.Struct({
     sessionID: Schema.optional(Schema.String.annotate({ description: "The top session of a listed record, for that record in full; without it, one line per record of this project." })),
 });
@@ -50,7 +50,7 @@ export function addMemoryTools(tools, ports) {
             "so that a lesson for one kind of job can be told from one that holds everywhere. One line, at most " +
             `${LESSON_MAX} characters; a longer one is refused, not clipped, so write it again shorter. Kept on your own tree's ` +
             "record and listed by courier_recall after its facts, dated; a second call replaces the first. From the top session " +
-            "or one that started sessions, never a leaf. No code, no secrets, and not a rule that holds every time: that belongs " +
+            "only: a session below it puts what it learned in its report. No code, no secrets, and not a rule that holds every time: that belongs " +
             "in AGENTS.md or the skill, for the person to put there, so tell them instead.",
         input: NoteInput,
         execute: async (input, context) => {
@@ -63,8 +63,8 @@ export function addMemoryTools(tools, ports) {
                 }
                 case "off":
                     throw refuse(NOTE_OFF);
-                case "leaf":
-                    throw refuse(noteLeafRefusal(result.depth, result.maxDepth));
+                case "below":
+                    throw refuse(noteBelowRefusal(result.depth, result.top));
                 case "empty":
                     throw refuse(NOTE_EMPTY);
                 case "long":

package/dist/person/tools.js

@@ -42,7 +42,8 @@ export function addPersonTools(tools, ports) {
         name: "courier_answer",
         options: { codemode: false },
         description: "Pass on the answer to a permission request or a question that a session you started with courier_spawn (or " +
-            "one started from it) waits on, after a notice from it named the request. For a permission request, reply is " +
+            "one started from it) waits on, after a notice from it named the request. Only the top session of a tree gets " +
+            "those notices and can answer. For a permission request, reply is " +
             "the answer you propose, once or reject: proposing is not deciding. With once, OpenCode asks the person you are " +
             "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 " +

package/dist/scheduling/tools.js

@@ -18,8 +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, end your turn by replying without " +
-            "calling more tools, and cancel it with courier_cancel if the child reports first. Survives server restarts; " +
+            "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; " +
             "may arrive up to ~15 seconds late.",
         input: LaterInput,
         execute: async (input, context) => {
@@ -34,7 +35,8 @@ export function addSchedulingTools(tools, later) {
     tools.add({
         name: "courier_cancel",
         options: { codemode: false },
-        description: "Cancel a message scheduled with courier_later, e.g. because the child it was waiting for reported.",
+        description: "Cancel a message scheduled with courier_later, e.g. a check-in whose reports arrived. Nothing else cancels " +
+            "it but courier_stop of the session it is for.",
         input: CancelInput,
         execute: async (input) => {
             const cancelled = await cancel(later, input.id).catch(rethrow("courier_cancel"));

package/dist/skill.js

@@ -1,110 +1,61 @@
 import { ONE_PART_LINE, SKILL_ID, SPLIT_LINE } from "./kernel/protocol.js";
-export const SKILL_DESCRIPTION = "How opencode-courier's session tools work. Load before you split a task with courier_spawn: when it has 2 or more " +
-    "independent, substantial parts touching separate files or areas. Starting the parts, waiting without polling, " +
-    "relaying questions and permissions, reading reports, merging and reporting upward.";
+export const SKILL_DESCRIPTION = "How opencode-courier's session tools work. Load it when you decide whether to split a task across sessions with " +
+    "courier_spawn: one with 2 or more independent, substantial parts touching separate files or areas. Starting the " +
+    "parts, waiting without polling, permission requests and questions from below, verifying and merging.";
 export const SKILL_CONTENT = [
     "# How opencode-courier's session tools work",
     "",
-    "Your brief, or the opencode-courier role line in your system prompt, names your depth in the session tree and its " +
-        "limits. If courier_spawn is not among your tools, you cannot split: do the task yourself, and report upward as your " +
-        "brief says if a session started you.",
+    "If courier_spawn is not among your tools, you cannot split: do the task yourself. Planning the parts, staging a " +
+        "tightly coupled core and reviewing the merge are not in this skill: if a skill for them is listed to you, load it too.",
     "",
-    "This skill says how the tools behave. How to plan the parts, stage a tightly coupled core or review the merged result " +
-        "is a playbook's: if a skill for that is listed to you, load it too.",
+    "## 1. Split or do",
     "",
-    "## 1. Decide: split or do",
-    "",
-    "- At the root, first call courier_recall once, before you decide and never in a loop: it lists how earlier trees in " +
-        "this project were split and how each part went. Below the root, read none: the records describe whole trees, which " +
-        "the root weighed before it split.",
-    "- 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. Several whole jobs in one prompt, such as 4 tickets, are that many " +
-        "parts: each session runs this skill for its job, so the tree below you repeats its shape once per job.",
-    "- Only the root, the session nobody started, may start exactly one session for the whole task, and only when the " +
-        "task is heavy (long reading, many edits, long runs) and its own context is worth keeping; it still verifies and " +
-        "integrates that session's report itself. Every other session never starts exactly one session for the whole task: " +
-        "it only adds a hop, and a chain of single hops uses up the tree's depth. One session for one stage is a part, not " +
-        "the whole, as your brief says: a core you stage before the rest, when 2 or more parts follow it, or a review of " +
-        "the parts once you have merged them.",
-    `- Say which in one line of your reply, before you start: ${SPLIT_LINE}; the root has a third form, ${ONE_PART_LINE}.`,
+    "Split or do by the rule in your brief, the text above your task. At the root, the top session of the tree, which has no brief: split a task with 2 " +
+        "or more independent, substantial parts touching separate files or areas, do it yourself when it is small, " +
+        "sequential or tightly coupled, or hand a heavy one (long reading, many edits, long runs) whole to one session to " +
+        `keep your context. Say which in one line of your reply: ${SPLIT_LINE}, or, at the root only, ${ONE_PART_LINE}. Several whole ` +
+        "jobs in one prompt, such as 4 tickets, are that many parts. Below the root, never start one session for the whole " +
+        "task: it only adds a hop, and a chain of single hops uses up the tree's depth.",
     "",
     "## 2. Start the parts",
     "",
-    "- One courier_spawn per part that runs at once, all with the same group name, so that you are woken once with every " +
-        "report. No two parts edit the same files; isolate: true for each part that edits files in parallel with another. " +
-        "When the parts do not all fit the tree's limits at once, start the parts that fit in one group, and the rest in a " +
-        "group of their own once the first group has reported.",
+    "- One courier_spawn per part, the parts that run at once in one group. When they do not all fit the tree's limits " +
+        "at once, start waves, each its own group, or leave them ungrouped and start the next as each report frees a slot.",
+    "- No two parts edit the same files; isolate: true for each part that edits files in parallel with another.",
     "- Write each task so the session can do it without you, since it sees none of your conversation: what to produce " +
-        "and where, the context it needs, how to check it so that one permission rule covers the checks (step 4), and what to report. Name " +
-        "the skills it should load for its part, from those listed to you: it sees the same list, not your choice; one " +
-        "permission rule for skill covers their loads, as one covers the checks. Say whether it may split its part further, " +
-        "and when the part is a whole job that delivers itself (step 5), since an isolated session's brief otherwise says " +
-        "its branch is for you to merge.",
-    "- Leave model and variant unset, so a part runs on your own model, unless the part plainly calls for another: a " +
-        "cheaper one or a lower variant for a small, well-specified part, a stronger one or a higher variant for a design " +
-        "question or a hard bug. native: true for a part that only reads, checks or looks something up and reports once; " +
-        "leave it off for a part the person may want to open, or that should outlive you.",
-    "- A part that depends on another starts once that one is done: merged into your checkout, or, when it was " +
-        "delivered (step 5), started with isolate: true and told to merge the delivering session's courier/<session> " +
-        "branch first.",
+        "and where, the context it needs, how to check it, and what to report. Name the skills it should load for its " +
+        "part, from those listed to you (an isolated part sees only committed project skills).",
+    "- A part that depends on another starts once that one has reported and its branch, if isolated, is merged into " +
+        "your checkout.",
     "",
     "## 3. End your turn",
     "",
-    "Reply without calling more tools, and do not poll with courier_children, courier_tree or sleep. The group's reports, " +
-        "a blocked report, a message without a status, a question, a permission request, a failed turn or a silent end each start a new turn " +
-        "for you. For long work, courier_later a check-in for yourself, and courier_cancel it when the reports arrive.",
-    "",
-    "- Answering from below: follow the notice. A permission request: propose once with courier_answer, or reject with " +
-        "the reason when the person has told you to refuse it or it plainly goes against what they asked; the person " +
-        "decides in OpenCode's prompt. A question: ask the person with your question tool, with the questions the notice " +
-        "gives; their answer goes on by itself. When the notice says OpenCode already shows it to the person, call nothing " +
-        "unless they give you their answer. Never answer for them.",
-    "- Passing a message on: when it 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, " +
-        "then end your turn again; if it breaks the split, courier_stop those parts and plan them again, or send them a " +
-        "corrected task. Send it up too, without a status, when your parent's other parts need it. Progress goes to no one. " +
-        "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.",
+    "- 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.",
+    "- 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.",
     "",
-    "## 4. Read each report, and verify first-hand",
+    "## 4. Verify first-hand",
     "",
-    "- 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.",
-    "- Verify first-hand: open the files, run the checks. Never hand the checking to another session. Your own permission " +
-        "prompts are relayed nowhere, and each one stalls the whole tree, as each request below you waits on the person: run " +
-        "the checks so that one permission rule covers them, through the project's scripts rather than a tool's own path.",
+    "Open the files and run the project's checks yourself. A blocked report: 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. A " +
+        "partial or failed report: have it finish or retry with courier_send, do the rest yourself, or start a replacement.",
     "",
     "## 5. 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. When a part is a whole job with a " +
-        "deliverable of its own, its session delivers it and reports where, still naming its courier/<session> branch when " +
-        "it is isolated; you verify each delivery and merge nothing of it into your checkout.",
-    "",
-    "## 6. 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, or verified and delivered; partial, blocked or failed otherwise) and the artifacts.",
-    "- At the top, before you reply to the person: if the next tree in this project should know something about running " +
-        "one like this (how it was split, what a part got wrong and what caught it, what a brief should have said, what the " +
-        "person decided), one courier_note with that one line; none when there is nothing. Name the job it comes from and " +
-        "the reason, so a lesson for one kind of job is not taken for every job; the tool refuses a line over its limit " +
-        "rather than clipping it, so write it shorter. A rule that holds every time goes to AGENTS.md or a skill, through " +
-        "the person, not into a note.",
+    "Merge each isolated part's reported branch into your own checkout (git merge courier/<session>), resolve conflicts " +
+        "yourself and run the checks once more. Then courier_cleanup each session you are done with, isolated or not.",
     "",
-    "## When a part goes wrong",
+    "## 6. Done",
     "",
-    '- 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. A silent end counts " +
-        "toward the limits until it reports; a failed turn does not, until you message it again.",
-    "- 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.",
+    "The task is done only when every part is verified and integrated. At the root, before you reply to the person: one " +
+        "courier_note if the next tree in this project should know something about running one like this; none when there " +
+        "is nothing.",
 ].join("\n");
 // A skill:// path: the read tool serves it from the registry (api-notes)
 const SKILL_PATH = `skill://${SKILL_ID}/SKILL.md`;

package/dist/tree/context.js

@@ -5,12 +5,13 @@ const ROLES_MAX = 1000;
 const ROLE_LINE = new RegExp(`^${ROLE_PREFIX}`, "m");
 export async function shapeContext(ports, event) {
     try {
-        const { depth, entry } = await roleOf(ports, event.sessionID);
-        if (depth === null && !event.tools.courier_spawn)
-            return;
-        if (depth !== null && depth >= ports.limits.maxDepth)
+        const { depth, entry, subagent } = await roleOf(ports, event.sessionID);
+        const leaf = subagent || (depth !== null && depth >= ports.limits.maxDepth);
+        if (leaf)
             for (const tool of ["courier_spawn", ...(ports.hiddenFromLeaf ?? [])])
                 delete event.tools[tool];
+        if (subagent || (depth === null && !event.tools.courier_spawn))
+            return;
         if (entry || event.system.some((part) => ROLE_LINE.test(part.text)))
             return;
         event.system.push({ type: "text", text: rolePart(depth, ports.limits) });
@@ -19,13 +20,24 @@ export async function shapeContext(ports, event) {
         ports.log(`courier: cannot tell the role of session ${event.sessionID}: ${String(error)}`);
     }
 }
-async function roleOf(ports, sessionID) {
+async function roleOf(ports, sessionID, below = new Set()) {
     const known = ports.roles.get(sessionID);
     if (known !== undefined)
         return known;
     const children = childStore(ports.storage);
     const chain = await children.indexedLineage(sessionID);
     const depth = chain.length || ((await children.children(sessionID)).length ? 0 : null);
+    if (depth === null) {
+        const { parentID } = await ports.session.get({ sessionID });
+        if (parentID && !below.has(parentID)) {
+            const above = await roleOf(ports, parentID, new Set([...below, sessionID]));
+            if (above.depth === null && !above.subagent)
+                return { depth: null, entry: false };
+            const role = { depth: null, entry: false, subagent: true };
+            setBounded(ports.roles, sessionID, role, ROLES_MAX);
+            return role;
+        }
+    }
     const role = { depth, entry: depth !== null && (await hasEntry(ports, sessionID)) };
     setBounded(ports.roles, sessionID, role, ROLES_MAX);
     return role;

package/dist/tree/events.d.ts

@@ -23,6 +23,11 @@ export interface InboxEnqueued {
         readonly inboxID: string;
         readonly item: {
             readonly type: string;
+            readonly payload?: {
+                readonly metadata?: {
+                    readonly [key: string]: unknown;
+                };
+            };
         };
     };
 }

package/dist/tree/events.js

@@ -3,8 +3,9 @@ import { claim, SEEN_MAX, setBounded } from "../platform/bounded.js";
 import { endsIdle, retryDelay } from "./domain.js";
 import { forgetChild, forgetDeleted } from "./forget.js";
 import { hasCompleteGroup, leave, outIn } from "./group.js";
+import { liveBelow } from "./limits.js";
 import { owedUnwaited } from "./nudge.js";
-import { stoppedSincePrompt } from "./report.js";
+import { reportedSincePrompt, stoppedSincePrompt } from "./report.js";
 import { syncStanding } from "./standing.js";
 import { childStore, groupStore } from "./store.js";
 import { lastReply } from "./status.js";
@@ -26,9 +27,13 @@ export async function reportFailure(ports, seen, event) {
     try {
         if (quiet)
             return [];
+        const below = await liveBelow(ports, sessionID).then((live) => live.map((entry) => entry.title), (error) => {
+            ports.log(`courier watch: could not read the sessions under ${sessionID}: ${String(error)}`);
+            return [];
+        });
         await Promise.all(entries.map((entry, index) => ports.session.synthetic({
             sessionID: entry.parentID,
-            text: envelope(sessionID, failureNotice(entry.title, error, out[index]?.group, at), { failed: error.type }),
+            text: envelope(sessionID, failureNotice(entry.title, error, out[index]?.group, at, below), { failed: error.type }),
             description: `Session ${sessionID} failed`,
             metadata: { source: "courier", from: sessionID, failed: true },
             delivery: "steer",
@@ -43,21 +48,29 @@ 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 metadata = item.payload?.metadata;
+    return item.type === "synthetic" && metadata?.source === "courier" && typeof metadata.group === "string" ? GROUP : item.type;
+}
 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, item.type, SEEN_MAX);
+    setBounded(inbox, inboxID, kindOf(item), SEEN_MAX);
     return true;
 }
 export async function notePrompt(ports, event, inbox) {
     const { sessionID, inboxID } = event.data;
-    if (inboxID !== undefined && UNOWED.has(inbox?.get(inboxID) ?? ""))
+    const kind = inboxID === undefined ? undefined : inbox?.get(inboxID);
+    if (UNOWED.has(kind ?? ""))
         return false;
     const children = childStore(ports.storage);
     const parentID = await children.indexedParent(sessionID);
     if (parentID === undefined)
         return false;
+    if (kind === GROUP && (await reportedSincePrompt(children, sessionID)))
+        return false;
     // the idle hook's reminder still publishes inbox.delivered (api-notes)
     if (inboxID !== undefined && (await children.nudgeOf(sessionID)).inboxID === inboxID)
         return false;
@@ -150,10 +163,10 @@ const TREE_TYPES = [
     "session.deleted",
 ];
 async function sealGroups(ports, event) {
-    // a shutdown stamps no time.idle (api-notes)
-    if (event.data.reason === "shutdown")
-        return;
     try {
+        // a shutdown ends a turn only on a plain decline's aborted step (api-notes)
+        if (event.data.reason === "shutdown" && !endsIdle(await ports.session.context({ sessionID: event.data.sessionID }).catch(() => [])))
+            return;
         if (await hasCompleteGroup(groupStore(ports.storage), event.data.sessionID))
             ports.nudge();
     }

package/dist/tree/group.js

@@ -1,6 +1,6 @@
 import { isNotFound, millis } from "../platform/json.js";
 import { envelope } from "../kernel/protocol.js";
-import { complete, standingOf } from "./domain.js";
+import { complete, endedAt, standingOf, turnEnd } from "./domain.js";
 import { syncStanding } from "./standing.js";
 import { groupStore } from "./store.js";
 import { groupNotice } from "./text.js";
@@ -109,8 +109,11 @@ async function sealed(ports, parentID, members) {
     const joined = Math.max(...members.map((member) => member.joinedAt));
     try {
         const { time } = await ports.session.get({ sessionID: parentID });
-        // only a turn's end stamps time.idle, not a shutdown (api-notes)
-        return millis(time.idle) >= joined;
+        if (millis(time.idle) >= joined)
+            return true;
+        // a plain decline ends the turn on an aborted step, no idle (api-notes)
+        const end = turnEnd(await ports.session.context({ sessionID: parentID }).catch(() => []));
+        return end !== undefined && (endedAt(end, time) ?? Number.NEGATIVE_INFINITY) >= joined;
     }
     catch (error) {
         if (isNotFound(error))

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

@@ -45,8 +45,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]);
+}

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,6 +2,7 @@ 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 lastStatus(children: Notes, sessionID: string): Promise<Status | undefined>;
 export declare function reportOf(children: Notes, sessionID: string): Promise<{
     resumesAt?: number | undefined;

package/dist/tree/report.js

@@ -4,6 +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) {
+    const { prompt, settled } = await children.notes(sessionID, ["prompt", "settled"]);
+    return prompt.at !== undefined && settled.by === "report" && settled.status !== "blocked" && since(settled.at, prompt.at);
+}
 export async function lastStatus(children, sessionID) {
     const { status } = (await children.notes(sessionID, ["settled"])).settled;
     return isStatus(status) ? status : undefined;

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/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;
@@ -73,7 +74,7 @@ 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,12 @@ 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.",
+        "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 +70,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.");
@@ -134,9 +137,11 @@ export const depthRefusal = (depth, maxDepth) => `Not started: this session is a
     "(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");
 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 end your turn and start it once one of them has reported, not in a loop.`;
+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.");
 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 +189,18 @@ 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 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${child.belowTop ? "" : ", a question"} ` +
+            `or a failed turn still reaches you at once.${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}`);
@@ -240,14 +248,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.",
@@ -297,17 +309,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,7 +353,9 @@ 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.",
+        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.",
         ...(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 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, " +
             "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 (per session when ungrouped) in case the reports never come, " +
+            "and courier_cancel it when they arrive: 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"));

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-courier",
-  "version": "0.14.0",
+  "version": "0.15.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>",