opencode-courier 0.1.6 → 0.2.0

package/README.md

@@ -1,6 +1,10 @@
 # opencode-courier
 
 [![CI](https://github.com/ivopogace/opencode-courier/actions/workflows/ci.yml/badge.svg)](https://github.com/ivopogace/opencode-courier/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/opencode-courier)](https://www.npmjs.com/package/opencode-courier)
+[![Socket Badge](https://badge.socket.dev/npm/package/opencode-courier)](https://socket.dev/npm/package/opencode-courier)
+[![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.
@@ -12,304 +16,102 @@ idle. A child whose turn fails instead, so that it cannot report, is reported by
 child that waits for a permission or asks a question has it passed to the parent, who asks you and
 passes your answer back.
 
-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."*
+> **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).
 
-![A parent spawns two slow children, writes a README itself, and is woken by each report](docs/demo-async.gif)
+**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."*
 
-Watch the parent write its README and finish its turn 13 seconds in, while both children still
-sleep. Each report then starts a new turn on its own (the `Details` 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.
+![A parent spawns two slow children, writes a README itself, and is woken by each report](docs/demo-async-tui.gif)
 
-A child's question reaches you. Prompt: *"Spawn a child session to add a multiply function to
+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."*
 
-![A child's question appears in the parent, is answered there, and the child carries on](docs/demo-question.gif)
+![A child's question opens as a form in the parent's session, times is picked, and the child carries on](docs/demo-question-tui.gif)
+
+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)
 
-Watch the child's question open in the parent's session, where the answer `times` is picked. The
-parent passes it back, and the child adds `times` to math.js and reports.
+</details>
 
-> **Status: early.** Passes an end-to-end test inside a live OpenCode V2 server
-> (`opencode2 v0.0.0-beta-19271`) driven by a scripted stand-in model (`e2e/run.sh`), and a smoke
-> test with real (free) models: see [Real models](#real-models).
+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 `beta` branch).
+`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.
 
-## Tools
+## Install
 
-| Tool | Does |
+### 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.
+
+| opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
-| `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_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](#a-child-that-asks-for-permission) and [A child that asks a question](#a-child-that-asks-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). |
-| `courier_unsubscribe` | Drops one topic, or all of a session's, e.g. once its pull request is merged. |
-
-### The child's model
-
-A child runs on the model its parent is using, not on OpenCode's default, so a parent you moved to
-another model starts children that can reach theirs too. The exception is a child given an `agent`
-that names a model of its own: that agent's model is kept. If the parent's model cannot be looked
-up, the child is started anyway, on OpenCode's default.
-
-### A child that fails
-
-A child reports with `courier_send`, which it cannot do when its turn fails: the model is not
-available to the account, the credentials are missing, the provider is down. The plugin follows
-OpenCode's events, and for every `session.execution.failed` of a session on a roster it sends the
-parent a message from that child, marked `failed="<error type>"`, with the child's title and the
-error, waking the parent if it is idle. The parent then decides: message the child to have it try
-again, start a replacement, or carry on without it.
-
-Every failed turn of a child is reported, also one that fails after the child has reported. A turn
-that was interrupted is not a failure and is not reported, and neither is a failure that happens
-while the OpenCode server is down or the plugin is not loaded; a `courier_later` check-in still
-covers those.
-
-### A child that asks for permission
-
-When a child's tool call needs an approval (a permission rule with `"effect": "ask"`, or no rule
-for it), OpenCode holds the call until someone answers in the child's session, which the person
-working in the parent's session does not see. The plugin follows `permission.asked`, and for a
-session on a roster it sends the parent a message from that child, marked `asks="permission"` and
-`request="<id>"`, waking the parent if it is idle. The message says what the child asks for (the
-action, such as `shell` or `edit`, and its resources, such as the command or the paths), lists
-the choices OpenCode's own prompt offers, and tells the parent to ask the person rather than
-decide:
-
-- `once`: allow this request only;
-- `always`: allow it and save the rule for the project; offered only when the request says what
-  to save, as in OpenCode's prompt;
-- `reject`: refuse it, with a reason if the person gives one.
-
-The parent asks you, with its question tool if it has one, and calls
-`courier_answer { sessionID, requestID, reply, message? }` with your choice. The plugin passes it
-on with the plugin API's `permission.reply`, and the child carries on.
-
-A request of a child's child goes to the session at the top, the one you started the first child
-from, and so on down any number of levels, since that is where you are; the message names the
-session that started the asking one. Only that top session can answer it. A session started with
-`courier_spawn` cannot answer what its own children ask, so it cannot get around a rule that makes
-it ask by starting a child to do the job and approving it.
-
-OpenCode ends the child's turn when a request is rejected without a message, and the child would
-then never report back. So `courier_answer` always sends a message with a rejection, the person's
-reason or a default one; the child's call fails and it carries on, and can report. At
-`0.0.0-beta-19271` the child's model is told that the call could not be run, not the reason.
-
-A request can also be answered without the parent: in the child's own session, or along with
-another answer (an `always` that covers it, or a rejection, which rejects the session's other
-pending requests as well). For a request the parent was told about, the plugin then sends it a
-short message marked `answered="<reply>"` saying the request is settled, so it does not pass on a
-stale question; after a rejection, the message adds that the child may have stopped, and that
-`courier_send` gets it going again. A `courier_answer` that comes later anyway passes nothing on and
-says so.
-
-`courier_status` and `courier_children` list the requests a session waits on under `pending`, so a
-parent that has lost the message, after a compaction for example, can still find them. Whenever
-the plugin starts following OpenCode's events, on loading and after its event stream broke, it
-also relays the requests that spawned sessions already wait on, so one asked in the gap is not
-missed.
-
-### A child that asks a question
-
-A child that calls OpenCode's question tool shows its question in its own session only. The plugin
-wraps that tool, and once the question of a session on a roster is on screen, it sends the session
-at the top, the one its permission requests go to, a message from that child marked
-`asks="question"` and `request="question_<id>"`, waking it if it is idle. The message lists the
-questions and their options, gives them again as one line of JSON in the question tool's own input
-shape, and tells the parent to ask the person, with its question tool and exactly those questions,
-rather than answer.
-
-When the parent asks you the same questions with the same options, the two are linked: what you
-pick in the parent's session is passed to the child's waiting call, which returns it as if you had
-answered there, and the child carries on in the same turn. The parent's tool result says so. Only
-the same wording links (spacing and case aside; the options may come in any order), so a question
-of the parent's own with the same yes-or-no choices never answers a child's; when a waiting question has the same choices, the
-parent's tool result says the answers were not passed on and names the request. A parent that asked you some
-other way, in text or reworded, calls
-`courier_answer { sessionID, requestID, answers }`: one entry per question, in order, each the
-label you chose or the text you gave, or a list of labels where a question allows several. As with
-permission requests, only the session at the top can answer. Answers to one question are passed on
-one at a time, and once: a second waits for the first, and is told the question no longer waits once
-the first got through. A first that has not got through after 30 seconds gives way, and the second
-goes on; should the first still get through, the child is told twice.
-
-The question stays in the child's session too, and you can answer it there instead. Whichever
-answer comes first counts, and the other side's question is withdrawn:
-
-- answered or dismissed in the child's session: the parent's open question disappears and its
-  tool result says why, or, with none open, the parent gets a short message marked
-  `answered="elsewhere"` or `answered="dismissed"` (or `answered="failed"`, when the child's
-  question call failed, which ends its turn too). A dismissal there ends the child's turn, as
-  OpenCode's question tool does, and the message says to `courier_send` it if it should carry on;
-- answered in the parent's session: the child's question disappears;
-- dismissed in the parent's session: the parent's turn ends, as OpenCode's tool does, and the
-  child's call returns that you dismissed the question, so the child carries on without the answer
-  and can report.
-
-A question whose call is cut off stays answerable. When the child's turn is stopped (interrupted,
-or by OpenCode itself, which stops every turn in a project location after 60 minutes without
-activity there), or the server restarts or closes the project, the question is gone from the
-screen. The plugin keeps it in its storage, sends the parent a message marked `stopped="true"`, or
-`restarted="true"` when the plugin is next loaded (or half a minute later, when
-OpenCode closed only that project, keeps running, and has the plugin loaded for another), with the
-questions, and passes
-the answer on as a message to the child, which wakes it. If the parent is asking you at that
-moment, your answer goes that way without a new message. When the plugin loads, stored questions
-are dropped after 14 days, once the child is off its parent's roster, or beyond the 100 newest.
-
-`courier_status` and `courier_children` list a session's questions under `pending`, with
-`type: "question"`, the questions, and `stopped: true` for one that was cut off. A question whose
-message to the parent could not be sent, or whose record could not be stored, is listed there too,
-and can be answered all the same.
-
-A question is relayed only once OpenCode's permission check for it has passed: a child whose agent
-may not ask questions (OpenCode's `general` agent, or a `question` rule with `"effect": "deny"`)
-is refused as before, and the parent hears nothing. The plugin learns that a question is on screen
-from OpenCode's events; when no instance of it followed them for a while and one does again, it
-relays every question still waiting for that, since one shown meanwhile was not seen. The child brief tells children to use the
-question tool when the person must decide; a child can still send its question with
-`courier_send` instead, and the parent then passes your answer back with `courier_send`.
-
-### Roster
-
-`courier_spawn` records each child under its parent in the plugin's storage, so a parent that has
-lost track after a compaction or a server restart can call `courier_children` to find them again.
-A child that can no longer be looked up is still listed, with the error instead of its state.
-Entries are dropped 14 days after the child was started, when that parent's roster is read or
-the plugin is next loaded, except isolated children whose worktree is still there (see
-[Worktree cleanup](#worktree-cleanup)). If the roster cannot be written, the child still gets its task and
-`courier_spawn` says it is not on the list.
-
-### Worktree cleanup
-
-An isolated child works in a git worktree under OpenCode's data directory
-(`…/opencode/worktree/<project>/<name>`, on a detached HEAD), and nothing removes it on its own.
-When the parent has what it needs from the child, it calls `courier_cleanup { sessionID }`, which
-removes the worktree through the plugin API's `worktree.remove` and drops the child from
-`courier_children`.
-
-The worktree is kept, and the result says why, when it holds work that would otherwise be lost:
-
-- uncommitted changes, untracked files included (ignored files, such as `node_modules`, are not
-  work and go with the worktree);
-- commits that are on no branch, tag or remote-tracking ref, which is where a child's commits on
-  its detached HEAD end up. A commit on a branch survives the removal, so it does not count, and
-  neither do commits the worktree was made from (`courier_spawn` records that commit), such as a
-  parent's own unbranched work when an isolated child spawns isolated children of its own.
-
-The result lists up to 50 changed paths (an untracked directory counts once) and 50 commits. Commit
-or branch what you want to keep (`git -C <worktree> branch <name>` keeps its commits), or call
-`courier_cleanup` again with `force: true` to discard it; `force` also removes a worktree git can
-no longer read. A worktree whose directory is already gone is just dropped from the list; git
-forgets its registration on its next `git worktree prune` or `git gc`.
-
-Cleanup is explicit only. A child reporting back does not mean the parent has merged, reviewed or
-even read its work, and the parent may still send it more to do in the same worktree, so the
-plugin never removes one on its own. Isolated children whose worktree still exists are kept on
-`courier_children` past the 14 days, so they can still be found and cleaned up.
-
-`courier_cleanup` cannot tell whether the child is still running, so call it after the child has
-reported. It works on the calling session's own children.
-
-### Scheduled messages
-
-Pending `courier_later` messages are kept in the plugin's storage, and every loaded copy of the
-plugin checks for due ones every 15 seconds, so a message can arrive up to about 15 seconds late.
-OpenCode loads the plugin once per project location; the copies share one claim set, so each
-message is delivered once.
-
-They survive a server restart. After a start, OpenCode loads plugins for a project the first time
-that project is used, so messages that fell due while it was down are delivered then, not at the
-moment the server comes back. A crash between delivering a message and forgetting it can deliver
-it twice after the restart; a lost check-in would be worse.
-
-### Webhooks
-
-With the `webhook` option set (see [Receiving webhooks](#receiving-webhooks)), the plugin listens
-for HTTP deliveries and turns them into messages for subscribed sessions:
-
-- `POST /github` takes GitHub webhook deliveries. A pull request review, a review comment, a
-  comment, a pull request or issue being opened, reopened, closed (or merged) or marked ready for
-  review, or a completed check run, check suite or workflow run on a pull request goes to the
-  sessions subscribed to `owner/repo#N` and to `owner/repo`; anything else with a repository (a
-  push, a release) goes to `owner/repo` only. Pings, CI runs that have not completed, and other
-  pull request and issue actions (pushes to the branch, edits, labels, assignments, review
-  requests) wake nobody.
-- `POST /hook/<name>` takes anything else, for sessions subscribed to `<name>`. A JSON body's
-  `text`, `summary` or `message` field is delivered, otherwise the body itself.
-
-Every delivery must carry an `X-Hub-Signature-256` header: `sha256=` followed by exactly 64 hex
-digits, the HMAC-SHA256 under the shared secret. For GitHub that is of the raw body, as GitHub sends it. For
-`/hook/<name>` it is of the name, a newline and the body, so a captured delivery cannot be sent to
-another topic:
+| 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.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:
 
 ```bash
-sig=$(printf '%s\n%s' deploys "$body" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)
-curl -X POST -H "x-hub-signature-256: sha256=$sig" --data-binary "$body" http://127.0.0.1:4097/hook/deploys
+npm install -g @opencode/cli@2.0.22
 ```
 
-A missing or wrong signature gets `401`, and the body is not parsed. The check is constant-time.
-Bodies over 1 MiB (`maxBytes`) get `413`. A delivered event gets `202`, with the number of
-sessions it reached, which can be 0. The digests of the last 1000 accepted deliveries are remembered in
-memory (as lowercase hex, so re-casing the header does not get around it), and a delivery already
-accepted gets `200 already delivered`. One that reached nobody because every delivery to a session
-failed is forgotten again, so it can be retried. That stops replays of
-a captured delivery, and it also means a GitHub Redeliver of a delivery that already arrived is
-ignored. Redelivering one that failed works. Generic senders that post the same text twice should
-add something unique, such as a timestamp, to the body.
-
-A session that OpenCode no longer knows loses its subscriptions the next time a delivery for it
-fails, and `courier_subscribe` refuses a session id that does not exist.
-
-A session sees a short summary (event, repository and number, who, state or conclusion, link, and
-at most 1500 characters of a review or comment body), wrapped in `<courier from="github"
-event="...">` and followed by a note that it is outside text, to be treated as data. Review and
-comment bodies are written by whoever can comment on the repository, so subscribe sessions only to
-repositories whose commenters you trust with your agent's attention. The server log gets one line
-per delivery (event, delivery id, number of sessions), never the payload or the secret.
-
-GitHub does not report check suites on pull requests from forks (`pull_requests` is empty), so CI
-results for those reach `owner/repo` subscribers only. There is no GitHub event for a merge
-conflict.
-
-## Install
-
-Requires OpenCode V2, command `opencode2`. Its plugin API is still beta, and each release is built
-and tested against one version of it: the `@opencode-ai/plugin` peer dependency in `package.json`.
-The CLI of that version is the one known to work:
-
-```bash
-npm install -g @opencode-ai/cli@0.0.0-beta-19271
-```
+### The plugin
 
 Then install the plugin:
 
 ```bash
-opencode2 plugin add opencode-courier
+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 below, which carries a `webhook` option.
+object form shown under [Webhooks](#webhooks), which carries a `webhook` option.
 
 ### From a local clone
 
@@ -327,7 +129,66 @@ Then list it in `opencode.json` (V2 uses `plugins`, plural). A local plugin path
 }
 ```
 
-## Receiving webhooks
+## Using it
+
+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
+   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.
+
+## 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_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_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). |
+| `courier_unsubscribe` | Drops one topic, or all of a session's, e.g. once its pull request is merged. |
+
+## How children reach you
+
+The short version; the long one, with every edge, is [docs/reference.md](docs/reference.md).
+
+- **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 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 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.
+  [More](docs/reference.md#a-child-that-asks-for-permission).
+- **A child that asks a question** with OpenCode's question tool has it shown in the top session.
+  When that session asks you the same question, your answer goes to the child's waiting call as if
+  you had answered there; 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.
+  [Roster](docs/reference.md#roster), [Scheduled messages](docs/reference.md#scheduled-messages).
+- **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).
+
+## Webhooks
 
 The receiver is off unless the plugin has a `webhook` option. Put it in the **global** config
 (`~/.config/opencode/opencode.json`), since there is one receiver per OpenCode server:
@@ -343,9 +204,9 @@ The receiver is off unless the plugin has a `webhook` option. Put it in the **gl
 }
 ```
 
-From a local clone, `package` is the path to its `dist` directory instead. `"webhook": true`
-takes every default. If the option is given more than once, for example in a project's config as
-well, the first location to load wins, and the others log that their settings are ignored.
+From a local clone, `package` is the path to its `dist` directory instead. `"webhook": true` takes
+every default. If the option is given more than once, for example in a project's config as well, the
+first location to load wins, and the others log that their settings are ignored.
 
 | Option | Default | |
 |---|---|---|
@@ -355,79 +216,37 @@ well, the first location to load wins, and the others log that their settings ar
 | `secretEnv` | `COURIER_WEBHOOK_SECRET` | Environment variable holding it, when there is no `secretFile`. |
 | `maxBytes` | `1048576` | Largest body accepted. |
 
-The secret is never read from `opencode.json` itself (a `secret` key is refused), so the config
-can be committed. Make one with `openssl rand -hex 32 > ~/.config/opencode/courier-webhook-secret`
-and `chmod 600` it. A file is the safer choice with `opencode2 service start`, whose environment
-may not be your shell's. Without a usable secret the receiver does not start, and the server log
-says why.
+The secret is never read from `opencode.json` itself (a `secret` key is refused), so the config can
+be committed. Make one with `openssl rand -hex 32 > ~/.config/opencode/courier-webhook-secret` and
+`chmod 600` it. A file is the safer choice with `opencode service start`, whose environment may not
+be your shell's. Without a usable secret the receiver does not start, and the server log says why.
 
 On GitHub, add a webhook to the repository (Settings → Webhooks) with content type
-`application/json`, the same secret, and the events you want (pull request reviews, review
-comments, issue comments, pull requests, check suites or workflow runs). GitHub must reach the
-receiver, and by default it only listens on `127.0.0.1`: forward a public URL to it with a tunnel
-you trust (`cloudflared tunnel --url http://127.0.0.1:4097`, `ngrok http 4097`, or
-`smee --url https://smee.io/<channel> --target http://127.0.0.1:4097/github`, which needs no
-inbound port at all) and use `<public URL>/github` as the payload URL. Whatever you expose, only
-signed deliveries are acted on.
+`application/json`, the same secret, and the events you want (pull request reviews, review comments,
+issue comments, pull requests, check suites or workflow runs). GitHub must reach the receiver, and
+by default it only listens on `127.0.0.1`: forward a public URL to it with a tunnel you trust
+(`cloudflared tunnel --url http://127.0.0.1:4097`, `ngrok http 4097`, or `smee --url
+https://smee.io/<channel> --target http://127.0.0.1:4097/github`, which needs no inbound port at
+all) and use `<public URL>/github` as the payload URL. Whatever you expose, only signed deliveries
+are acted on.
 
 The receiver starts when OpenCode loads the plugin, which after a server start happens the first
-time a project is used. Until then deliveries fail; GitHub does not retry them on its own, but
-lists them under Recent Deliveries with a Redeliver button.
-
-## Using it
-
-1. Keep the background server running so sessions can be woken while you are away
-   (`opencode2 service start`; `opencode2 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](#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](#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 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.
-
-## Real models
-
-`e2e/real-model.sh` runs the same live server with a real model and asks the parent to fan a small
-task out to two children. It reports which tools the parent called and in what order, whether it
-ended its turn instead of polling, whether each child called `courier_send`, and whether each report
-woke the idle parent. By default it uses a free model on OpenCode Zen, which needs no key:
-
-```bash
-OPENCODE_BIN=$(which opencode2) e2e/real-model.sh
-COURIER_MODEL=muse-spark-1.3-contributor-free OPENCODE_BIN=$(which opencode2) e2e/real-model.sh
-COURIER_SCENARIO=permission OPENCODE_BIN=$(which opencode2) e2e/real-model.sh
-COURIER_SCENARIO=question OPENCODE_BIN=$(which opencode2) e2e/real-model.sh
-```
-
-With `COURIER_SCENARIO=permission` it runs the permission relay instead: one child whose command
-needs an approval, and the script in the person's place. It checks that the parent asks rather
-than answering by itself, answers its question with `once`, and checks that the parent passes that
-on with `courier_answer` and the child runs its command and reports.
-
-With `COURIER_SCENARIO=question` it runs the question relay: one child whose task is to find out
-from the person which of three greetings to use, without being told how to ask. The script plays
-the person in the parent's session. It checks that the child asks with its question tool (or
-records that it sent its question with `courier_send` instead), that the parent asks the person
-rather than answering by itself, with the child's options, and that the person's answer reaches the
-child, which reports it.
+time a project is used. Until then deliveries fail; GitHub does not retry them on its own, but lists
+them under Recent Deliveries with a Redeliver button.
 
-On `opencode2 v0.0.0-beta-19271`, `longcat-2.5-preview-free`, `muse-spark-1.3-contributor-free`
-and `nemotron-3-ultra-free` complete the fan-out with both reports waking the parent, after the
-tool results were tuned to say plainly that the parent should end its turn. How to run it, what
-each model did, what was tuned and why: [docs/real-model.md](docs/real-model.md). It costs nothing
-on the free models, and it is not part of CI.
+Once it runs, `courier_subscribe` ties a session to a topic and every matching delivery arrives as a
+message, queued behind any running turn and waking the session if idle:
 
-## Roadmap
+- `POST /github` takes GitHub webhook deliveries: reviews, comments, pull requests and issues being
+  opened, closed or merged, and completed CI runs reach the sessions subscribed to `owner/repo#N`
+  and `owner/repo`; other events with a repository reach `owner/repo`.
+- `POST /hook/<name>` takes anything else, for sessions subscribed to `<name>`: a JSON body's
+  `text`, `summary` or `message` field, otherwise the body itself.
 
-Tracked as [issues](https://github.com/ivopogace/opencode-courier/issues).
+Every delivery must be signed (`X-Hub-Signature-256`, HMAC-SHA256 under the shared secret), replays
+are refused, and what a session sees is a short summary marked as outside text. Which events wake
+whom, the signing scheme for `/hook/<name>`, limits and status codes: [the
+reference](docs/reference.md#webhooks).
 
 ## Development
 
@@ -436,241 +255,38 @@ bun install
 bun test           # unit tests, with a fake plugin context
 npm run typecheck
 npm run build      # emits dist/
-OPENCODE_BIN=$(which opencode2) npm run test:e2e   # live test, see below
-OPENCODE_BIN=$(which opencode2) e2e/real-model.sh  # with a real model, see Real models
+OPENCODE_BIN=$(which opencode) npm run test:e2e   # live test, about two minutes, no API key
+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, so no API key is needed. It checks that a parent's spawn completes, that the parent
-gets a new turn after its own has ended once the child reports (shared and `isolate: true`), that
-`courier_status` reports and fails readably, that a child runs on the model its parent was started
-with rather than the default one, that a child whose model request is refused is reported to its
-idle parent, once and with the error, that a child's permission request (a project rule makes it
-ask before one command) wakes its idle parent once, with what it asks for and the choices, that
-`courier_status` shows it pending and `courier_answer` passes the answer back, `once` to a shared
-child and `reject` to an isolated one, after which the child carries on and reports, that a request
-answered in the child's own session gets the parent a message that it is settled and a later
-`courier_answer` passes nothing on, that a child's question (the stand-in model calls OpenCode's
-question tool) wakes its idle parent once, with the questions, which the parent asks the person in
-its own session, that `courier_status` shows it pending, and that the person's answer there reaches
-the child: single choice, multi-select, a typed answer (from an isolated child), and through
-`courier_answer` from a parent that relabelled the options or reworded the question, which is then
-told its answers were not passed on; that answering in the child's session
-withdraws the parent's question, that a dismissal on either side is passed to the other, that a
-question whose child's turn was interrupted, or both turns, or that was open across a server
-restart, still reaches the child with the answer, as a message, and that a question of a child's
-child goes to the session at the top; that a `courier_later` message wakes an idle parent
-(with its delay sent as a string, as some models send it),
-that a cancelled one never arrives, that a pending one is delivered after a server restart, that
-`courier_children` lists the two children a parent spawned, before and after that restart, that
-a recorded GitHub review delivery (`e2e/fixtures/pull_request_review.json`), signed, wakes an idle
-session subscribed with `courier_subscribe`, once, while unsigned and wrongly signed ones are
-refused, and that `courier_cleanup` removes an isolated child's clean worktree but keeps one with an
-uncommitted file until asked with `force`. Last, it packs the package with `npm pack`, serves the
-tarball from a stand-in registry (`e2e/registry.mjs`), installs it with `opencode2 plugin add
-opencode-courier` and checks that its tools load from the installed copy. It takes about two
-minutes and needs node, npm, bun, git, curl, jq and openssl.
-
-CI (`.github/workflows/ci.yml`) runs both on every push to `main` and every pull request, with the
-OpenCode CLI at the same version as the pinned plugin API.
-
-### Releasing
-
-A release starts from GitHub and ends with a maintainer's 2FA approval on npm; no tag needs
-creating or pushing by hand. Three workflows under `.github/workflows/` take turns:
-
-1. **Start a release** (Actions → Start a release → Run workflow, from `main`, or
-   `gh workflow run release-start.yml -f version=patch`). `version` is `patch`, `minor`, `major`
-   or an exact version such as `0.2.0-beta.1`. The workflow bumps `version` in `package.json`,
-   checks that the current version is tagged, that the new one is higher and that neither a
-   `vX.Y.Z` tag, a `release-X.Y.Z` branch nor npm has it, then pushes the branch `release-X.Y.Z`
-   and opens the pull request "Release X.Y.Z".
-2. GitHub holds the checks of a pull request that GitHub Actions opened: select **Approve
-   workflows to run** in its merge box, review it, and squash-merge it like any other pull
-   request (`main` takes nothing else).
-3. **Tag the release** runs on every push to `main` that touches `package.json`. When the version
-   there has no tag yet, it tags the commit `vX.Y.Z` and dispatches **Release** on that tag. A
-   version whose tag exists is left alone, so a push that does not bump the version does nothing.
-4. **Release** (`release.yml`), on the tag, runs the CI workflow, checks that the tag matches the
-   `version` in `package.json`, builds, and runs `npm stage publish` from the `npm` environment,
-   authenticated as the repository variable `NPM_AUTH` says: with the `NPM_TOKEN` secret
-   (`token`, the default) or through npm trusted publishing (`oidc`), both below. It adds a
-   provenance attestation, which links the package to the workflow run that built it, unless
-   `NPM_PROVENANCE` turns it off. A prerelease (`0.2.0-beta.1`) is staged for the `next`
-   dist-tag.
-5. It then creates a **draft** GitHub release with generated notes (marked as a prerelease for
-   one), so nothing is announced yet.
-6. A maintainer reviews the staged version and approves it with 2FA: on npmjs.com under Staged
-   Packages, or with `npm stage list` and `npm stage approve <id>`. The version is live from then.
-7. Publish the draft release: `gh release edit vX.Y.Z --draft=false`, or Publish release on
-   GitHub.
-
-Why the tag is dispatched rather than pushed into `on: push: tags`: Tag the release pushes it with
-the workflow's `GITHUB_TOKEN`, and GitHub starts no workflow for an event made with that token,
-`workflow_dispatch` excepted. The dispatch names the tag as its ref, so `GITHUB_REF` is the tag:
-that is what the `npm` environment's `v*` rule and Release's tag check look at, and the rule stays
-as it is. A tag pushed by hand still triggers Release as before.
-
-**Dry runs**, to exercise the flow without releasing. Start a release with `dry_run` computes the
-bump and shows the diff, pushing nothing. Tag the release with `dry_run` (the default when run by
-hand, and it runs on any branch) checks the version and the tag, builds and runs
-`npm stage publish --dry-run`, which also refuses a version npm already has; so run it on the
-release branch to rehearse a release: `gh workflow run release-tag.yml --ref release-X.Y.Z`.
-Release itself takes a `dry_run` on a tag cut with this flow (v0.1.2 onward; earlier tags carry a
-`release.yml` without the dispatch trigger), `gh workflow run release.yml --ref vX.Y.Z
--f dry_run=true`: the environment admits the tag, the token is checked in token mode (a missing
-one is a warning there), the package is packed and nothing is staged or released.
-
-The flow needs the repository setting **Allow GitHub Actions to create and approve pull requests**
-(Settings → Actions → General → Workflow permissions); without it Start a release stops at opening
-the pull request. Should a release pull request show neither checks nor the approval banner, close
-and reopen it: that is an event a person made, and CI runs on it as on any pull request.
-
-**By hand**, should a step fail. The bump is an ordinary pull request that changes `version` in
-`package.json`; once it is merged, Tag the release tags it. If that run failed, tag the merge
-commit yourself and the tag push runs Release as it always did:
-
-```bash
-git fetch origin && git tag -a vX.Y.Z -m vX.Y.Z origin/main && git push origin vX.Y.Z
-```
-
-If the tag exists but Release did not start: `gh workflow run release.yml --ref vX.Y.Z`. If staging
-fails, nothing reached npm and the version is still free. Re-running the job reuses the workflow
-file at the tag, so after fixing `release.yml` move the tag to the fixed commit instead:
-`git push origin :refs/tags/vX.Y.Z`, then tag and push again (or re-run Tag the release on
-`main` with `dry_run` off).
-
-Repository variables are set under Settings → Secrets and variables → Actions → Variables, and a
-re-run of the job picks a change up without moving the tag.
-
-**The token** (`NPM_AUTH` unset or `token`). `NPM_TOKEN` is a secret of the `npm` environment
-(repository Settings → Environments → `npm` → Environment secrets). It holds an npm granular
-access token, made on npmjs.com under Access Tokens → Generate New Token → Granular Access Token,
-with:
-
-- Packages and scopes: Read and write, for `opencode-courier` only;
-- **Bypass two-factor authentication left off.** Such a token can stage a version but not publish
-  one, so nothing goes live without a maintainer's 2FA approval, even if the token leaks;
-- an expiry date. npm caps how long a token with write access lives; when it has expired or been
-  revoked, the job stops at "Check the npm token", and a new token replaces the secret.
-
-Limit the `npm` environment to version tags: under its Deployment branches and tags, choose
-Selected branches and tags and add the tag pattern `v*`. Otherwise a workflow on any branch that
-names the environment can read the secret. A tag ruleset on `v*` closes the remaining gap, with
-two things to know: Tag the release creates the tags with the workflow's token, so a rule that
-restricts creation needs the GitHub Actions app in the ruleset's bypass list or the tag push fails;
-and a rule against deletion also blocks the move-the-tag recovery above for anyone not in that
-list.
-
-If "Check the npm token" passes but staging fails with E403, look at the package's Publishing
-access on npmjs.com (the package's Settings): the option that disallows tokens refuses this one
-too.
-
-The job stages with `--provenance`, signed through GitHub's OIDC token and Sigstore. Should npm
-refuse the attestation, set the repository variable `NPM_PROVENANCE` to `false` and re-run the job,
-which then stages without one; any value other than `true` or `false` (in any case) stops the job.
-
-**Trusted publishing** (`NPM_AUTH` set to `oidc`) needs no stored token, but does not work for this
-repository yet: npm rejects the immutable OIDC subject claims GitHub issues for repositories
-created after 2026-07-15 ([npm/cli#9969](https://github.com/npm/cli/issues/9969)), with `OIDC token
-exchange error - package not found`. Once npm fixes that:
-
-1. On npmjs.com, give the package a trusted publisher: this repository, workflow `release.yml`,
-   environment `npm`, allowed to stage only.
-2. Set the repository variable `NPM_AUTH` to `oidc` and release. In this mode the job does not pass
-   `NPM_TOKEN`, so a failed exchange cannot fall back to it: npm falls back to the placeholder
-   token setup-node configures and the job fails with E401. Before staging it logs the claims of
-   its OIDC token (repository, workflow, environment, ref), so a mismatch with the trusted
-   publisher shows, and it stages with `--loglevel verbose`, because npm reports a failed exchange
-   only there. Trusted publishing adds the provenance attestation itself.
-3. Once a release has been staged that way, revoke the token on npmjs.com and delete the
-   `NPM_TOKEN` secret. To go back, set `NPM_AUTH` to `token` or delete the variable.
-
-To stage by hand instead (npm 11.15.0 or later, Node 22.14 or later):
-
-```bash
-git checkout vX.Y.Z
-npm install && npm run build
-npm login
-npm stage publish --access public   # add --tag next for a prerelease
-```
-
-Approve the staged version with 2FA as above, then create the release:
-`gh release create vX.Y.Z --verify-tag --generate-notes` (add `--prerelease` for a prerelease). A
-version staged by hand has no provenance attestation.
-
-A prerelease version (`1.2.0-beta.1`) is staged for the `next` dist-tag and its release is marked
-as a prerelease. Nothing moves `next` after a stable release, so it can point at an older version
-than `latest`; that only matters to someone installing `opencode-courier@next`, and
-`npm dist-tag rm opencode-courier next` removes the tag until the next prerelease sets it again.
-
-CI also checks the package as published: `publint` for `package.json` and `exports`, and
-`@arethetypeswrong/cli` for the type declarations.
-
-The plugin API is still beta and pinned to an exact version in `package.json`; bump it
-deliberately and re-run both test suites.
-
-### Notes on the V2 plugin API
-
-Found while testing against `0.0.0-beta-19271`:
-
-- A plugin tool is only reachable through code mode's `execute` tool unless it is registered with
-  `options: { codemode: false }`. The courier tools are direct tools.
-- A tool whose result `metadata` holds an `undefined` value never completes: the call stays
-  `running` and no error is reported. Results here drop `undefined` keys.
-- A plugin cannot add an HTTP route to OpenCode's own server. The nearest thing, `rpc.register`,
-  is reached through the authenticated `/api/rpc` endpoint with a JSON envelope, so neither
-  GitHub's headers nor the raw body its signature covers would get through. The webhook receiver
-  is therefore its own small listener inside the OpenCode process, shared by the plugin's
-  per-location instances. It waits for the previous listener to finish closing before it binds,
-  as after a plugin reload, and if binding fails, the next instance to load tries again. A plugin's options come from a `{ "package", "options" }` entry in
-  `plugins`, which takes a local directory as `package` too.
-- OpenCode errors such as `Session.NotFoundError` can arrive with an empty message, so the tools
-  rethrow them with the tag and session id.
-- OpenCode decodes a tool's input with its own copy of `effect`, not the plugin's, and schema
-  checks and transformations from the plugin's copy do not survive that: `Schema.Finite` refuses
-  the number `2` ("Expected a finite number"), and `Schema.FiniteFromString` fails with "Cannot
-  convert a symbol to a number". Tool inputs use plain schemas and the tools validate the values
-  themselves; a unit test keeps it that way.
-- `permission.asked` and `permission.replied` reach a plugin's `event.subscribe()`, as
-  `session.execution.failed` does. OpenCode keeps pending permission requests per location, and a
-  plugin instance's `permission` domain answers from its own location's, so a request of an
-  isolated child is answered through the instance loaded in the child's worktree. The plugin keeps
-  the domain of every loaded instance and answers through the one that holds the request.
-- A permission request rejected without a message ends the asking session's turn ("The user
-  declined this tool call"); with a message, only the tool call fails, and its model is told that
-  the call could not be run, not the message.
-- A plugin can replace the `execute` of any tool, OpenCode's own included, with `tool.transform`
-  and the editor's `update` (an id that is missing is ignored). OpenCode's question tool is such a
-  tool, `question`, added by a plugin of OpenCode's own that loads before external ones. The
-  promise API hands the original `execute` out only as a function returning a promise, run
-  without an abort signal, so the call cannot be stopped once started. OpenCode's form service
-  withdraws a question's form when the call that asked it is interrupted, and nothing else in the
-  plugin API can withdraw or answer a form: the context has no form domain. The question relay
-  needs to withdraw a child's question once its parent's answer is in, so the plugin's default
-  export is an Effect plugin (`{ id, effect }`): it runs the promise plugin through `fromPromise`
-  from `@opencode-ai/plugin/promise/adapter`, which is what OpenCode does with a promise plugin,
-  then wraps the question tool with the Effect API, where the original `execute` is an Effect
-  that can be raced and interrupted. The plugin's `effect` is the same version as OpenCode's
-  (`4.0.0-rc.112` at the pinned version), and Effects of the two copies compose. A plugin loaded
-  after this one that replaces `question` as well would drop the relay.
-- OpenCode's question tool asks through a form. `form.created` reaches `event.subscribe()` (form
-  events are ephemeral, never stored), of every location's plugin instance whichever location the
-  form is in, with the form's `metadata.tool.id`, the id of the call; the
-  form is created only after the call's permission check has passed. A person dismissing a form
-  makes the tool die with `QuestionTool.CancelledError`, which ends the asking session's turn
-  ("The user dismissed this question"). Forms live in memory: a restart drops them, and the call
-  that asked stays `running` until the session's next turn marks it aborted. When OpenCode closes
-  a location, as on a graceful server shutdown, it unloads the plugin there first and then
-  withdraws every open form, which looks to the tool exactly like the person dismissing it; the
-  relay treats a call that ends after its plugin instance unloaded as cut off, not dismissed.
-- OpenCode stops every turn in a project location after 60 minutes without a stored session event
-  there (`packages/core/src/location-activity.ts`), which withdraws any question still open. A
-  tool call has no timeout of its own.
-- `Schema.Number` advertises the strings `"Infinity"`, `"-Infinity"` and `"NaN"` in its JSON
-  Schema, so models are offered a string where a number is meant. Some send numbers as strings
-  regardless, so `courier_later` takes `delayMinutes` as either.
+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. 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).
+
+## 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