opencode-courier 0.2.1 → 0.2.3

package/README.md

@@ -1,36 +1,109 @@
 # 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)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=ivopogace_opencode-courier&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=ivopogace_opencode-courier)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=ivopogace_opencode-courier&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=ivopogace_opencode-courier)
 [![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.
+![A parent spawns two slow children, writes a README itself, and is woken by each report](docs/demo-async-tui.gif)
+
+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.
+- **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.
 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.
+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.
 
-> **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).
+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."*
@@ -40,73 +113,36 @@ 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).
 
 ## 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.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.23
+npm install -g @opencode/cli@2.0.26
 ```
 
 ### The plugin
 
-Then install the plugin:
-
 ```bash
 opencode plugin add opencode-courier
 ```
@@ -115,10 +151,15 @@ This installs the package from npm and adds `"opencode-courier"` to `plugins` in
 configuration (`~/.config/opencode/opencode.json`). To receive webhooks, replace that entry with the
 object form shown under [Webhooks](#webhooks), which carries a `webhook` option.
 
+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
 ```
 
@@ -136,12 +177,13 @@ 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.
+   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. 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
@@ -158,8 +200,8 @@ Then list it in `opencode.json` (V2 uses `plugins`, plural). A local plugin path
 | `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_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)). |
+| `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). |
@@ -181,11 +223,20 @@ The short version; the long one, with every edge, is [docs/reference.md](docs/re
   [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).
+  you had answered there. Whichever answer reaches the child first counts, in its session, in the
+  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).
+- **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).
 - **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).
+- **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, 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).
@@ -261,34 +312,28 @@ 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. 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. 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,10 @@
+/**
+ * Bounded collections of remembered ids: plain `Set`s and `Map`s that drop their oldest entry past
+ * a bound. Functions over the built-in types rather than a class, since the process-wide ones are
+ * shared with copies of the plugin loaded before an update, which call `.has` and `.add` on them.
+ * Imports nothing of the plugin's.
+ */
+/** 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,21 @@
+/**
+ * Bounded collections of remembered ids: plain `Set`s and `Map`s that drop their oldest entry past
+ * a bound. Functions over the built-in types rather than a class, since the process-wide ones are
+ * shared with copies of the plugin loaded before an update, which call `.has` and `.add` on them.
+ * Imports nothing of the plugin's.
+ */
+/** 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. */
@@ -23,24 +24,6 @@ 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;
 /**
@@ -49,6 +32,18 @@ export declare const MAX_LISTED = 50;
  * result says what is in it.
  */
 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>;
 /**

package/dist/cleanup.js

@@ -1,24 +1,10 @@
 import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
-import { rosterKey } from "./roster.js";
-/** Why a worktree in this state must be kept, or undefined when removing it loses nothing. */
-export function keepReason(state) {
-    const reasons = [
-        state.changes.length ? `${count(state.changes.length, "uncommitted change")} (${preview(state.changes)})` : "",
-        state.commits.length
-            ? `${count(state.commits.length, "commit")} on no branch, tag or remote (${preview(state.commits)})`
-            : "",
-    ].filter(Boolean);
-    return reasons.length ? reasons.join(" and ") : undefined;
-}
-function count(n, noun) {
-    return `${n} ${noun}${n === 1 ? "" : "s"}`;
-}
+import { isAbsolute } from "node:path";
+import { keepReason } from "./notices.js";
+import { remove, rosterKey } from "./roster.js";
 /** At most this many changes and commits are returned; the reason still counts them all. */
 export const MAX_LISTED = 50;
-function preview(items) {
-    return items.length > 5 ? `${items.slice(0, 5).join(", ")}, ...` : items.join(", ");
-}
 /**
  * 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
@@ -31,7 +17,7 @@ export async function cleanup(ports, parentID, input) {
     if (!entry.isolated)
         throw new Error(`${input.sessionID} ran in ${entry.directory}, not in a worktree of its own; there is nothing to remove.`);
     const { directory } = entry;
-    const forget = () => ports.storage.remove(rosterKey(parentID, input.sessionID));
+    const forget = () => remove(ports.storage, parentID, input.sessionID);
     // With force the state only decides whether there is anything left to remove, so a worktree git
     // can no longer read is still removed.
     const state = await ports
@@ -59,8 +45,41 @@ export async function cleanup(ports, parentID, input) {
     await forget();
     return { sessionID: input.sessionID, directory, outcome: "removed" };
 }
+/** Names the git to run, by absolute path, overriding the places `GIT_LOCATIONS` lists. */
+export const GIT_ENV = "OPENCODE_COURIER_GIT";
+/**
+ * Where git is looked for, in order: its usual install locations, never `PATH`, so a writable
+ * directory early in `PATH` cannot put another program in its place.
+ */
+export const GIT_LOCATIONS = {
+    posix: [
+        "/usr/bin/git",
+        "/usr/local/bin/git",
+        "/opt/homebrew/bin/git",
+        // NixOS, and nix-darwin.
+        "/run/current-system/sw/bin/git",
+    ],
+    win32: [String.raw `C:\Program Files\Git\cmd\git.exe`, String.raw `C:\Program Files (x86)\Git\cmd\git.exe`],
+};
+/**
+ * The git to run: `OPENCODE_COURIER_GIT` when it is an absolute path, otherwise the first of
+ * `GIT_LOCATIONS` that exists. Throws when there is none.
+ */
+export function findGit(env = process.env, platform = process.platform, exists = existsSync) {
+    const named = env[GIT_ENV]?.trim();
+    if (named) {
+        if (!isAbsolute(named))
+            throw new Error(`${GIT_ENV} must be an absolute path, not ${named}.`);
+        return named;
+    }
+    const locations = GIT_LOCATIONS[platform === "win32" ? "win32" : "posix"];
+    const found = locations.find((path) => exists(path));
+    if (!found)
+        throw new Error(`git is in none of ${locations.join(", ")}; set ${GIT_ENV} to its absolute path.`);
+    return found;
+}
 function git(directory, args) {
-    return new Promise((resolve, reject) => execFile("git", ["-C", directory, ...args], { maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => error ? reject(new Error(`git ${args[0]} in ${directory}: ${stderr.trim() || error.message}`)) : resolve(stdout)));
+    return new Promise((resolve, reject) => execFile(findGit(), ["-C", directory, ...args], { maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => error ? reject(new Error(`git ${args[0]} in ${directory}: ${stderr.trim() || error.message}`)) : resolve(stdout)));
 }
 /** The commit a worktree is on, or undefined when git cannot tell. */
 export function headOf(directory) {

package/dist/courier.d.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from "@opencode/plugin";
-import type { Prompt } from "./question.js";
+import { type Prompt } from "./notices.js";
 import { type RosterStorage } from "./roster.js";
 type Context = Plugin.Context;
 /** The slice of the plugin context the courier tools use; tests pass a fake. */
@@ -48,10 +48,6 @@ export interface StatusInput {
 export interface ChildrenInput {
     readonly sessionID?: string;
 }
-/** Closes a tool result after which the caller most likely has nothing left to do. */
-export declare const END_TURN = "If nothing else is left to do now, end your turn by replying without calling more tools.";
-export declare function childBrief(parentID: string, task: string): string;
-export declare function envelope(from: string, message: string, attributes?: Record<string, string>): string;
 /** Creates a child session, hands it the task and returns at once; the child reports back with courier_send. */
 export declare function spawn(ports: CourierPorts, parentID: string, input: SpawnInput): Promise<{
     rosterError?: string | undefined;

package/dist/courier.js

@@ -1,24 +1,5 @@
+import { childBrief, envelope } from "./notices.js";
 import { current, record } from "./roster.js";
-/** Closes a tool result after which the caller most likely has nothing left to do. */
-export const END_TURN = "If nothing else is left to do now, end your turn by replying without calling more tools.";
-export function childBrief(parentID, task) {
-    return [
-        `You were started by session ${parentID} through opencode-courier.`,
-        "",
-        `When you finish, or need a decision you cannot make yourself, call courier_send with sessionID "${parentID}" and a short report.`,
-        "That message wakes the parent. It is the only way the parent hears from you, so do not end without sending it.",
-        "If you need the person to decide something, use your question tool; it reaches them through the session that started you.",
-        "",
-        "Task:",
-        task,
-    ].join("\n");
-}
-export function envelope(from, message, attributes = {}) {
-    const extra = Object.entries(attributes)
-        .map(([name, value]) => ` ${name}="${value}"`)
-        .join("");
-    return `<courier from="${from}"${extra}>\n${message}\n</courier>`;
-}
 function titleOf(task) {
     const line = task.trim().split("\n")[0] ?? "";
     return line.length > 60 ? `${line.slice(0, 57)}...` : line;
@@ -34,6 +15,15 @@ async function inheritedModel(ports, parentID, agent) {
     const named = await ports.agent.get({ agentID: agent, location: { directory: ports.directory } });
     return named.data.model ? undefined : parent.model;
 }
+/** Removes a worktree made for a child that was never created; one that cannot be removed stays. */
+async function dropWorktree(ports, directory) {
+    try {
+        await ports.worktree.remove({ projectID: ports.projectID, directory, force: false });
+    }
+    catch {
+        // The spawn's own failure is the one to report.
+    }
+}
 /** Creates a child session, hands it the task and returns at once; the child reports back with courier_send. */
 export async function spawn(ports, parentID, input) {
     // A failed lookup must not keep the child from starting; it then runs on OpenCode's default.
@@ -54,9 +44,7 @@ export async function spawn(ports, parentID, input) {
         .catch(async (error) => {
         // No session will ever use the fresh worktree, and nothing records it, so it goes now.
         if (directory)
-            await ports.worktree
-                .remove({ projectID: ports.projectID, directory, force: false })
-                .catch(() => undefined);
+            await dropWorktree(ports, directory);
         throw error;
     });
     // Recorded before the prompt, so a child that exists is on the roster even if prompting fails. A