opencode-courier 0.2.2 → 0.3.0

package/README.md

@@ -1,5 +1,9 @@
 # opencode-courier
 
+**Your OpenCode session hands work to other sessions, ends its turn, and is woken when they
+report.** Multi-session orchestration for OpenCode V2: spawn child sessions, be woken by them. No
+polling.
+
 [![CI](https://github.com/ivopogace/opencode-courier/actions/workflows/ci.yml/badge.svg)](https://github.com/ivopogace/opencode-courier/actions/workflows/ci.yml)
 [![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=ivopogace_opencode-courier&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=ivopogace_opencode-courier)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ivopogace_opencode-courier&metric=coverage)](https://sonarcloud.io/summary/new_code?id=ivopogace_opencode-courier)
@@ -10,31 +14,98 @@
 [![License: MIT](https://img.shields.io/npm/l/opencode-courier)](LICENSE)
 [![Supported OpenCode V2 version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fivopogace%2Fopencode-courier%2Fmain%2Fpackage.json&query=%24.peerDependencies%5B%27%40opencode%2Fplugin%27%5D&label=opencode&color=blue)](#supported-opencode-version)
 
-An [OpenCode](https://github.com/anomalyco/opencode) V2 plugin that lets one session start other
-sessions, message them, and be woken by them, without polling.
+![A parent spawns two slow children, writes a README itself, and is woken by each report](docs/demo-async-tui.gif)
 
-A parent session calls `courier_spawn`, gets a session id back immediately and ends its turn. The
-child works on its own and, when it is done or stuck, calls `courier_send` with the parent's id.
-That message lands in the parent's inbox and OpenCode starts a new turn for the parent if it is
-idle. A child whose turn fails instead, so that it cannot report, is reported by the plugin, and a
-child that waits for a permission or asks a question has it passed to the parent, who asks you and
-passes your answer back.
+A parent writes a README while two slow children work, and each report wakes it ([the
+prompt](#demos)).
+
+## Quickstart
+
+```bash
+npm install -g @opencode/cli@2.0.26   # OpenCode V2, at the version courier is tested on
+opencode plugin add opencode-courier  # by name, so OpenCode offers new releases
+opencode                              # in any folder
+```
+
+Paste this prompt:
+
+> Start two helper sessions with courier_spawn and have each report back to you. One runs
+> `` `sleep 20; echo $((17 * 23))` ``, the other `` `sleep 40; echo $((2 ** 10))` ``. Do not run the
+> commands yourself. When both have reported, reply with one line: RESULTS \<first\> \<second\>
+
+The parent spawns both children and ends its turn. Within a minute the first report starts a new
+turn on its own, about 20 seconds later the second does, and the parent replies `RESULTS 391 1024`.
+If OpenCode asks to allow a child's command, the parent passes the question to you. Free models
+sometimes stall on a request; if nothing moves for a few minutes, send the prompt again. Next:
+[Using it](#using-it).
+
+## OpenCode V2 native
+
+Courier is built on OpenCode V2's plugin API (`@opencode/plugin`), not the V1 one
+(`@opencode-ai/plugin`), and needs OpenCode V2. Each release is pinned to one V2 version and tested
+against it end to end; the current one is tested on **OpenCode 2.0.26**. CI also runs the live
+suite on the newest OpenCode release, so a host release that breaks the plugin shows up there
+first. Older releases and their versions: [Supported OpenCode version](#supported-opencode-version).
 
 > **Status: early.** Passes an end-to-end test inside a live OpenCode V2 server driven by a
 > scripted stand-in model, and a smoke test with real (free) models: see
 > [Development](#development).
 
+## Courier or the built-in subagent tool?
+
+OpenCode V2 has its own [`subagent` tool](https://opencode.ai/v2/docs/agents): it starts an agent
+with fresh context in a child session, and the parent either waits for its final answer or, with
+`background: true`, carries on and is notified when the child finishes. Passing the child's
+`sessionID` back sends it another prompt, steering it if it is running and waking it if it is idle.
+Use it when one result back is all you need: a search, a review, a self-contained task that needs
+nothing from you on the way.
+
+Use courier when the work needs more than one result back. On top of what the built-in tool does,
+it adds:
+
+- **Messages from the child, mid-run:** with the built-in tool a child's one message to its parent
+  is its final answer. With courier a child reports progress, or asks its parent something,
+  whenever it likes with `courier_send`, and any session can message any other.
+- **Waking an idle session from anywhere:** a message from a child, a schedule or a webhook starts a
+  new turn in a session that has ended its own.
+- **Scheduled messages:** `courier_later` wakes a session at a set time, for check-ins and
+  reminders.
+- **Webhooks:** GitHub reviews, comments and CI runs, or any signed POST, wake the
+  [subscribed](#webhooks) session.
+- **Worktree isolation:** `isolate: true` gives a child its own git worktree, so children can edit
+  files in parallel. An isolated child that splits hands its committed work down: its isolated
+  children start from its HEAD, and each isolated child commits on `courier/<its session ID>` and
+  reports that branch for its parent to merge ([nested isolation](docs/reference.md#nested-isolation)).
+- **Relaying to you:** a child's permission requests and questions reach you through the parent,
+  and your answers go back; a form only you can answer is pointed out to you.
+
+## How it works
+
+A parent session calls `courier_spawn`, gets a session id back immediately and ends its turn. The
+child works on its own and, when it is done or stuck, calls `courier_send` with the parent's id, a
+status and what it produced. That message lands in the parent's inbox and OpenCode starts a new
+turn for the parent if it is idle. A child whose turn fails instead, so that it cannot report, or ends without reporting, is
+reported by the plugin, and a child that waits for a permission or asks a question has it passed to the parent, who asks you and
+passes your answer back. A child that waits on a form only you can answer, such as OpenCode asking
+which web search provider to use, has its parent told so.
+
+There is no polling anywhere: a message is admitted into the target session's inbox through
+OpenCode's own API, which wakes the session, the same way OpenCode's background subagents report to
+their parent. Delivery is `steer` by default (injected into the target's running turn, or starts
+one if idle); `queue: true` waits until the current turn ends.
+
+## Demos
+
 **The parent does not wait.** Prompt: *"Spawn two children: one runs `sleep 30` then lists the
 exports of math.js, the other runs `sleep 45` then lists the exports of text.js. Don't wait for
 them: meanwhile write a short README.md for this folder yourself, and add their reports to it when
 they arrive."*
 
-![A parent spawns two slow children, writes a README itself, and is woken by each report](docs/demo-async-tui.gif)
-
-Watch the parent write its README and finish its turn 16 seconds in, while both children still
-sleep. Each report then starts a new turn on its own (the `Message from ses_…` line is the child's
-message): the first after about 30 seconds, the second after about 45, and the parent folds each
-into the README and cancels the check-in it had scheduled for itself.
+The recording at the top is this run. Watch the parent write its README and finish its turn 16
+seconds in, while both children still sleep. Each report then starts a new turn on its own (the
+`Message from ses_…` line is the child's message): the first after about 30 seconds, the second
+after about 45, and the parent folds each into the README and cancels the check-in it had scheduled
+for itself.
 
 **A child's question reaches you.** Prompt: *"Spawn a child session to add a multiply function to
 math.js. It must ask me first whether to name it multiply, times or product."*
@@ -44,87 +115,91 @@ math.js. It must ask me first whether to name it multiply, times or product."*
 Watch the child's question open in the parent's session as OpenCode's own question form, where
 `times` is picked. The parent passes it back, and the child adds `times` to math.js and reports.
 
-<details>
-<summary>The same two runs in OpenCode's web UI</summary>
-
-![The async demo in the web UI: the parent writes its README, ends its turn, and is woken by each report](docs/demo-async.gif)
-
-![The question demo in the web UI: the child's question appears in the parent, is answered there, and the child carries on](docs/demo-question.gif)
-
-</details>
-
-Both recordings are real runs on `opencode2 v0.0.0-beta-19271` with a free model on [OpenCode
-Zen](https://opencode.ai/zen) (Muse Spark 1.3).
-
-## How the wake works
-
-There is no polling anywhere. `courier_send` calls the plugin API's `session.synthetic`, which
-admits a message into the target session's inbox and, unless `resume: false` is passed, calls
-`execution.wake` on it (`packages/core/src/session/session.ts` on OpenCode's `v2` branch).
-OpenCode's own background subagents report to their parent the same way
-(`packages/core/src/session/subagent-completion.ts`).
-
-Delivery is `steer` by default (injected into the target's running turn, or starts one if idle);
-`queue: true` waits until the current turn ends.
+Both recordings are real runs with a free model on [OpenCode Zen](https://opencode.ai/zen) (Muse
+Spark 1.3).
+
+## Recursive orchestration
+
+A session splits a goal across child sessions, each child decides in turn whether to split its
+part again, and the results are checked and integrated at every level on the way back up. The
+plugin ships the playbook as an OpenCode skill, `courier-orchestrate`, listed in every session with
+the plugin loaded: how to decide whether to split, and to say which in one line of the reply
+(`split: no, because …; considered: <the parts you weighed>` or `split: 3 parts: …`), plan the
+parts, start them in one join group, end the turn, read each report by its status, verify
+first-hand through the project's scripts, integrate and report upward, and what to do when a part
+fails, ends quietly, blocks or hits a limit. It names the parts an implementation task with one
+tightly coupled core usually still has: its e2e scenario, its documentation, sometimes a second
+test file, and a review of the core by a session with fresh context (`isolate: false`, it edits
+nothing). The session does the core itself first and commits it, then starts one session per
+remaining part, if 2 or more remain; a review session's findings are a report to act on, and
+running the checks stays the session's own. Its description asks a model to load it at the start
+of any implementation task that may have independent parts, and a session nobody spawned is pointed to it by its system prompt as well
+([Session trees](#session-trees)); `/skills` in the TUI attaches it to your prompt. Its text:
+[the reference](docs/reference.md#the-courier-orchestrate-skill).
+
+The smoke test's recursive scenario (`COURIER_SCENARIO=recursive`, [docs/real-model.md](docs/real-model.md#recursive-orchestration))
+asks a free model:
+
+> Have this job done through helper sessions started with courier_spawn, one session per part, and
+> do no part yourself. It has two parts. Part "numbers" is itself two independent halves, which the
+> session that gets it hands to two sessions of its own: one runs `` `sleep 20; echo $((17 * 23))` ``
+> and writes the number it printed to numbers/a.txt, the other runs `` `sleep 20; echo $((2 ** 10))` ``
+> and writes the number it printed to numbers/b.txt. Part "count" runs `` `sleep 20; echo $((99 - 57))` ``
+> and writes the number it printed to count/total.txt. When the parts have reported back, read the
+> three files yourself and reply with one line: RESULTS \<a\> \<b\> \<total\>
+
+The root starts two sessions and ends its turn; the "numbers" session starts two of its own, ends
+its turn, checks both files when their reports wake it and reports once to the root; the "count"
+session does its part itself. The root is woken by the two reports, reads the three files and
+replies `RESULTS 391 1024 42`. The checker verifies the shape of the tree, that no session polled or
+went past `maxDepth`, that every report carries a status and each sub-orchestrator reported once,
+after its children, and the files and the final line.
 
 ## Install
 
 ### Supported OpenCode version
 
-Requires OpenCode V2: the `opencode` command from `@opencode/cli` (the same binary is also installed
-as `opencode2`, the name of the beta line, so a shell that still calls that keeps working). Each
-release of this plugin is built and tested against exactly one OpenCode V2 version, the
-`@opencode/plugin` version pinned in `package.json` (the CLI and the plugin API share a version).
-The end-to-end suite runs on that version with every change, and once more on the newest
-`@opencode/cli` release, where a failure is a warning rather than a red build, so a host release
-that breaks the plugin shows up in CI first. A newer OpenCode may still break tools;
-[docs/plugin-api-notes.md](docs/plugin-api-notes.md) lists what the pinned version already needed
-working around, and what changed the last time the pin moved. A release that moves the pin adds a
-row here. When the plugin loads on an OpenCode whose version is not the pinned one, it writes one
-line to the server log naming both versions, so a mismatch is named before a tool fails.
+Requires OpenCode V2: the `opencode` command from `@opencode/cli` (also installed as `opencode2`,
+the name of the beta line). Each release of this plugin is built and tested against exactly one
+OpenCode V2 version, and a release that moves the pin adds a row here. OpenCode itself never
+checks the version: the plugin installs and loads on any V2 host. When it loads on a version other
+than the pinned one, it writes one line to the server log naming both versions, so a mismatch is
+named before a tool fails. More in [the reference](docs/reference.md#the-opencode-version).
 
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
+| 0.2.3 | 2.0.26 |
 | 0.2.2 | 2.0.24 |
 | 0.2.1 | 2.0.23 |
 | 0.2.0 | 2.0.22 |
 | 0.1.6 | 0.0.0-beta-19271 (the beta line: `opencode2` from `@opencode-ai/cli`, and `@opencode-ai/plugin`) |
 
-0.2.2 moves the pin to 2.0.24, which changed nothing the plugin calls; 0.2.1 passes the suite on
-2.0.24 as well. 0.2.1 changes nothing but the pin: 2.0.23 changed nothing the plugin calls, and
-0.2.0 passes the suite on 2.0.23 as well. 0.2.0 was tested on 2.0.22 and on the `dev` build 0.0.0-dev-20534 of 2026-10-04, the newest build
-then (no 2.x release above 2.0.22 existed), where the suite passed too. Of the older hosts tried, it
-loads on 2.0.4 and 2.0.21 (nothing in between was run, and the suite was not), and fails to load on
-2.0.0 and 2.0.3, which lack the `model` domain the plugin API gained in 2.0.4. The version in
-`package.json` protects nobody on its own: OpenCode says nothing about it, since
-`opencode plugin add` installs the plugin whatever your OpenCode version and its loader warns about
-nothing either (a recorded experiment, in
-[docs/plugin-api-notes.md](docs/plugin-api-notes.md#what-plugin-add-and-loading-do-with-the-peer-dependency-2026-10-04),
-which also says why the peer dependency stays exact rather than a range: it picks the copy of the
-plugin API the plugin runs on). The plugin's own log line above is the only runtime signal, apart
-from the load failure on those hosts before 2.0.4. Check yours with `opencode --version`, and
-install the matching CLI with:
+Check yours with `opencode --version`, and install the matching CLI with:
 
 ```bash
-npm install -g @opencode/cli@2.0.24
+npm install -g @opencode/cli@2.0.26
 ```
 
 ### The plugin
 
-Then install the plugin:
-
 ```bash
 opencode plugin add opencode-courier
 ```
 
 This installs the package from npm and adds `"opencode-courier"` to `plugins` in the global
 configuration (`~/.config/opencode/opencode.json`). To receive webhooks, replace that entry with the
-object form shown under [Webhooks](#webhooks), which carries a `webhook` option.
+object form shown under [Webhooks](#webhooks), which carries a `webhook` option; the [session tree
+limits](#session-trees) are options of the same entry.
+
+Install it by name, without a version: OpenCode only checks plugins for updates when their entry is
+not an exact version, so `opencode-courier@0.2.1` is never offered a newer release. How to move an
+entry that carries a version to the name, and what to look at when an update still does not show:
+[Updating the plugin](docs/reference.md#updating-the-plugin).
 
 ### From a local clone
 
 ```bash
-git clone <this repo> && cd opencode-courier
+git clone https://github.com/ivopogace/opencode-courier && cd opencode-courier
 bun install && npm run build
 ```
 
@@ -142,30 +217,40 @@ Then list it in `opencode.json` (V2 uses `plugins`, plural). A local plugin path
 1. Keep the background server running so sessions can be woken while you are away (`opencode
    service start`; `opencode service status` to check).
 2. Give the agents that run children the permissions their work needs. A child that hits an approval
-   prompt has it passed to its parent, which asks you (see [A child that asks for
-   permission](docs/reference.md#a-child-that-asks-for-permission)), but the child waits until you
-   answer, so keep prompts for what you want to decide yourself. A child's question goes to the
-   parent the same way (see [A child that asks a
-   question](docs/reference.md#a-child-that-asks-a-question)), so let the agents that run children
-   use the `question` tool if they should be able to ask you; OpenCode's default agent may.
-3. Use `isolate: true` whenever children edit files in parallel. The child's worktree is made from
-   the last commit, so an uncommitted `opencode.json` is not there and the child falls back to your
+   prompt has it passed to its parent, which asks you, but the child waits until you answer, so keep
+   prompts for what you want to decide yourself. A child's question goes to the parent the same
+   way, so let the agents that run children use the `question` tool if they should be able to ask
+   you; OpenCode's default agent may. Choose a web search provider before children search the web
+   (run one web search in your own session and answer OpenCode's prompt, or use its "Third-party
+   search" setting): otherwise the first child to search shows that prompt in its own session,
+   which only you can answer there.
+3. Your own session's prompts are relayed nowhere, and each one stalls the whole tree until you
+   answer it. Before an unattended run, allow the orchestrating session's toolchain up front: the
+   repository's `bun run` and `npm run` scripts, `git`, and whatever its checks need. Prefer one rule
+   on `bun run *` or `npm run *` over a rule per binary; the skill tells a session that orchestrates
+   to run checks through the project's scripts rather than `./node_modules/.bin/<tool>`, so one rule
+   covers them.
+4. Use `isolate: true` whenever children edit files in parallel. The child's worktree is made from
+   the last commit (from an isolated session, its HEAD), so an uncommitted `opencode.json` is not there and the child falls back to your
    global config: keep providers and models in the global config, or commit the file. When you are
    done with an isolated child, `courier_cleanup` it so its worktree does not linger.
-4. A child that crashes before calling `courier_send` never wakes the parent. When you spawn a
-   long-running child, also `courier_later` a check-in for yourself, and `courier_cancel` it when
-   the child reports.
+5. A child whose turn fails, or ends without `courier_send`, is reported to its parent by the
+   plugin. What the plugin cannot see, such as a server that stops while a child runs, a
+   `courier_later` check-in still covers: for a long-running child, schedule one for yourself and
+   `courier_cancel` it when the child reports.
 
 ## Tools
 
 | Tool | Does |
 |---|---|
-| `courier_spawn` | Creates a session (optionally in its own git worktree with `isolate: true`) on the parent's model, sends it the task plus a brief naming the parent and how to report back, and returns at once. |
-| `courier_send` | Delivers a message to a session, signed with the sender's id, waking it if idle. |
+| `courier_spawn` | Creates a session (optionally in its own git worktree with `isolate: true`, which from an isolated session starts at its HEAD, [nested isolation](docs/reference.md#nested-isolation)) on the parent's model, sends it the task plus a brief naming the parent, how to report back and when to split the task further, and returns at once. With a `group` name, the reports of every session started under that name are held and delivered together, in one message ([reference](docs/reference.md#join-groups)). Refused past the [session tree limits](#session-trees). |
+| `courier_send` | Delivers a message to a session, signed with the sender's id, waking it if idle. From a child to its parent, a `status` (`done`, `partial`, `blocked` or `failed`) makes it the child's report, carried as an attribute of the message (`<courier from="…" status="done">`), and `artifacts` (`branch`, `commits`, `files`, `checks`) are listed in its body in a fixed layout; a message without a status is progress, not the report ([reference](docs/reference.md#a-childs-report)). From a member of a join group, a report with `done`, `partial` or `failed` is held with the group instead, and the result says so. |
 | `courier_status` | One look at a session: outcome, idle time, last reply and the permission requests and questions it waits on. For check-ins, not for waiting. |
-| `courier_children` | Lists the sessions this one (or a given `sessionID`) started with `courier_spawn`, each with what `courier_status` reports plus its directory, whether it is isolated and when it was started. |
-| `courier_cleanup` | Removes the git worktree of a child started with `isolate: true` and drops the child from `courier_children`. Keeps a worktree with uncommitted changes or commits on no branch, tag or remote and lists them, unless `force: true` is passed. |
-| `courier_answer` | Passes the person's answer to a permission request or a question that a session started from this one waits on, after the plugin relayed it here: `reply` (`once`, `always` or `reject`, with an optional `message`) for a permission request, `answers` for a question. See [A child that asks for permission](docs/reference.md#a-child-that-asks-for-permission) and [A child that asks a question](docs/reference.md#a-child-that-asks-a-question). |
+| `courier_children` | Lists the sessions this one (or a given `sessionID`) started with `courier_spawn`, each with what `courier_status` reports plus its directory, whether it is isolated, when it was started and, for one started in a group, the group and whether its report is `held`, `out` or `released`. |
+| `courier_tree` | Lists the whole tree under this session (or a given `sessionID`): every session started from it with `courier_spawn`, directly or through others, depth first, each with what `courier_children` shows plus its depth, its parent, and its report state (whether it owes a report, sent progress, ended without one, and the status of its last report). Cut at `maxTotal` sessions ([reference](docs/reference.md#seeing-and-stopping-a-subtree)). |
+| `courier_stop` | Interrupts a session you started, directly or through others, and every session under it, deepest first, and cancels the `courier_later` messages scheduled for them. With `cleanup: true` it also removes their worktrees, by `courier_cleanup`'s rules (kept ones are listed). You are not told of what you stopped; a session between you and the target is, once, as `ended="stopped"` ([reference](docs/reference.md#seeing-and-stopping-a-subtree)). |
+| `courier_cleanup` | Removes the git worktree of a child started with `isolate: true` and drops the child from `courier_children`. Keeps a worktree with uncommitted changes or commits on no branch, tag or remote and lists them, unless `force: true` is passed ([reference](docs/reference.md#worktree-cleanup)). A child without a worktree is only dropped from `courier_children`; either way, a join group member that has not reported is dropped from its group, which is released without it ([reference](docs/reference.md#join-groups)). |
+| `courier_answer` | Passes your answer to a permission request or a question that a session started from this one waits on: `reply` (`once`, `always` or `reject`, with an optional `message`) for a permission request, `answers` for a question. |
 | `courier_later` | Schedules a message for a session (this one by default) in `delayMinutes` or `at` an ISO time, and returns an id. When due it is delivered like `courier_send`, queued behind any running turn and waking the session if idle. |
 | `courier_cancel` | Drops a message scheduled with `courier_later`, e.g. because the child it was waiting for reported first. |
 | `courier_subscribe` | Subscribes a session (this one by default) to webhook deliveries for a `topic`: `owner/repo`, `owner/repo#12` (one pull request or issue) or a generic name. Each matching delivery arrives as a message, queued behind any running turn and waking the session if idle. Needs the [webhook receiver](#webhooks). |
@@ -178,9 +263,31 @@ The short version; the long one, with every edge, is [docs/reference.md](docs/re
 - **A child runs on its parent's model**, not on OpenCode's default, so a parent you moved to
   another model starts children that can reach theirs too. An `agent` with a model of its own keeps
   it. [More](docs/reference.md#the-childs-model).
+- **A child can split its task** with `courier_spawn` of its own, within the [limits](#session-trees):
+  its brief says when to split and when to do the work itself, and a session that splits checks
+  its children's work and sends one combined report. [More](docs/reference.md#session-trees-and-their-limits).
+- **A child reports once, with a status**: `done`, `partial`, `blocked` (it needs a decision from
+  its parent, and says what) or `failed`, as an attribute of the message, with its artifacts listed
+  in the body. A message without a status is progress, so a child that sends "halfway" and then
+  stops is still reported as ending without a report. [More](docs/reference.md#a-childs-report).
+- **A join group wakes you once.** Start a batch of sessions with the same `group` name, and
+  their `done`, `partial` and `failed` reports are held until the last one is in and your turn has ended, then delivered
+  in one message, marked `group="<name>"`, listing every report with its status and artifacts in
+  the order the sessions were started. A `blocked` report, progress, a failed turn, a silent end, a
+  permission request and a question reach you at once, as ever; a member whose turn fails or is
+  interrupted leaves the group, which is released without it. A member that will not report (it
+  ended its turn silently, or you gave up on it) holds the others back: drop it with
+  `courier_cleanup`, and the group is released without it, the message naming it; a report it
+  sends after all comes on its own. Held reports survive a restart, and the name is free again
+  once the group has been delivered. [More](docs/reference.md#join-groups).
 - **A child that fails** cannot report, so the plugin does: every failed turn of a spawned session
   sends its parent a message marked `failed="<error type>"`, with the error, waking it if idle.
   [More](docs/reference.md#a-child-that-fails).
+- **A child that ends its turn without reporting** to its parent has the parent told, marked
+  `ended="without-report"`, with its last reply, waking it if idle; it counts toward the limits
+  until it reports. One that waits, on a request, a session it started, a scheduled message or a
+  webhook it just subscribed to, is not reported, nor is one that answers what you typed in its session.
+  [More](docs/reference.md#a-child-that-ends-without-a-report).
 - **A child that asks for permission** has the request passed to the session at the top, with what
   it asks for and the choices OpenCode offers (`once`, `always`, `reject`). That session asks you
   and answers with `courier_answer`; the child carries on.
@@ -191,13 +298,52 @@ The short version; the long one, with every edge, is [docs/reference.md](docs/re
   parent's or by `courier_answer`, and the other question is withdrawn; a question stays answerable
   across an interrupted turn or a server restart.
   [More](docs/reference.md#a-child-that-asks-a-question).
-- **The plugin remembers.** Each parent's children (`courier_children`), pending `courier_later`
-  messages and open questions survive a compaction or a restart; entries are dropped after 14 days.
+- **A child that shows a form** the plugin cannot pass on, such as OpenCode's web search asking
+  for a provider, has the top session told, marked `asks="form"`, with the form's choices: only you
+  can answer it, in the child's session. [More](docs/reference.md#a-child-that-shows-a-form).
+- **You can see and stop a whole subtree.** `courier_tree` lists every session under yours with its
+  depth and report state; `courier_stop` interrupts one of them and everything under it, deepest
+  first, and cancels their scheduled messages. A stop is neither a failure nor a silent end, and
+  only a session above the target may order it. [More](docs/reference.md#seeing-and-stopping-a-subtree).
+- **The plugin remembers.** Each parent's children (`courier_children`) and whether each owes a
+  report, held group reports, pending `courier_later` messages and open questions survive a compaction or a restart; entries are dropped after 14 days.
   [Roster](docs/reference.md#roster), [Scheduled messages](docs/reference.md#scheduled-messages).
+- **One OpenCode server per data directory, preferably.** A second server on the same one, such as
+  `opencode serve` next to `opencode service`, shares the plugin's storage: one of the two delivers
+  `courier_later` messages and released groups, but a child's permission request can only be answered from the server
+  that runs the child. [More](docs/reference.md#two-servers-on-one-data-directory).
 - **Worktrees are yours to remove.** An isolated child's worktree is kept until `courier_cleanup`,
   which refuses to drop uncommitted changes or unbranched commits unless told to.
   [More](docs/reference.md#worktree-cleanup).
 
+## Session trees
+
+A spawned session may start sessions of its own, so the sessions form a tree, and three options
+bound it. Set them in the plugin's `options`, in the global config (`~/.config/opencode/opencode.json`):
+
+```jsonc
+{
+  "plugins": [{ "package": "opencode-courier", "options": { "maxDepth": 2, "maxChildren": 3 } }]
+}
+```
+
+| Option | Default | |
+|---|---|---|
+| `maxDepth` | `3` | How deep the tree goes: your session is depth 0, the sessions it starts depth 1. A session at `maxDepth` cannot start sessions. |
+| `maxChildren` | `5` | How many sessions one session started may have live at once. |
+| `maxTotal` | `20` | How many spawned sessions may be live at once in one tree. |
+
+`courier_spawn` refuses a spawn past a limit, naming it and saying what to do instead: do the work
+itself, or wait for a child to report. A session counts while it is live: its turn runs, it owes
+its parent a report (its task or a message reached it after it last reported, failed or was interrupted), or a
+session below it is live. One that has reported, with nothing live below it, does not. Each
+spawned session's model is also told its role on every request: `sub-orchestrator`, which may split
+its task, or `leaf`, at `maxDepth`, which does not see `courier_spawn` at all. Your own session is
+told, in one line, to load the `courier-orchestrate` skill before a task that touches several files
+or areas, decide whether to split it, and say which in one line of its reply (`split: no, because …;
+considered: <the parts you weighed>` or `split: 3 parts: …`); once it has started a session, that
+line becomes a `root orchestrator` part with the limits. The details: [the reference](docs/reference.md#session-trees-and-their-limits).
+
 ## Webhooks
 
 The receiver is off unless the plugin has a `webhook` option. Put it in the **global** config
@@ -269,36 +415,29 @@ OPENCODE_BIN=$(which opencode) npm run test:e2e   # live test, about two minutes
 OPENCODE_BIN=$(which opencode) e2e/real-model.sh  # smoke test with a real model, not in CI
 ```
 
-`e2e/run.sh` starts a real OpenCode V2 server in a throwaway project and home directory, with this
-plugin loaded and `e2e/mock-model.mjs` as the model: an OpenAI-compatible server that replies from a
-fixed script. It walks every tool through the behaviour above, including a permission request, a
-question answered on either side, a server restart with pending work, a signed and an unsigned
-GitHub delivery, and the package installed from a stand-in npm registry. It needs node, npm, bun,
-git, curl, jq and openssl. New behaviour gets a scenario there.
-
-`e2e/real-model.sh` runs the same server with a real model (by default a free one on [OpenCode
-Zen](https://opencode.ai/zen), no key needed) and asks the parent to fan a small task out to two
-children; `COURIER_SCENARIO=permission` and `COURIER_SCENARIO=question` exercise the two relays with
-the script in the person's place. It checks that the parent spawns instead of doing the work, ends
-its turn instead of polling, and that each report wakes it. Which models pass and what was tuned for
-them: [docs/real-model.md](docs/real-model.md).
-
-CI (`.github/workflows/ci.yml`) runs both suites on every push to `main` and every pull request,
-with the OpenCode CLI at the same version as the pinned plugin API, and the live suite once more
-with the CLI at its `latest` dist-tag: that job may fail, and its step summary names the version it
-ran on, so a host release that breaks the plugin is seen without blocking the build. On `main` and
-on this repository's own pull requests, a SonarCloud job then scans `src/` with the unit suites'
-coverage (`sonar-project.properties`), and fails when the quality gate does. Releases start from
-GitHub and end with a maintainer's 2FA approval on npm: [docs/releasing.md](docs/releasing.md).
-What the plugin API does that the plugin had to work around, and what changed when the pin last
-moved: [docs/plugin-api-notes.md](docs/plugin-api-notes.md).
+The live test (`e2e/run.sh`) starts a real OpenCode V2 server in a throwaway project and home
+directory, with this plugin loaded and a scripted OpenAI-compatible stand-in model, and walks every
+tool through the behaviour above. It needs node, npm, bun, git, curl, jq and openssl. New behaviour
+gets a scenario there.
+
+The smoke test (`e2e/real-model.sh`) runs the same server with a real model (by default a free one
+on [OpenCode Zen](https://opencode.ai/zen), no key needed) and checks that the parent spawns instead
+of doing the work, ends its turn instead of polling, and is woken by each report;
+`COURIER_SCENARIO=permission` and `COURIER_SCENARIO=question` exercise the two relays, and
+`COURIER_SCENARIO=recursive` the [recursive orchestration](#recursive-orchestration) above. Which
+models pass and what was tuned for them: [docs/real-model.md](docs/real-model.md).
+
+CI runs both suites on every push to `main` and every pull request, with the OpenCode CLI at the
+pinned version, and the live suite once more on the newest OpenCode release, where a failure warns
+rather than breaks the build. SonarCloud scans `src/` on `main` and on pull requests. Releases start
+from GitHub and end with a maintainer's 2FA approval on npm: [docs/releasing.md](docs/releasing.md).
+What the plugin API does that the plugin had to work around: [docs/plugin-api-notes.md](docs/plugin-api-notes.md).
 
 ## Contributing
 
 Questions and bug reports go to the [issues](https://github.com/ivopogace/opencode-courier/issues).
 Pull requests are welcome: a change in behaviour comes with a unit test, an `e2e/run.sh` scenario
 and its line in this README or [docs/reference.md](docs/reference.md), and CI must be green.
-Maintainers release from GitHub as [docs/releasing.md](docs/releasing.md) describes.
 
 ## License
 

package/dist/bounded.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Bounded `Set`s and `Map`s of remembered ids that drop their oldest entry past a bound. Functions
+ * on the built-ins, not a class, as older plugin copies call `.has` and `.add` on the shared ones.
+ */
+/** Adds to a bounded set, dropping the oldest entry past `max`; false when the value was there already. */
+export declare function addBounded<T>(set: Set<T>, value: T, max: number): boolean;
+/** Sets an entry of a bounded map, dropping the oldest entry past `max`; an existing key keeps its place. */
+export declare function setBounded<K, V>(map: Map<K, V>, key: K, value: V, max: number): void;

package/dist/bounded.js

@@ -0,0 +1,19 @@
+/**
+ * Bounded `Set`s and `Map`s of remembered ids that drop their oldest entry past a bound. Functions
+ * on the built-ins, not a class, as older plugin copies call `.has` and `.add` on the shared ones.
+ */
+/** Adds to a bounded set, dropping the oldest entry past `max`; false when the value was there already. */
+export function addBounded(set, value, max) {
+    if (set.has(value))
+        return false;
+    set.add(value);
+    if (set.size > max)
+        set.delete(set.values().next().value);
+    return true;
+}
+/** Sets an entry of a bounded map, dropping the oldest entry past `max`; an existing key keeps its place. */
+export function setBounded(map, key, value, max) {
+    map.set(key, value);
+    if (map.size > max)
+        map.delete(map.keys().next().value);
+}

package/dist/cleanup.d.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from "@opencode/plugin";
+import { type CleanupResult } from "./notices.js";
 import { type RosterStorage } from "./roster.js";
 type Context = Plugin.Context;
 /** What would be lost by removing a worktree. */
@@ -18,39 +19,38 @@ export interface CleanupPorts {
     readonly projectID: string;
     /** The worktree's state, or undefined when its directory no longer exists; `base` is the commit it was made from. */
     readonly inspect: (directory: string, base?: string) => Promise<WorktreeState | undefined>;
+    /** When a member still out is dropped from its group. */
+    readonly now: () => number;
+    /** Has the scheduler deliver what is due now: a group the forgotten child may have been the last member out of. */
+    readonly nudge: () => void;
 }
 export interface CleanupInput {
     readonly sessionID: string;
     readonly force?: boolean;
 }
-export type CleanupResult = {
-    readonly sessionID: string;
-    readonly directory: string;
-    readonly outcome: "removed";
-} | {
-    readonly sessionID: string;
-    readonly directory: string;
-    readonly outcome: "gone";
-} | {
-    readonly sessionID: string;
-    readonly directory: string;
-    readonly outcome: "kept";
-    readonly reason: string;
-    readonly changes: readonly string[];
-    readonly commits: readonly string[];
-};
-/** Why a worktree in this state must be kept, or undefined when removing it loses nothing. */
-export declare function keepReason(state: WorktreeState): string | undefined;
 /** At most this many changes and commits are returned; the reason still counts them all. */
 export declare const MAX_LISTED = 50;
 /**
- * Removes the worktree of an isolated child the parent started, and forgets the child. A worktree
- * with uncommitted changes or commits that exist nowhere else is kept unless `force` is set, and the
- * result says what is in it.
+ * 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.