opencode-courier 0.11.1 → 0.13.0

package/dist/skill.d.ts

@@ -3,7 +3,7 @@ import type { Plugin } from "@opencode/plugin";
 export declare const SKILL_DESCRIPTION: string;
 /**
  * The skill's text; it names no limits, which the role part and the brief give for the session's own tree.
- * Steps 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
+ * Steps 1, 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
  */
 export declare const SKILL_CONTENT: string;
 /** The editor OpenCode hands a skill transform. */

package/dist/skill.js

@@ -1,66 +1,118 @@
 import { ONE_PART_LINE, SKILL_ID, SPLIT_LINE } from "./kernel/protocol.js";
 // The courier-orchestrate skill: the playbook a session loads with its skill tool.
 /** Why a model loads the skill, listed with every session's available skills. */
-export const SKILL_DESCRIPTION = "Load at the start of any implementation task that may have independent parts, or when a session started you, to " +
-    "decide whether to split it across OpenCode sessions with courier_spawn and state the decision, and how: plan the " +
-    "parts, start them, end your turn, read the reports, verify the work, integrate it and report upward, and what to do " +
-    "when a part goes wrong.";
+export const SKILL_DESCRIPTION = "Load at the start of any implementation task that may have independent parts, or when a session started you, if " +
+    "courier_spawn is among your tools: how to decide whether to split it across OpenCode sessions and state the decision, " +
+    "plan and start the parts, end your turn, verify and integrate the reports, report upward, and handle a part gone wrong.";
 /**
  * The skill's text; it names no limits, which the role part and the brief give for the session's own tree.
- * Steps 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
+ * Steps 1, 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
  */
 export const SKILL_CONTENT = [
     "How to split a task across OpenCode sessions with opencode-courier, and bring the results back up. Your brief, or the " +
-        "opencode-courier role line in your system prompt, names your depth in the session tree and its limits.",
+        "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.",
     "",
-    "1. Decide: split or do. First call courier_recall once: it lists how earlier trees in this project were split and how " +
-        "each part went, so weigh that; one call, before you decide, never in a loop. 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. What you read and write yourself stays in your context for every later turn, so keep the deciding, " +
-        "checking and integrating, and hand off the long reading and writing. 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 (steps 5 to 7), " +
-        "and does a small task 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. A part that is itself big and divisible is split again by " +
-        "the session that gets it; at the deepest level a session does its part itself. " +
-        `Say which in one line of your reply, before you start, so that a reasoned decision to do it yourself can be told ` +
-        `from one never made: ${SPLIT_LINE}; the root has a third form, ${ONE_PART_LINE}.`,
-    "   When the core is coupled: an implementation task with one tightly coupled core usually still has independent parts: " +
-        "finding out what the change needs (a session with isolate: false reads the code, or a library's or a host's source, " +
-        "tries things and reports what it found), its e2e scenario, its documentation, sometimes a second test file, and a " +
-        "review of the core by a session with fresh context, which reads the committed diff against the task and the " +
-        "repository's rules and reports its findings (isolate: false, it edits nothing). Weigh each of them. When the other " +
-        "parts depend on names and texts the core fixes, split in stages: the core first, yourself when it is small or by one " +
-        "session when it is big, merged and committed before the rest start; then, if 2 or more parts remain, one session per " +
-        "remaining part, in one group. A staged core is one part of the task, not the whole task, so the rule against starting exactly one " +
-        "session for the whole task does not apply to it when 2 or more parts follow it.",
+    "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 playbook for its job, stages, review and all, so the tree below you repeats its shape once per job.",
+    "   - What you read and write yourself stays in your context for every later turn: keep the deciding, checking and " +
+        "integrating, and hand off the long reading and writing.",
+    "   - 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 (steps 5 to 7). 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.",
+    `   - Say which in one line of your reply, before you start: ${SPLIT_LINE}; the root has a third form, ${ONE_PART_LINE}.`,
+    "   Parts a task can have, besides its edits, each one session where it is worth a context of its own:",
+    "   - a scout: a session with isolate: false reads the code, or a library's or a host's source, tries things and " +
+        "reports what it found, before you plan;",
+    "   - the implementers, isolate: true where two edit at once, each with its checks and what to report;",
+    "   - its e2e scenario, its documentation, sometimes a second test file;",
+    "   - a review stage, after the merge, to see the whole: one review session with fresh context, which makes no fixes " +
+        "of its own. Put in its task the diff to read: your checkout's HEAD, with the " +
+        "merges committed, against the commit you started from, which you note before your first spawn; when you are " +
+        "isolated, your own courier/<session> branch, committed first, against the commit your worktree started from. It " +
+        "may hand the reading to 2 or more reviewers (one group, each reads the diff from one angle and reports its " +
+        "findings), then starts one verifier with their reports: a fresh session that checks each finding against the diff, " +
+        "drops what does not hold, and starts one implementor for what holds, or 2 or more with isolate: true when the fixes " +
+        "are independent, merging their branches after (step 7); an implementor fixes what it should and refuses, with the " +
+        "reason, what it should not. In the project's checkout, the review session, the verifier and a lone implementor go " +
+        "without isolate and commit in place; when you are isolated, start each of them with isolate: true, so that each " +
+        "worktree starts from the one above; reviewers only read and need no worktree. The review session reports to you " +
+        "what was found, what held, what was fixed (the commits) and what was refused and why. It does not replace step 6: " +
+        "running the checks on the fixed tree stays yours, and so does settling a refusal you disagree with. Go through " +
+        "steps 3 to 7 once more for the stage, and do its work yourself when the levels below you are too few for it. One " +
+        "session for one stage, after a stage of 2 or more parts or one you did yourself, is a part of the task, not the " +
+        "whole; a reviewer alone with nothing before it is not a stage.",
+    "   When the core is coupled: a task with one tightly coupled core usually still has parts from that list; weigh each. " +
+        "When the rest depend on names and texts the core fixes, split in stages: the core first, yourself when it is small " +
+        "or by one session when it is big, merged and committed before the rest start; then, if 2 or more parts remain, one " +
+        "session per part, in one group. A staged core is one part of the task, not the whole task, when 2 or more parts " +
+        "follow it.",
     "2. Plan the parts so that no two edit the same files. Write each task so the session can do it without you: what to " +
         "produce and where, how to check it, what to report. Say if it may split its part further, and to run its checks " +
-        "through the project's scripts (step 6): each permission request of a session below you wakes you and waits on the person.",
-    "3. Start them: one courier_spawn per part that runs at once, all with the same group name, so you are woken once with every report; " +
-        "isolate: true for each part that edits files in parallel with another (commit your own work first if you are isolated " +
-        "yourself). For long work, courier_later a check-in for yourself, and courier_cancel it when the reports arrive.",
-    "4. End your turn: reply without calling more tools. Do not poll with courier_status, courier_children, courier_tree or " +
-        "sleep. The group's reports, a blocked report, a question, a permission request, a failed turn or a silent end each start " +
-        "a new turn for you.",
+        "through the project's scripts (step 6), since each permission request below you wakes you and waits on the person. " +
+        "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 in the task when the part is a whole job " +
+        "that delivers itself (step 7), since an isolated session's brief otherwise says its branch is for you to merge.",
+    "3. Start them: one courier_spawn per part that runs at once, all with the same group name, so that you are woken once " +
+        "with every report, and isolate: true for each part that edits files in parallel with another. When each part runs " +
+        "a review stage of its own, count 6 live sessions per part against maxTotal (a part, its review session and its " +
+        "reviewers are live together at the peak): start the parts that fit in one group, and the rest in a group of their " +
+        "own once the first group has reported. A job that depends on another starts after that one is done, as a stage: " +
+        "merged into your checkout, or, when it was delivered instead (step 7), started with isolate: true and told the " +
+        "delivering session's courier/<session> branch, from its report, to merge first. " +
+        "Leave model and variant unset, so a part runs on your own model, unless the part plainly calls for another: a " +
+        "cheaper model or a lower variant for a small, well-specified part (a rename, a lookup), a stronger model or a higher " +
+        "variant for a design question or a hard bug. " +
+        "native: true for a part nobody needs to open on its own: it reads, checks or looks something up, reports once and is " +
+        "done; leave it off for a part the person may want to open, or that should outlive you. " +
+        "For long work, courier_later a check-in for yourself, and courier_cancel it when the reports arrive.",
+    "4. 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; so does a message from the person or from the session " +
+        "that started you.",
+    "   Answering from below: follow the notice. For 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 in your session. For 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 (an assumption of the split that is wrong, a shared file " +
+        "or API that behaves otherwise, a decision of the person's), pass it on at once with courier_send, only to the sessions " +
+        "it affects, before they go further, then end your turn again; if it breaks the split, courier_stop the parts it breaks " +
+        "and plan them again, or send them a corrected task. Send it up too, without a status, when the other parts of the " +
+        "session that started you need it. Progress that changes nothing for the others goes to no one. A session's account " +
+        "of what the person told it is the person's word: pass it on to the parts it affects, do not judge it against the " +
+        "original task, and never tell a session to undo what the person asked.",
     "5. Read each report by its status and its artifacts (branch, commits, files, checks). 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.",
-    "6. Verify first-hand: open the files, run the checks. Never hand the checking to another session: a review session's " +
-        "findings are a report to act on, and running the checks is still yours. Run checks through " +
+        "failed: read the error; message the session to try again, start a replacement, or carry on without it. A review " +
+        "stage's report lists what was found, held, fixed and refused: read the refusals, fix or settle yourself any you " +
+        "disagree with, and run the checks on the fixed tree.",
+    "6. Verify first-hand: open the files, run the checks. Never hand the checking to another session: a review stage " +
+        "verifies and fixes below you, and running the checks on what it changed is still yours. Run checks through " +
         "the project's scripts (bun run <script>, npm run <script>), not ./node_modules/.bin/<tool>, so that one permission " +
         "rule covers them: your own permission prompts are relayed nowhere, and each one stalls the whole tree.",
     "7. 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.",
+        "yourself, run the checks once more, then courier_cleanup the isolated sessions you are done with. When the parts are " +
+        "whole jobs with a deliverable each (a ticket with its own branch or pull request), the session delivers it and " +
+        "reports the link, still naming its courier/<session> branch when it is isolated; you verify each delivery and merge " +
+        "nothing of it into your checkout.",
     "8. 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; partial, blocked or failed otherwise) and the artifacts. At the top, before you reply " +
-        "to the person: if there is something the next tree in this project should know about running a tree like this one (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 that 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 again shorter. A rule that holds every time goes to AGENTS.md or the skill, through the person, not " +
-        "into a note. Then reply to the person.",
+        "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 there is something the next tree in this project should know about " +
+        "running a tree like this one (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 that 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 again shorter. A rule that holds every time goes to AGENTS.md or " +
+        "the skill, through the person, not into a note. Then reply to the person.",
     "",
     "When a part goes wrong:",
     "- A failed turn (failed=\"...\") or a silent end (ended=\"without-report\", quoting the session's last reply): message " +

package/dist/tree/cleanup.js

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { isAbsolute } from "node:path";
 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. */
@@ -18,6 +19,7 @@ export async function cleanup(ports, parentID, input) {
     // 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);
         return group ? { group } : {};
     };
     if (!entry.isolated)

package/dist/tree/context.d.ts

@@ -9,7 +9,7 @@ export interface Shaped {
     }>;
 }
 /**
- * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn, and the tools
- * named `hiddenFromLeaf`, from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ * 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,28 +1,31 @@
 import { setBounded } from "../platform/bounded.js";
 import { childStore } from "./store.js";
-import { ROLE_PREFIX, rolePart } from "./text.js";
-/** How many sessions' depths an instance remembers. */
+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: names a session's role in its tree in a system part, and hides courier_spawn, and the tools
- * named `hiddenFromLeaf`, from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ * 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 = await depthOf(ports, event.sessionID);
+        const { depth, entry } = await roleOf(ports, event.sessionID);
         if (depth === null && !event.tools.courier_spawn)
             return;
         if (depth !== null && depth >= ports.limits.maxDepth)
             for (const tool of ["courier_spawn", ...(ports.hiddenFromLeaf ?? [])])
                 delete event.tools[tool];
-        if (!event.system.some((part) => part.text.startsWith(ROLE_PREFIX)))
-            event.system.push({ type: "text", text: rolePart(depth, ports.limits) });
+        if (entry || event.system.some((part) => ROLE_LINE.test(part.text)))
+            return;
+        event.system.push({ type: "text", text: rolePart(depth, ports.limits) });
     }
     catch (error) {
         ports.log(`courier: cannot tell the role of session ${event.sessionID}: ${String(error)}`);
     }
 }
-async function depthOf(ports, sessionID) {
+async function roleOf(ports, sessionID) {
     const known = ports.roles.get(sessionID);
     if (known !== undefined)
         return known;
@@ -30,6 +33,19 @@ async function depthOf(ports, sessionID) {
     const children = childStore(ports.storage);
     const chain = await children.indexedLineage(sessionID);
     const depth = chain.length || ((await children.children(sessionID)).length ? 0 : null);
-    setBounded(ports.roles, sessionID, depth, ROLES_MAX);
-    return depth;
+    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;
+    try {
+        return (await ports.instructions.entry.list({ sessionID })).some((entry) => entry.key === ROLE_KEY);
+    }
+    catch (error) {
+        ports.log(`courier: cannot read the instruction entries of session ${sessionID}, so its role goes in a system part: ${String(error)}`);
+        return false;
+    }
 }

package/dist/tree/domain.d.ts

@@ -17,7 +17,7 @@ export declare function readLimits(options: unknown): {
     limits: Limits;
     problems: string[];
 };
-/** The `nativeChildren` option: whether a child started without isolate gets OpenCode's own `parentID`; off unless `true`. */
+/** 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[];
@@ -73,6 +73,18 @@ export declare function cut<T extends Cuttable>(nodes: ReadonlyArray<T>, max: nu
     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;
@@ -91,9 +103,27 @@ export interface RosterEntry {
     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` (the `nativeChildren` option), so OpenCode shows its asks in its parent's view. */
+    /** 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`. */

package/dist/tree/domain.js

@@ -1,5 +1,5 @@
 import { millis, obj } from "../platform/json.js";
-export const DEFAULT_LIMITS = { maxDepth: 3, maxChildren: 5, maxTotal: 20 };
+export const DEFAULT_LIMITS = { maxDepth: 5, maxChildren: 5, maxTotal: 30 };
 /** The limits in the plugin's options; one that is not a positive integer keeps its default and is named in `problems`. */
 export function readLimits(options) {
     const given = obj(options);
@@ -16,7 +16,7 @@ export function readLimits(options) {
     const limits = { maxDepth: read("maxDepth"), maxChildren: read("maxChildren"), maxTotal: read("maxTotal") };
     return { limits, problems };
 }
-/** The `nativeChildren` option: whether a child started without isolate gets OpenCode's own `parentID`; off unless `true`. */
+/** The `nativeChildren` option: whether a child started without isolate or `native` gets OpenCode's own `parentID`; off unless `true`. */
 export function readNativeChildren(options) {
     const value = obj(options).nativeChildren;
     if (value === undefined || typeof value === "boolean")
@@ -70,6 +70,32 @@ export function cut(nodes, max) {
     }
     return { kept: nodes.filter((node) => kept.has(node.sessionID)), leftOut: nodes.length - kept.size };
 }
+/**
+ * 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 const RETENTION_MS = 14 * 24 * 60 * 60_000;
+/**
+ * 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 const isExpired = (entry, now, exists) => now - entry.createdAt > RETENTION_MS && !(entry.isolated && exists(entry.directory));
+/** 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 function startedAs(entry) {
+    return { isolated: entry.isolated, ...(entry.native ? { native: true } : {}), ...(entry.model ? { model: entry.model } : {}) };
+}
+/** `provider/model` as `courier_spawn` takes it: one slash, nothing empty on either side. */
+export function parseModelName(text) {
+    const slash = text.indexOf("/");
+    if (slash <= 0 || slash === text.length - 1)
+        return undefined;
+    return { providerID: text.slice(0, slash), id: text.slice(slash + 1) };
+}
+/** 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 function modelName(model) {
+    const variant = model.variant && model.variant !== "default" ? `#${model.variant}` : "";
+    return `${model.providerID}/${model.id}${variant}`;
+}
 /** `lineage` over roster entries already read. */
 export function lineageIn(entries, sessionID) {
     return lineageBy(bySession(entries), sessionID);

package/dist/tree/events.js

@@ -4,6 +4,7 @@ import { endsIdle, retryDelay } from "./domain.js";
 import { forgetChild, forgetDeleted } from "./forget.js";
 import { hasCompleteGroup, leave, outIn } from "./group.js";
 import { awaited, reportOf, stoppedSincePrompt } from "./report.js";
+import { syncStanding } from "./standing.js";
 import { childStore, groupStore } from "./store.js";
 import { lastReply } from "./status.js";
 import { failureNotice, silentNotice } from "./text.js";
@@ -43,6 +44,7 @@ export async function reportFailure(ports, seen, event) {
     finally {
         if (completed.includes(true))
             ports.nudge();
+        await Promise.all(entries.map((entry) => syncStanding(ports, entry.parentID)));
     }
     return entries.map((entry) => entry.parentID);
 }
@@ -66,9 +68,11 @@ export async function notePrompt(ports, event, inbox) {
     if (inboxID !== undefined && UNOWED.has(inbox?.get(inboxID) ?? ""))
         return false;
     const children = childStore(ports.storage);
-    if ((await children.indexedParent(sessionID)) === undefined)
+    const parentID = await children.indexedParent(sessionID);
+    if (parentID === undefined)
         return false;
     await children.prompted(sessionID, event.created ?? ports.now());
+    await syncStanding(ports, parentID);
     return true;
 }
 /**
@@ -88,6 +92,7 @@ export async function noteInterrupted(ports, event) {
     const member = await outIn(ports, entry);
     if (member && (await leave(ports, member, "interrupted", at)))
         ports.nudge();
+    await syncStanding(ports, entry.parentID);
     return true;
 }
 /**
@@ -104,6 +109,8 @@ export async function noteDeleted(ports, event) {
     await forgetDeleted(ports, sessionID, forgotten, member, event.created);
     if (parentID !== undefined && entry && !entry.isolated && started.length === 0)
         await forgetChild(ports.storage, parentID, sessionID);
+    if (parentID !== undefined)
+        await syncStanding(ports, parentID);
     return forgotten;
 }
 /** A `Waits` asking `suppliers` one after another, cheapest first: the first that waits answers. */
@@ -165,6 +172,7 @@ export async function reportSilent(ports, seen, event, outside) {
         await children.untold(sessionID, toldAt).catch(() => undefined);
         throw error;
     }
+    await syncStanding(ports, entry.parentID);
     return [entry.parentID];
 }
 /**
@@ -179,6 +187,17 @@ export async function reportDeclined(ports, seen, event, outside) {
     return reportSilent(ports, seen, event, outside);
 }
 const TURN_ENDS = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"]);
+/** What `route` and `after` dispatch on; the wake watch needs `inbox.enqueued` and `execution.started` both. */
+const TREE_TYPES = [
+    "session.execution.started",
+    "session.execution.succeeded",
+    "session.execution.failed",
+    "session.execution.interrupted",
+    "session.inbox.enqueued",
+    "session.inbox.delivered",
+    "session.inbox.cancelled",
+    "session.deleted",
+];
 /** A session's turn ended, sealing its groups: one that is complete has the scheduler deliver it now; not a shutdown's, which stamps no idle time. */
 async function sealGroups(ports, event) {
     if (event.data.reason === "shutdown")
@@ -239,6 +258,7 @@ async function route(ports, state, outside, event) {
  */
 export function treeEvents(state, outside) {
     return {
+        types: TREE_TYPES,
         handle: (ports, event) => route(ports, state, outside, event),
         // After: a silent end is judged while the group the nudge may deliver is still there to wait on.
         after: (ports, event) => (TURN_ENDS.has(event.type) ? sealGroups(ports, event) : undefined),

package/dist/tree/group.js

@@ -1,6 +1,7 @@
 import { isNotFound, millis } from "../platform/json.js";
 import { envelope } from "../kernel/protocol.js";
 import { complete, standingOf } from "./domain.js";
+import { syncStanding } from "./standing.js";
 import { groupStore } from "./store.js";
 import { groupNotice } from "./text.js";
 /** Makes a spawned session a member of its parent's group, opening the group if it was not. */
@@ -182,6 +183,8 @@ async function release(ports, parentID, group) {
         }
     }
     await drop(ports, parentID, group, members);
+    // Delivered: the members read as released in the parent's standing, which its next step shows.
+    await syncStanding(ports, parentID);
 }
 /** Drops a group's members once delivered, or unsent, saying why. */
 async function drop(ports, parentID, group, members, unsent) {

package/dist/tree/index.d.ts

@@ -4,7 +4,7 @@ export { endsIdle, lineageIn, nativeRootOf, readLimits, readNativeChildren } fro
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
 export { contextOf } from "./panel.js";
-export type { CleanupPorts, CourierPorts, ModelWindow, Pending, PendingPrompt, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
+export type { CleanupPorts, CourierPorts, Entries, Entry, Instructions, ModelWindow, Pending, PendingPrompt, Role, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
 export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS, type ReportState } from "./roster.js";
 export { runs, turnIn, turnOf, type Turn } from "./running.js";
 export { subtree, type Below } from "./subtree.js";

package/dist/tree/model.d.ts

@@ -0,0 +1,18 @@
+import { type ModelRef } from "./domain.js";
+import type { CourierPorts } from "./ports.js";
+/** What courier_spawn says of the model: `provider/model`, and the variant of whichever model is chosen. */
+export interface ModelChoice {
+    readonly model?: string;
+    readonly variant?: string;
+}
+/**
+ * The model a child runs on: the `model` named, else the agent's, else the one its parent runs on, with the `variant`
+ * named; `parent` is the parent's own, for the roster to tell a child on another one.
+ */
+export declare function chooseModel(ports: CourierPorts, parentID: string, choice: ModelChoice, agent: string | undefined): Promise<{
+    model: undefined;
+    parent: ModelRef | undefined;
+} | {
+    model: ModelRef;
+    parent: ModelRef | undefined;
+}>;

package/dist/tree/model.js

@@ -0,0 +1,65 @@
+import { modelName, parseModelName } from "./domain.js";
+import { modelFormatRefusal, unknownModelRefusal, unknownVariantRefusal, variantWithoutModelRefusal } from "./text.js";
+/**
+ * The model a child runs on: the `model` named, else the agent's, else the one its parent runs on, with the `variant`
+ * named; `parent` is the parent's own, for the roster to tell a child on another one.
+ */
+export async function chooseModel(ports, parentID, choice, agent) {
+    // Some models send null, or an empty string, for an optional field they leave out.
+    const named = trimmed(choice.model);
+    const variant = trimmed(choice.variant);
+    const own = named === undefined ? undefined : parseModelName(named);
+    if (named !== undefined && !own)
+        throw new Error(modelFormatRefusal(named));
+    const parent = await parentModel(ports, parentID);
+    // An agent that cannot be looked up may name a model of its own, which OpenCode applies when none is passed.
+    const inherited = own ? undefined : await inheritedModel(ports, parent, agent).catch(() => undefined);
+    const base = own ?? inherited;
+    if (!base) {
+        if (variant !== undefined)
+            throw new Error(variantWithoutModelRefusal(variant, agent));
+        return { model: undefined, parent };
+    }
+    const chosen = variant ?? base.variant;
+    const model = { providerID: base.providerID, id: base.id, ...(chosen !== undefined ? { variant: chosen } : {}) };
+    if (own || variant !== undefined)
+        await check(ports, model, own !== undefined);
+    return { model, parent };
+}
+/**
+ * The model the parent runs on: its session's, else OpenCode's default. A failed lookup must not keep a child on no
+ * particular model from starting, so it reads as none, and the child then runs on OpenCode's default.
+ */
+async function parentModel(ports, parentID) {
+    const session = await ports.session.get({ sessionID: parentID }).catch(() => undefined);
+    if (!session)
+        return undefined;
+    return session.model ?? (await ports.defaultModel().catch(() => undefined));
+}
+/** The named agent's model, if it names one; else the parent's. */
+async function inheritedModel(ports, parent, agent) {
+    if (!agent)
+        return parent;
+    const named = await ports.agent.get({ agentID: agent, location: { directory: ports.directory } });
+    return named.data.model ?? parent;
+}
+/**
+ * Refuses a model OpenCode does not list, or a variant its model has not; `"default"` is every model's. A listing that
+ * cannot be read checks nothing: OpenCode refuses what it does not know at the child's first turn, which is reported.
+ */
+async function check(ports, model, named) {
+    let known;
+    try {
+        known = await ports.models();
+    }
+    catch (error) {
+        ports.log(`courier_spawn: cannot list the models to check ${modelName(model)} against: ${String(error)}`);
+        return;
+    }
+    const found = known.find((item) => item.providerID === model.providerID && item.id === model.id);
+    if (!found)
+        throw new Error(unknownModelRefusal(model, known, named));
+    if (model.variant !== undefined && model.variant !== "default" && !found.variants.includes(model.variant))
+        throw new Error(unknownVariantRefusal(model, found.variants));
+}
+const trimmed = (value) => (typeof value === "string" ? value.trim() || undefined : (value ?? undefined));

package/dist/tree/panel.js

@@ -1,3 +1,4 @@
+import { startedAs } from "./domain.js";
 import { lastStatus, stoppedSincePrompt } from "./report.js";
 import { standingIn } from "./status.js";
 import { childStore } from "./store.js";
@@ -80,7 +81,7 @@ async function row(ports, windows, { entry, depth, info, running, endedAt, pendi
         ...(stopped ? { stopped } : {}),
         ...reportRow(report, status),
         ...(entry.group && standing ? { group: { name: entry.group, standing } } : {}),
-        isolated: entry.isolated,
+        ...startedAs(entry),
         created: info?.time.created ?? entry.createdAt,
         ...(info && !running && endedAt !== undefined ? { idle: endedAt } : {}),
         ...(info ? { cost: info.cost } : {}),
@@ -96,7 +97,7 @@ async function row(ports, windows, { entry, depth, info, running, endedAt, pendi
 export async function panel(ports, rootID) {
     const { kept, leftOut } = await readTree(ports, rootID);
     const stalled = await stalledAmong(ports, [rootID, ...kept.map((node) => node.entry.sessionID)]);
-    const windows = await ports.windows().catch(() => []);
+    const windows = await ports.models().catch(() => []);
     const rows = await Promise.all(kept.map((node) => row(ports, windows, node, stalled.get(node.entry.sessionID))));
     const own = stalled.get(rootID);
     return { rows, ...(leftOut ? { truncated: leftOut } : {}), ...(own !== undefined ? { stalled: own } : {}) };