opencode-courier 0.13.8 → 0.15.0

package/dist/scheduling/tools.d.ts

@@ -10,5 +10,4 @@ export declare const LaterInput: Schema.Struct<{
 export declare const CancelInput: Schema.Struct<{
     readonly id: Schema.String;
 }>;
-/** Adds `courier_later` and `courier_cancel`. */
 export declare function addSchedulingTools(tools: ToolEditor, later: LaterPorts): void;

package/dist/scheduling/tools.js

@@ -4,10 +4,7 @@ import { cancel, schedule } from "./later.js";
 import { cancelText, laterText } from "./text.js";
 export const LaterInput = Schema.Struct({
     message: Schema.String.annotate({ description: "The message to deliver." }),
-    delayMinutes: Schema.optional(
-    // Some models send the number as a string ("3", "3.0") whatever the schema says, and resend it
-    // unchanged after the error, so a string is accepted and schedule reads it as a number.
-    Schema.Union([Schema.Number, Schema.String]).annotate({
+    delayMinutes: Schema.optional(Schema.Union([Schema.Number, Schema.String]).annotate({
         description: "Deliver this many minutes from now. Give this or at.",
     })),
     at: Schema.optional(Schema.String.annotate({ description: "Deliver at this ISO 8601 time. Give this or delayMinutes." })),
@@ -16,14 +13,14 @@ export const LaterInput = Schema.Struct({
 export const CancelInput = Schema.Struct({
     id: Schema.String.annotate({ description: "The id courier_later returned." }),
 });
-/** Adds `courier_later` and `courier_cancel`. */
 export function addSchedulingTools(tools, later) {
     tools.add({
         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) => {
@@ -38,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.d.ts

@@ -1,20 +1,12 @@
 import type { Plugin } from "@opencode/plugin";
-/** Why a model loads the skill, listed with every session's available skills. */
 export declare const SKILL_DESCRIPTION: string;
-/**
- * The skill's text: how the tools behave, not how to plan or review the parts, which is left to the person's own skills.
- * It names no limits, which the role part and the brief give; it repeats the brief's split rule, since the root has no brief.
- */
 export declare const SKILL_CONTENT: string;
-/** The editor OpenCode hands a skill transform. */
 export type SkillEditor = Parameters<Parameters<Plugin.Context["skill"]["transform"]>[0]>[0];
-/** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */
 export declare const orchestrateSkill: () => {
     readonly id: "courier-orchestrate";
     readonly name: "courier-orchestrate";
     readonly description: string;
-    readonly path: "/opencode-courier/courier-orchestrate.md";
+    readonly path: "skill://courier-orchestrate/SKILL.md";
     readonly content: string;
 };
-/** Adds the courier-orchestrate skill; every instance adds the same one, under the same id. */
 export declare function addSkill(skills: SkillEditor): void;

package/dist/skill.js

@@ -1,122 +1,65 @@
 import { ONE_PART_LINE, SKILL_ID, SPLIT_LINE } from "./kernel/protocol.js";
-// The courier-orchestrate skill: the text a session loads with its skill tool.
-/** Why a model loads the skill, listed with every session's available skills. */
-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.";
-/**
- * The skill's text: how the tools behave, not how to plan or review the parts, which is left to the person's own skills.
- * It names no limits, which the role part and the brief give; it repeats the brief's split rule, since the root has no brief.
- */
+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. Until it reports, " +
-        "it counts toward the limits.",
-    "- A refusal from courier_spawn naming maxDepth, maxChildren or maxTotal: do that part yourself, or end your turn and " +
-        "start it once a report has arrived. Do not retry it in a loop.",
-    "- Lost track, after a compaction or a restart: one courier_tree shows every session under you with its depth, its " +
-        "parent and whether it still owes a report; one look, not a loop.",
-    "- A subtree that went wrong or is no longer needed: courier_stop its top session; everything under it is stopped " +
-        "too, and nothing in it reports back. cleanup: true removes their worktrees.",
+    "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's path is where OpenCode would look for its files; this one has none, so a path of the plugin's own. */
-const SKILL_PATH = `/opencode-courier/${SKILL_ID}.md`;
-/** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */
+// A skill:// path: the read tool serves it from the registry (api-notes)
+const SKILL_PATH = `skill://${SKILL_ID}/SKILL.md`;
 export const orchestrateSkill = () => ({ id: SKILL_ID, name: SKILL_ID, description: SKILL_DESCRIPTION, path: SKILL_PATH, content: SKILL_CONTENT });
-/** Adds the courier-orchestrate skill; every instance adds the same one, under the same id. */
 export function addSkill(skills) {
     skills.add(orchestrateSkill());
 }

package/dist/tree/cleanup.d.ts

@@ -3,31 +3,11 @@ export interface CleanupInput {
     readonly sessionID: string;
     readonly force?: boolean;
 }
-/** At most this many changes and commits are returned; the reason still counts them all. */
 export declare const MAX_LISTED = 50;
-/**
- * Forgets a child the parent started, removing its worktree if it is isolated. A worktree with uncommitted changes
- * or commits found nowhere else is kept unless `force` is set; the result says so.
- */
 export declare function cleanup(ports: CleanupPorts, parentID: string, input: CleanupInput): Promise<CleanupResult>;
-/** Names the git to run, by absolute path, overriding the places `GIT_LOCATIONS` lists. */
 export declare const GIT_ENV = "OPENCODE_COURIER_GIT";
-/**
- * Where git is looked for, in order: its usual install locations, never `PATH`, so a writable
- * directory early in `PATH` cannot put another program in its place.
- */
 export declare const GIT_LOCATIONS: Readonly<Record<"posix" | "win32", readonly string[]>>;
-/**
- * The git to run: `OPENCODE_COURIER_GIT` when it is an absolute path, otherwise the first of
- * `GIT_LOCATIONS` that exists. Throws when there is none.
- */
 export declare function findGit(env?: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform, exists?: (path: string) => boolean): string;
-/** The commit a worktree is on, or undefined when git cannot tell. */
 export declare function headOf(directory: string): Promise<string | undefined>;
-/** Whether a worktree has uncommitted changes, untracked files included; undefined when git cannot tell. */
 export declare function dirtyOf(directory: string): Promise<boolean | undefined>;
-/**
- * Reads a worktree's state with git; undefined when the directory is gone. Commits reachable from
- * `base`, the commit the worktree was made from, are not its own work and are not listed.
- */
 export declare function inspectWorktree(directory: string, base?: string): Promise<WorktreeState | undefined>;

package/dist/tree/cleanup.js

@@ -5,18 +5,12 @@ import { forgetDropped } from "./forget.js";
 import { syncStanding } from "./standing.js";
 import { childStore } from "./store.js";
 import { keepReason } from "./text.js";
-/** At most this many changes and commits are returned; the reason still counts them all. */
 export const MAX_LISTED = 50;
-/**
- * Forgets a child the parent started, removing its worktree if it is isolated. A worktree with uncommitted changes
- * or commits found nowhere else is kept unless `force` is set; the result says so.
- */
 export async function cleanup(ports, parentID, input) {
     const entry = await childStore(ports.storage).entry(parentID, input.sessionID);
     if (!entry)
         throw new Error(`${input.sessionID} is not on the courier_children list of ${parentID}.`);
     const { directory } = entry;
-    // A member still out is dropped from its group, so the group is released without it; the result names that group.
     const forget = async () => {
         const group = await forgetDropped(ports, entry);
         await syncStanding(ports, parentID);
@@ -24,8 +18,6 @@ export async function cleanup(ports, parentID, input) {
     };
     if (!entry.isolated)
         return { sessionID: input.sessionID, directory, outcome: "forgotten", ...(await forget()) };
-    // With force the state only decides whether there is anything left to remove, so a worktree git
-    // can no longer read is still removed.
     const state = await ports
         .inspect(directory, entry.base)
         .catch((error) => (input.force ? { changes: [], commits: [] } : Promise.reject(error)));
@@ -48,26 +40,16 @@ export async function cleanup(ports, parentID, input) {
     });
     return { sessionID: input.sessionID, directory, outcome: "removed", ...(await forget()) };
 }
-/** Names the git to run, by absolute path, overriding the places `GIT_LOCATIONS` lists. */
 export const GIT_ENV = "OPENCODE_COURIER_GIT";
-/**
- * Where git is looked for, in order: its usual install locations, never `PATH`, so a writable
- * directory early in `PATH` cannot put another program in its place.
- */
 export const GIT_LOCATIONS = {
     posix: [
         "/usr/bin/git",
         "/usr/local/bin/git",
         "/opt/homebrew/bin/git",
-        // NixOS, and nix-darwin.
         "/run/current-system/sw/bin/git",
     ],
     win32: [String.raw `C:\Program Files\Git\cmd\git.exe`, String.raw `C:\Program Files (x86)\Git\cmd\git.exe`],
 };
-/**
- * The git to run: `OPENCODE_COURIER_GIT` when it is an absolute path, otherwise the first of
- * `GIT_LOCATIONS` that exists. Throws when there is none.
- */
 export function findGit(env = process.env, platform = process.platform, exists = existsSync) {
     const named = env[GIT_ENV]?.trim();
     if (named) {
@@ -84,29 +66,21 @@ export function findGit(env = process.env, platform = process.platform, exists =
 function git(directory, args) {
     return new Promise((resolve, reject) => execFile(findGit(), ["-C", directory, ...args], { maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => error ? reject(new Error(`git ${args[0]} in ${directory}: ${stderr.trim() || error.message}`)) : resolve(stdout)));
 }
-/** The commit a worktree is on, or undefined when git cannot tell. */
 export function headOf(directory) {
     return git(directory, ["rev-parse", "HEAD"]).then((out) => out.trim() || undefined, () => undefined);
 }
-/** Whether a worktree has uncommitted changes, untracked files included; undefined when git cannot tell. */
 export function dirtyOf(directory) {
     return git(directory, ["status", "--porcelain"]).then((out) => out.trim().length > 0, () => undefined);
 }
-/**
- * Reads a worktree's state with git; undefined when the directory is gone. Commits reachable from
- * `base`, the commit the worktree was made from, are not its own work and are not listed.
- */
 export async function inspectWorktree(directory, base) {
     if (!existsSync(directory))
         return undefined;
-    // An untracked directory is one entry, not every file in it.
     const status = await git(directory, ["status", "--porcelain=v1", "-z", "--untracked-files=normal"]);
     const changes = [];
     const records = status.split("\0").filter(Boolean);
     for (let i = 0; i < records.length; i++) {
         const record = records[i];
         changes.push(record.slice(3));
-        // A rename or copy is followed by its source path in a record of its own.
         if ("RC".includes(record[0]) || "RC".includes(record[1]))
             i++;
     }

package/dist/tree/context.d.ts

@@ -1,5 +1,4 @@
 import type { ContextPorts } from "./ports.js";
-/** The part of a session context this hook changes. */
 export interface Shaped {
     readonly sessionID: string;
     tools: Record<string, unknown>;
@@ -8,8 +7,4 @@ export interface Shaped {
         text: string;
     }>;
 }
-/**
- * The `context` hook: hides courier_spawn and the tools named `hiddenFromLeaf` from a session at `maxDepth`, and names a
- * session's role in a system part unless its `role` entry does; a session nobody spawned that has started none is pointed to the skill.
- */
 export declare function shapeContext(ports: ContextPorts, event: Shaped): Promise<void>;

package/dist/tree/context.js

@@ -1,22 +1,17 @@
 import { setBounded } from "../platform/bounded.js";
 import { childStore } from "./store.js";
 import { ROLE_KEY, ROLE_PREFIX, rolePart } from "./text.js";
-/** How many sessions' roles an instance remembers. */
 const ROLES_MAX = 1000;
-/** A role part, or the role entry's block, already in the system prompt, wherever its part begins. */
 const ROLE_LINE = new RegExp(`^${ROLE_PREFIX}`, "m");
-/**
- * The `context` hook: hides courier_spawn and the tools named `hiddenFromLeaf` from a session at `maxDepth`, and names a
- * session's role in a system part unless its `role` entry does; a session nobody spawned that has started none is pointed to the skill.
- */
 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) });
@@ -25,19 +20,28 @@ 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;
-    // The reverse index alone: a scan here would run for every session's first request, courier or not.
     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;
 }
-/** Whether the session carries the role entry, listed when its role is looked up; one that cannot be read gets the part. */
 async function hasEntry(ports, sessionID) {
     if (!ports.instructions)
         return false;

package/dist/tree/domain.d.ts

@@ -1,37 +1,23 @@
-/**
- * The tree's pure rules, on plain data: the limits, a session's lineage, whether it runs, and a group
- * member's standing. Imports nothing of the plugin's but `kernel/` and `platform/json.ts`.
- */
 import type { Plugin } from "@opencode/plugin";
 import type { Status } from "../kernel/protocol.js";
 type Context = Plugin.Context;
-/** The limits on the tree of sessions courier_spawn builds, from the plugin's options. */
 export interface Limits {
     readonly maxDepth: number;
     readonly maxChildren: number;
     readonly maxTotal: number;
 }
 export declare const DEFAULT_LIMITS: Limits;
-/** The limits in the plugin's options; one that is not a positive integer keeps its default and is named in `problems`. */
 export declare function readLimits(options: unknown): {
     limits: Limits;
     problems: string[];
 };
-/** The `nativeChildren` option: whether a child started without isolate or `native` gets OpenCode's own `parentID`; off unless `true`. */
 export declare function readNativeChildren(options: unknown): {
     nativeChildren: boolean;
     problems: string[];
 };
-/** A session's times, as `session.get` gives them. */
 type Times = Awaited<ReturnType<Context["session"]["get"]>>["time"];
-/** A session's times as `busy` reads them; `busy`, when its latest execution started, is stamped since OpenCode 2.2.2. */
 export type BusyTimes = Pick<Times, "updated" | "idle" | "busy">;
-/**
- * Whether a session may run by its times: it has never finished a turn, or its latest execution started after the last one ended
- * (`busy`; without it `updated`, which a rename, an archive or a waiting inbox item also stamp); only its transcript then tells.
- */
 export declare const busy: (time: BusyTimes) => boolean;
-/** A stored message as `turnEnd` reads it: an assistant message's `error` says how its step ended. */
 type Stored = {
     readonly type: string;
     readonly error?: {
@@ -42,50 +28,26 @@ type Stored = {
         readonly completed?: unknown;
     };
 };
-/**
- * The message a transcript's last turn ended on, unless one runs, past asides made since: an `idle` message, or a step
- * interrupted with none after it, as a declined permission or dismissed question ends a turn, recording no `idle` (#326).
- */
 export declare function turnEnd<M extends Stored>(messages: ReadonlyArray<M>): M | undefined;
 export declare const endsIdle: (messages: ReadonlyArray<Stored>) => boolean;
-/** When the turn `end` ended: the session's idle time for an `idle` message, else when its interrupted step ended. */
 export declare function endedAt(end: Stored, time: BusyTimes): number | undefined;
-/**
- * Whether a session of a tree read is live, for a cut listing's order: it runs (its turn not failed or interrupted since its last
- * prompt), waits on a request or form, or owes a report, but not, unlike for the limits, for a message waiting in its inbox.
- */
 export declare const isLive: (running: boolean | undefined, waits: number, report: {
     readonly owes: boolean;
     readonly ended: boolean;
 } | undefined) => boolean;
-/** A session of a tree read, as `cut` takes it: where it is in the tree, when it was started, and whether it is live. */
 export interface Cuttable {
     readonly sessionID: string;
     readonly parentID: string;
     readonly createdAt: number;
     readonly live: boolean;
 }
-/**
- * Which sessions a listing of at most `max` keeps, of a tree read in the order it is drawn: the live ones first, then
- * the newest, each with the sessions above it so the tree still draws; `leftOut` counts the rest.
- */
 export declare function cut<T extends Cuttable>(nodes: ReadonlyArray<T>, max: number): {
     kept: T[];
     leftOut: number;
 };
-/**
- * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
- * except isolated children whose worktree is still there: those stay until courier_cleanup.
- */
 export declare const RETENTION_MS: number;
-/** Whether a directory still exists; tests pass a fake. */
 export type Exists = (directory: string) => boolean;
-/**
- * Whether an entry is past retention at `now`: recorded more than `RETENTION_MS` before, unless it is an isolated
- * child whose worktree exists, which is kept so it can still be cleaned up.
- */
 export declare const isExpired: (entry: RosterEntry, now: number, exists: Exists) => boolean;
-/** A session started with courier_spawn, recorded under the session that started it. */
 export interface RosterEntry {
     readonly sessionID: string;
     readonly parentID: string;
@@ -93,49 +55,30 @@ export interface RosterEntry {
     readonly directory: string;
     readonly isolated: boolean;
     readonly createdAt: number;
-    /** For an isolated child, the directory its worktree was made from; for the record, nothing acts on it. */
     readonly source?: string;
-    /** For an isolated child, the project its worktree belongs to; courier_cleanup removes it from there. */
     readonly project?: string;
-    /** For an isolated child, the commit its worktree was made from; its own work is what came after. */
     readonly base?: string;
-    /** `"status"` when its brief asked for a report with a status; absent for a child an earlier release briefed. */
     readonly reports?: "status";
-    /** The join group courier_spawn put it in, whose release holds its report; absent for a child in none. */
     readonly group?: string;
-    /** Created with OpenCode's own `parentID` (courier_spawn's `native`, else the `nativeChildren` option), so OpenCode shows its asks in its parent's view. */
     readonly native?: true;
-    /** The model it was started on, as `modelName` writes it, when that is not the model its parent was on. */
     readonly model?: string;
 }
-/** How a child was started, as courier_children and the panel show it: isolated, native when it is, and its model when not its parent's. */
 export declare function startedAs(entry: RosterEntry): {
     model?: string | undefined;
     native?: true | undefined;
     isolated: boolean;
 };
-/** A model as a session names it: its provider, its id, and its variant, which `"default"` and none both leave to the provider. */
 export interface ModelRef {
     readonly providerID: string;
     readonly id: string;
     readonly variant?: string;
 }
-/** `provider/model` as `courier_spawn` takes it: one slash, nothing empty on either side. */
 export declare function parseModelName(text: string): Pick<ModelRef, "providerID" | "id"> | undefined;
-/** A model as the roster, the panel and the results name it: `provider/model`, with `#variant` for a variant that is not the default. */
 export declare function modelName(model: ModelRef): string;
-/** `lineage` over roster entries already read. */
 export declare function lineageIn(entries: ReadonlyArray<RosterEntry>, sessionID: string): RosterEntry[];
-/** Roster entries by their session, for `lineageBy`. */
 export declare function bySession(entries: ReadonlyArray<RosterEntry>): Map<string, RosterEntry>;
-/** `lineage` over roster entries already read and mapped by `bySession`. */
 export declare function lineageBy(bySession: ReadonlyMap<string, RosterEntry>, sessionID: string): RosterEntry[];
-/**
- * The session whose view OpenCode shows the asks of a lineage's first session in: up its native parents, to the
- * first session that is not a native child (an isolated one, or the top). The session itself when it is not native.
- */
 export declare function nativeRootOf(chain: ReadonlyArray<RosterEntry>): string;
-/** What a report lists besides its text; `checks` are the commands the session ran and what each gave. */
 export interface Artifacts {
     readonly branch?: string;
     readonly commits?: ReadonlyArray<string>;
@@ -145,21 +88,18 @@ export interface Artifacts {
         readonly result: string;
     }>;
 }
-/** A report held with its group: its status, text and artifacts, as courier_send was given them, and when. */
 export interface HeldReport {
     readonly at: number;
     readonly status: Status;
     readonly message: string;
     readonly artifacts?: Artifacts;
 }
-/** A member of a group that left it without a report, and why: its turn failed or was interrupted, it was deleted, or courier_cleanup dropped it. */
 export interface LeftMember {
     readonly sessionID: string;
     readonly title: string;
     readonly by: "failed" | "interrupted" | "deleted" | "dropped";
 }
 export declare const isGroupName: (value: unknown) => value is string;
-/** A member of a group, as stored: its title for the release notice, and its report or how it left. */
 export interface Member {
     readonly title: string;
     readonly joinedAt: number;
@@ -169,13 +109,9 @@ export interface Member {
         readonly by: LeftMember["by"];
     };
 }
-/** What is known of a member's standing: its report is held, still out, or it left, or it is no longer in an open group. */
 export type Standing = "held" | "out" | LeftMember["by"] | "released";
-/** A member's standing from its stored value, or `released` when there is none. */
 export declare function standingOf(member: Member | undefined): Standing;
-/** Whether every member of a group has a held report or has left: released once the parent's turn has ended. */
 export declare const complete: (members: ReadonlyArray<Member>) => boolean;
-/** How long the provider asked to wait after a failed turn, if it did: a positive number of milliseconds, at most `RETRY_MAX_MS`. */
 export declare function retryDelay(error: {
     readonly retryAfterMs?: unknown;
 }): number | undefined;