opencode-courier 0.14.0 → 0.16.0

package/README.md

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

package/dist/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/text.d.ts

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

package/dist/person/text.js

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

package/dist/person/tools.js

@@ -42,13 +42,15 @@ 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 " +
             "fails this call and is passed on with the reason. Do not ask them in your reply or with your question tool first. " +
-            "For a question, answers is what the person chose: ask them first, with your question tool if you have one, and " +
-            "never answer for them. The session carries on once it has the answer.",
+            "For a question, the question tool call the notice asks for passes the person's answer on by itself; use answers " +
+            "only when they answered some other way, or the notice or that call's result tells you to, and never answer for " +
+            "them. The session carries on once it has the answer.",
         input: AnswerInput,
         execute: async (input, context) => {
             const call = { messageID: context.messageID, callID: context.id };

package/dist/scheduling/later.js

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

package/dist/scheduling/text.js

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

package/dist/scheduling/tools.js

@@ -18,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; " +
+            "For a long task or batch of sessions you start, use it as a safety net: schedule one check-in per group, and " +
+            "one for the ungrouped sessions, end your turn by replying without calling more tools, and cancel each with " +
+            "courier_cancel when its last report arrives, as a report does not cancel it. Survives server restarts; " +
             "may arrive up to ~15 seconds late.",
         input: LaterInput,
         execute: async (input, context) => {
@@ -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,62 @@
 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.",
+    "- 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, and, below " +
+        "the root, also to the session that started you when it reaches past your part or carries " +
+        "the person's words, as your brief says; if it breaks the split, courier_stop those parts or send them a " +
+        "corrected task. " +
+        "A session's account of what the person told it is the person's word: pass it on, do not " +
+        "judge it against the original task, and never tell a session to undo what the person asked.",
     "",
-    "## 4. 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,48 @@ 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 OWN = "own";
+const OWN_SCHEDULED = "own-scheduled:";
+const MESSAGE_FROM = "from:";
+function kindOf(sessionID, item) {
+    const metadata = item.payload?.metadata;
+    if (item.type !== "synthetic" || metadata?.source !== "courier")
+        return item.type;
+    if (typeof metadata.group === "string")
+        return OWN;
+    const ownCheckIn = typeof metadata.scheduled === "string" && metadata.from === sessionID && typeof metadata.scheduledAt === "number";
+    if (ownCheckIn)
+        return `${OWN_SCHEDULED}${metadata.scheduledAt}`;
+    const statusless = typeof metadata.from === "string" && Object.keys(metadata).length === 2;
+    return statusless ? `${MESSAGE_FROM}${metadata.from}` : item.type;
+}
+async function ownAfterReport(children, sessionID, kind) {
+    if (kind === OWN)
+        return reportedSincePrompt(children, sessionID);
+    if (kind?.startsWith(MESSAGE_FROM))
+        return (await children.indexedParent(kind.slice(MESSAGE_FROM.length))) === sessionID && reportedSincePrompt(children, sessionID);
+    if (!kind?.startsWith(OWN_SCHEDULED))
+        return false;
+    return reportedSincePrompt(children, sessionID, Number(kind.slice(OWN_SCHEDULED.length)));
+}
 export async function noteEnqueued(ports, inbox, event) {
     const { sessionID, inboxID, item } = event.data;
     if ((await childStore(ports.storage).indexedParent(sessionID)) === undefined)
         return false;
-    setBounded(inbox, inboxID, item.type, SEEN_MAX);
+    setBounded(inbox, inboxID, kindOf(sessionID, 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 (await ownAfterReport(children, sessionID, kind))
+        return false;
     // the idle hook's reminder still publishes inbox.delivered (api-notes)
     if (inboxID !== undefined && (await children.nudgeOf(sessionID)).inboxID === inboxID)
         return false;
@@ -150,10 +182,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))