opencode-courier 0.10.3 → 0.11.1

package/README.md

@@ -6,9 +6,6 @@ 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)
@@ -16,15 +13,14 @@ polling.
 
 https://github.com/user-attachments/assets/d7cf74f8-15b3-4cc1-866e-b75ba0ac3f8a
 
-The tree panel, the asks inbox, the edge cases and memory on the live terminal UI, narrated
-([what it shows](#demos)).
+A narrated tour of the terminal UI: the tree panel, the asks inbox, failing children and memory.
 
 ## Quickstart
 
 ```bash
-npm install -g @opencode/cli@2.1.2   # 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
+npm install -g @opencode/cli@2.1.4   # OpenCode V2, the version courier is tested on
+opencode plugin add opencode-courier
+opencode
 ```
 
 Paste this prompt:
@@ -33,207 +29,65 @@ Paste this prompt:
 > `` `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`). Each release is pinned to one V2 version and tested against it end to end;
-the current one is tested on **OpenCode 2.1.2**. CI also runs the live suite on the newest OpenCode
-release, on `main` and nightly. Older releases: [every release](docs/reference.md#the-opencode-version).
-
-## Courier or the built-in subagent tool?
-
-OpenCode V2's own [`subagent` tool](https://opencode.ai/v2/docs/agents) starts an agent with fresh
-context in a child session; the parent waits for its final answer or, with `background: true`, is
-notified when the child finishes. Use it when one result back is all you need. Use courier when the
-work needs more:
-
-- **Messages from the child, mid-run:** 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 (`courier_later`) or
-  a [webhook](#webhooks) starts a new turn in a session that has ended its own.
-- **Worktree isolation:** `isolate: true` gives a child its own git worktree, so children edit files
-  in parallel; each commits on `courier/<its session ID>` and reports that branch for its parent to
-  merge ([nested isolation](docs/reference.md#nested-isolation)).
-- **Relaying to you:** a child's permission requests and questions reach you through the parent. A
-  request is approved in OpenCode's own permission prompt in the parent's session, never by its
-  model; a form only you can answer is pointed out to you.
-
-## How it works
-
-A parent calls `courier_spawn`, gets a session id back at once and ends its turn. The child works
-on its own and, when done or stuck, calls `courier_send` with the parent's id, a status and what it
-produced. The message lands in the parent's inbox through OpenCode's own API, the way OpenCode's
-background subagents report, and starts a new turn if the parent is idle. Delivery is `steer` by
-default (into the target's running turn, or a new one if idle); `queue: true` waits until the current
-turn ends.
-
-## Demos
-
-The video at the top (3:01, narrated) is the TUI driven in `tmux` on the live test's scripted
-stand-in model, so each scene is real plugin behaviour, the thing each step points at framed:
-
-- **A join group:** one member reports and its report is held with the group, while the other waits
-  on a permission request, so the footer says one is waiting on you. `/courier tree` opens the panel,
-  with Digby and a row for each child saying what it waits on.
-- **A click opens a child:** a click on a row opens that child's session, the panel following you
-  there: one waits on the permission, the other shows the report it sent.
-- **The asks inbox:** back on the parent, you allow the permission from the inbox (`ctrl+x k`), and
-  both reports reach the parent in one message; the parent notes a lesson with `courier_note`.
-- **A child whose turn fails:** OpenCode shows "Session failed", the parent is told, and the
-  `/courier tree` row reads `failed`.
-- **A child that ends its turn without a report:** the parent is told, and the row says so.
-- **`/courier stop`:** pick the session, confirm, and it is stopped.
-- **A form only you can answer:** a child's web search shows a form; the footer, the panel row and
-  the asks inbox point to it, and answering it there wakes the parent.
-- **The memory view:** `/courier memory` lists the project's session trees, each with how it was
-  split, how its parts went and its lesson; `p` pins one, listed first and never swept.
-- **Recall from another tree:** a new tree's `courier_recall` lists the pinned record first, lesson
-  and all.
-
-## Recursive orchestration
-
-A session can split a goal across child sessions, each child deciding in turn whether to split its
-part again, with the results checked and integrated at every level on the way back up. The playbook
-ships as the OpenCode skill `courier-orchestrate`, listed in every session: models load it at the
-start of an implementation task that may have independent parts, and `/skills` in the TUI attaches
-it to your prompt ([what it says](docs/reference.md#the-courier-orchestrate-skill)).
-
-## Install
+The parent starts both children and ends its turn. Each report wakes it, and it replies
+`RESULTS 391 1024`. Free models sometimes stall; if nothing moves for a few minutes, send the
+prompt again.
 
-### Supported OpenCode version
+## Why courier
 
-Requires OpenCode V2: the `opencode` command from `@opencode/cli` (also installed as `opencode2`).
-Each release is built and tested against exactly one OpenCode V2 version; a row lists the releases
-pinned to its version. OpenCode never checks it: the plugin loads on any V2 host, and on another
-version than the pinned one writes one line to the server log
-([more](docs/reference.md#the-opencode-version)).
+OpenCode's own [`subagent` tool](https://opencode.ai/v2/docs/agents) hands back a child's final
+answer. Use it when one result is all you need. Use courier for more:
 
-<!-- compat-table:start rows=3: generated by script/compat-table.ts from the release tags -->
-| opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
-|---|---|
-| 0.10.2, 0.10.3 | 2.1.2 |
-| 0.10.1 | 2.1.0 |
-| 0.7.3, 0.8.0, 0.9.0, 0.10.0 | 2.0.32 |
-<!-- compat-table:end -->
+- **Messages mid-run.** A child reports progress or asks its parent at any time.
+- **Waking an idle session.** A message, a schedule or a GitHub webhook starts a new turn.
+- **Parallel edits.** `isolate: true` gives a child its own git worktree and branch to merge.
+- **Asks reach you.** A child's permission requests and questions come to you through the top
+  session. Only you approve a request, in OpenCode's own prompt.
+- **Trees.** A child may split its part again, within limits you set.
 
-Older releases and their versions: [every release](docs/reference.md#the-opencode-version).
+## How it works
 
-The [terminal part](#in-the-terminal) relies on the host to provide its UI modules and is tested on
-OpenCode 2.1.2 only; the server part works on older V2 hosts from 2.0.4 on.
+A parent calls `courier_spawn`, gets the child's session id at once, and ends its turn. When done
+or stuck, the child calls `courier_send` with a status (`done`, `partial`, `blocked` or `failed`).
+The message lands in the parent's inbox and starts a new turn if the parent is idle.
 
-Check yours with `opencode --version`, and install the matching CLI with:
+Children started with the same `group` report together, in one message. A child that fails (a
+rate or quota limit with when it lifts), or ends its turn without reporting, is reported to its
+parent. A message that does not wake its session is sent once more, then shown as `stalled`. Children, held reports and scheduled messages
+survive a restart. The `courier-orchestrate` skill, listed in every session, tells a model when to
+split a task and how to check and merge the parts. Every detail: [the reference](docs/reference.md).
 
-```bash
-npm install -g @opencode/cli@2.1.2
-```
+## Install
 
-### The plugin
+Requires OpenCode V2: the `opencode` command from `@opencode/cli`. Each release is tested against
+one OpenCode version; this one is tested on **OpenCode 2.1.4** (check with `opencode --version`).
 
 ```bash
+npm install -g @opencode/cli@2.1.4
 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`); its options ([session trees](#session-trees),
-[webhooks](#webhooks)) go in the object form of that entry. Install it by name, without a version:
-OpenCode only checks plugins for updates when their entry is not an exact version
+This adds `"opencode-courier"` to `plugins` in `~/.config/opencode/opencode.json`. Install it by
+name, without a version: OpenCode offers updates only for an entry without an exact version
 ([updating](docs/reference.md#updating-the-plugin)).
 
-From a local clone, `bun install && npm run build`, then list its `dist` **directory** in
-`opencode.json` (V2 uses `plugins`, plural; a path to a file is ignored with a warning):
+### Supported OpenCode version
 
-```jsonc
-{
-  "plugins": ["/absolute/path/to/opencode-courier/dist"]
-}
-```
+<!-- compat-table:start rows=3: generated by script/compat-table.ts from the release tags -->
+| opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
+|---|---|
+| 0.11.1 | 2.1.4 |
+| 0.11.0 | 2.1.3 |
+| 0.10.2, 0.10.3 | 2.1.2 |
+<!-- compat-table:end -->
 
-## Using it
-
-1. Keep the background server running so sessions can be woken while you are away (`opencode
-   service start`), and run one OpenCode server per data directory where you can: a second one
-   cannot pass your answer on to a child the other runs
-   ([why](docs/reference.md#two-servers-on-one-data-directory)).
-2. Give the agents that run children the permissions their work needs: a child that hits an approval
-   prompt waits until you answer OpenCode's prompt for it in the parent's session. Let them use the
-   `question` tool if they should be able to ask you. Choose a web search provider before children
-   search the web (run one web search in your own session, or use OpenCode's "Third-party search"
-   setting), or the first child to search shows that prompt in its own session, which only you can
-   answer there.
-3. Your own session's prompts are relayed nowhere, and each one stalls the whole tree until you
-   answer it. Before an unattended run, allow the orchestrating session's toolchain up front: one rule
-   on `bun run *` or `npm run *` (the skill has checks run through the project's scripts), `git`, and
-   whatever else its checks need.
-4. Use `isolate: true` whenever children edit files in parallel. The worktree is made from the last
-   commit (from an isolated session, its HEAD), so an uncommitted `opencode.json` is not there: keep
-   providers and models in the global config, or commit the file. A worktree is kept until you
-   `courier_cleanup` it, which refuses to drop uncommitted changes or unbranched commits unless told to.
-5. For a long-running child, schedule a `courier_later` check-in for yourself and `courier_cancel` it
-   when the child reports: it covers what the plugin cannot see, such as a server that stops while a
-   child runs.
+Every release: [the full table](docs/reference.md#the-opencode-version). The server part loads on
+any V2 host from 2.0.4 on. The terminal part is tested on OpenCode 2.1.4 only.
 
-## Tools
+## Options
 
-| Tool | Does |
-|---|---|
-| `courier_spawn` | Starts a session on the parent's model with the task and a brief, and returns at once; `isolate: true` gives it its own git worktree, `group` holds its report with its siblings'. |
-| `courier_send` | Messages a session, waking it if idle; from a child to its parent, a `status` and `artifacts` make it the child's [report](docs/reference.md#a-childs-report). |
-| `courier_status` | One look at a session: outcome, idle time, when it was archived, last reply and what it waits on. For check-ins, not for waiting. |
-| `courier_children` | Lists the sessions this one (or a given one) started, with their state, worktree and join group. |
-| `courier_tree` | Lists the whole tree under a session, depth first, with each one's depth and report state. |
-| `courier_stop` | Interrupts a session below you and everything under it, and cancels their scheduled messages; `cleanup: true` removes their worktrees too. |
-| `courier_cleanup` | Removes an isolated child's worktree, unless it holds unsaved work, and forgets the child. |
-| `courier_answer` | Answers a permission request that a session under this one waits on, after OpenCode has asked you in this session, or passes your answer to its question. |
-| `courier_later` | Schedules a message for a session (this one by default) in `delayMinutes` or `at` a time. |
-| `courier_cancel` | Drops a message scheduled with `courier_later`. |
-| `courier_subscribe` | Subscribes a session to webhook deliveries for a topic (`owner/repo`, `owner/repo#12` or a name). |
-| `courier_unsubscribe` | Drops one topic, or all of a session's. |
-| `courier_recall` | One look at what earlier session trees in this project did and the lesson each left; with `sessionID`, one tree's [record](#memory) in full. |
-| `courier_note` | Writes this tree's one lesson on its [record](#memory), for the next orchestrator in the project: one line of at most 300 characters, naming the job and the reason. A longer one is refused, a second call replaces the first. From the top or a sub-orchestrator, never a leaf. |
-
-Each tool's parameters: [the reference](docs/reference.md#the-tools).
-
-## How children reach you
-
-- **A child reports once, with a status**: `done`, `partial`, `blocked` (it needs a decision from
-  its parent, and says what) or `failed`, with its artifacts in the message. A message without a
-  status is progress, not the report. [More](docs/reference.md#a-childs-report).
-- **A join group wakes you once.** Start a batch of sessions with the same `group` name, and their
-  `done`, `partial` and `failed` reports are held until the last one is in, then delivered in one
-  message; a `blocked` report, a failure, a question or a permission request still reaches you at
-  once. A member that will not report holds the others back: drop it with `courier_cleanup`.
-  [More](docs/reference.md#join-groups).
-- **A child that fails, or ends its turn without reporting, is reported** to its parent, with the
-  error or its last reply, unless it waits on a request, its own children, a scheduled message or a
-  webhook. [More](docs/reference.md#a-child-that-fails).
-- **A message that fails to wake its session is sent again** after 30 seconds; if the session still
-  does not take it, the footer and the tree panel show it as `stalled`, for you to prompt it.
-  [More](docs/reference.md#a-missed-wake).
-- **Permission requests and questions reach you** through the session at the top of the tree, any
-  number of levels down. For a request, that session proposes an answer with `courier_answer`, and
-  OpenCode asks you in its own permission prompt there before anything is passed on: its model
-  cannot approve, only propose. For a question, it asks you and passes your answer back, or links
-  its own question to the child's so your pick goes straight to it.
-  [More](docs/reference.md#a-child-that-asks-for-permission).
-- **Some forms only you can answer**, such as OpenCode's web search asking for a provider: the top
-  session is told, and you answer in the child's session. [More](docs/reference.md#a-child-that-shows-a-form).
-- **You can see and stop a whole subtree** with `courier_tree` and `courier_stop`, or in the
-  [terminal](#in-the-terminal). [More](docs/reference.md#seeing-and-stopping-a-subtree).
-
-Children, held reports, scheduled messages and open questions survive a compaction or a restart;
-entries are dropped after 14 days, or at once when OpenCode deletes the child, unless it is isolated
-([roster](docs/reference.md#roster)).
-
-## Session trees
-
-A spawned session may start sessions of its own, so the sessions form a tree, bounded by three
-options in the plugin's `options`, in the global config:
+Set the server options on the plugin's entry in the **global** config,
+`~/.config/opencode/opencode.json`:
 
 ```jsonc
 {
@@ -243,136 +97,58 @@ options in the plugin's `options`, in the global config:
 
 | Option | Default | |
 |---|---|---|
-| `maxDepth` | `3` | How deep the tree goes: your session is depth 0, the sessions it starts depth 1. A session at `maxDepth` cannot start sessions. |
-| `maxChildren` | `5` | How many sessions one session started may have live at once. |
-| `maxTotal` | `20` | How many spawned sessions may be live at once in one tree. |
-
-`courier_spawn` refuses a spawn past a limit, naming it and saying what to do instead. A session
-counts while it is live: its turn runs, it owes its parent a report, a message the plugin sent to
-wake it waits undelivered in its inbox (from the moment `courier_send` returns, so a `courier_spawn` in the same step counts it),
-or a session below it is live; renaming, archiving or
-otherwise changing it in OpenCode does not make it run.
-Each spawned session's brief says when to split its task and when to do it itself
-([more](docs/reference.md#session-trees-and-their-limits)).
-
-## Memory
-
-The plugin keeps **one record per session tree** in the project, from facts it already has: when the
-tree started and last moved, the top session's title and first `split:` line, with up to 3 later ones
-that read otherwise (when each was stated, and after how many parts), and for each session started
-in the tree its title, depth, isolation, join group, status, duration, cost, context use and spawns
-refused; never a report's body or artifacts. A session deleted since keeps its last status and
-duration, or reads `gone` when it had not settled, so it never holds its tree at `not finished`.
-The one thing a model writes into it is **the tree's
-lesson**, with `courier_note`: one line of at most 300 characters, from the session that verified the
-tree, with the job it comes from and the reason. `courier_recall` reads the records back, each line
-showing the split line as prose (its markdown marks dropped, the asterisks of its globs kept) cut at a
-word, then the latest later one (`then, after 1 part: split: 2 parts: …`), and saying how long the tree ran and how long ago it last moved; the `courier-orchestrate` skill asks for
-one call before the split decision and one `courier_note` before the top replies. Each record counts
-how often other trees' `courier_recall` calls listed it and opened it in full, and when last, so the
-person can tell a lesson still read from one nobody reads; a record the person pins in the terminal
-is listed first and never swept. Each project keeps 30 unpinned records, those with a lesson first,
-and none older than 90 days. `"memory":
-false` in the plugin's `options` turns it off ([more](docs/reference.md#memory)).
-
-## In the terminal
-
-The package ships a part for OpenCode's terminal UI, loaded from the server's plugin list; the server
-half behaves the same with or without it. In a session that started sessions, the prompt's footer
-shows what the tree under it is doing: how many wait on you (a permission request, a question or a
-form), are [stalled](docs/reference.md#a-missed-wake), run or are idle, and each
-[join group](docs/reference.md#join-groups)'s members reported:
-
-```
-courier 1 waiting on you · 2 running · group pair 1/2
-```
+| `maxDepth` | `3` | How deep a tree goes. Your session is depth 0. A session at `maxDepth` cannot start sessions. |
+| `maxChildren` | `5` | Live children one session may have. |
+| `maxTotal` | `20` | Live spawned sessions in one tree. |
+| `memory` | `true` | Keep a record of each session tree for later orchestrators ([memory](docs/reference.md#memory)). |
+| `nativeChildren` | `false` | Create non-isolated children as OpenCode subagents ([native children](docs/reference.md#native-child-sessions)). |
+| `webhook` | off | Start the webhook receiver ([webhooks](docs/reference.md#webhooks)). |
 
-`/courier tree` opens a panel beside the session with the tree under it, a row per session with a
-mark for its state (`✓` reported, a spinner while it runs, `●` waiting on you, `!` stalled, `✗`
-failed or interrupted), what it does, its report, its group's standing and, for a leaf, how long it
-ran, its last tool call, its context use and its cost. `enter` or a click opens the session, `s`
-stops it and everything under it, `x` forgets a `gone` session, `q` closes the panel;
-`/courier stop <session>` stops from the prompt. Digby, the courier's mole, digs beside the header,
-his state following the tree's. `"animations": false` in the TUI part's options keeps the panel
-still; the TUI reads a plugin's options only from its own config, `~/.config/opencode/cli.json`
-([more](docs/reference.md#in-the-terminal)):
+The terminal part reads its options only from `~/.config/opencode/cli.json`, in the same entry
+form. Its one option, `"animations": false`, keeps the tree panel still.
 
-```jsonc
-{
-  "plugins": [{ "package": "opencode-courier", "options": { "animations": false } }]
-}
-```
+## Tools
 
-`ctrl+x k` (the leader key, then `k`), `/asks` (or `/ask`), the palette's "Courier: what waits on
-you" or a click on "waiting on you" opens the asks inbox: every permission request, question and form
-waiting anywhere in the tree, after the top session's own permission requests, with where each comes
-from, kept current while open and answered in a dialog with no model in between.
-The TUI plays OpenCode's sounds for a child's report, a group's release and a new ask. While a
-permission prompt or form is shown in the session, OpenCode hides the footer, so open the inbox with
-`ctrl+x k`.
-
-`/courier memory` (or the palette's "Courier: memory") lists the project's [tree records](#memory),
-pinned first, then newest first grouped by the day each tree last moved, one row each with how often
-other trees read it and its lesson under it. `enter` shows one in full; `p` pins or unpins the record,
-and a pinned one is listed first and never swept; `x` forgets the record under the row, or in a
-record on its lesson's rows only the lesson, after a confirm; `esc` goes back and closes. The search
-takes every letter but `x` and `p` ([more](docs/reference.md#the-memory-view)).
-
-## Native child sessions
-
-Off by default. With `"nativeChildren": true` in the plugin's `options`, a child started without
-`isolate` is also created with OpenCode's own `parentID`, so OpenCode treats it as the parent's
-subagent: the TUI's view of the top session, and the paired app's request dock, list and answer the
-permission requests, questions and forms of every session under it, and the top session's model is
-only told. Deleting a session then deletes its native children, the child gets an empty ruleset
-rather than its parent's, and providers see a subagent (not tested on GitHub Copilot). Turn it on
-only with OpenCode's TUI or the paired app, which show those prompts
-([more](docs/reference.md#native-child-sessions)).
-
-## Webhooks
-
-GitHub reviews, comments, pull requests and completed CI runs, or anything signed posted to
-`/hook/<name>`, can wake a session. The receiver is off unless the plugin has a `webhook` option, in
-the **global** config, since there is one receiver per OpenCode server (`"webhook": true` takes
-every default):
+| Tool | Does |
+|---|---|
+| `courier_spawn` | Starts a child session with a task and returns at once. `isolate`, `group`, `agent`, `title`. |
+| `courier_send` | Messages a session, waking it if idle. With a `status`, it is a child's report. |
+| `courier_status` / `courier_children` / `courier_tree` | One look at a session, at the sessions it started, or at its whole tree. |
+| `courier_stop` | Stops a session below you and everything under it. |
+| `courier_cleanup` | Removes an isolated child's worktree and forgets the child. |
+| `courier_answer` | Proposes an answer to a child's permission request, or passes on your answer to its question. |
+| `courier_later` / `courier_cancel` | Schedules a message for a session, or drops one. |
+| `courier_subscribe` / `courier_unsubscribe` | Subscribes a session to webhook deliveries for a topic, or drops it. |
+| `courier_recall` / `courier_note` | Reads what earlier trees in this project did, or writes this tree's one-line lesson. |
+
+Parameters and behaviour: [the reference](docs/reference.md#the-tools).
 
-```jsonc
-{
-  "plugins": [
-    {
-      "package": "opencode-courier",
-      "options": { "webhook": { "port": 4097, "secretFile": "~/.config/opencode/courier-webhook-secret" } }
-    }
-  ]
-}
-```
+## In the terminal
 
-1. Make the secret with `openssl rand -hex 32 > ~/.config/opencode/courier-webhook-secret` and
-   `chmod 600` it. It is never read from `opencode.json` (a `secret` key is refused), so the config
-   can be committed; without a usable secret the receiver does not start, and the server log says why.
-2. On GitHub, add a webhook to the repository (Settings → Webhooks) with content type
-   `application/json`, the same secret, the events you want, and `<public URL>/github` as the payload
-   URL, forwarded to `127.0.0.1:4097` by a tunnel you trust (`smee`, `cloudflared`, `ngrok`). Only
-   signed deliveries are acted on.
-3. `courier_subscribe` a session to `owner/repo`, `owner/repo#N` or `<name>`: each matching delivery
-   arrives as a short summary marked as outside text, queued behind any running turn and waking the
-   session if idle.
+- **Footer:** `courier 1 waiting on you · 2 running · group pair 1/2`.
+- **`/courier tree`:** a panel with the tree. `enter` opens a session, `s` stops it, `q` closes.
+- **`/courier stop <session>`:** stops a session and everything under it.
+- **`ctrl+x k`** or **`/asks`:** every ask waiting on you in the tree, answered in a dialog.
+- **`/courier memory`:** the project's tree records. `p` pins one, `x` forgets one.
 
-The options, which events wake whom, the signing scheme and status codes: [the
-reference](docs/reference.md#webhooks).
+More: [in the terminal](docs/reference.md#in-the-terminal).
 
-## Development
+## Tips
 
-Commands, the suites and CI: [docs/maintainers/development.md](docs/maintainers/development.md). How
-the code is laid out: [architecture.md](docs/maintainers/architecture.md); what the plugin API does
-that courier works around: [plugin-api-notes.md](docs/maintainers/plugin-api-notes.md); releases:
-[releasing.md](docs/maintainers/releasing.md).
+- Keep `opencode service start` running, so sessions can be woken while you are away. Run one
+  OpenCode server per data directory ([why](docs/reference.md#two-servers-on-one-data-directory)).
+- Allow up front what the work needs, and the `question` tool if children should ask you. A
+  child's approval prompt waits for you, and the top session's own prompts stall the whole tree
+  (allow `bun run *` or `npm run *` and `git`).
+- Choose a web search provider before children search, or the first one shows you a form.
+- Use `isolate: true` when children edit files in parallel. The worktree starts from the last
+  commit, so keep providers in the global config or commit `opencode.json`.
+- For a long-running child, schedule a `courier_later` check-in, in case the server stops.
 
 ## 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.
+Questions and bugs: [issues](https://github.com/ivopogace/opencode-courier/issues). Pull requests
+are welcome; start with [development.md](docs/maintainers/development.md).
 
 ## License
 

package/dist/tree/domain.d.ts

@@ -145,4 +145,8 @@ export type Standing = "held" | "out" | LeftMember["by"] | "released";
 export declare function standingOf(member: Member | undefined): Standing;
 /** Whether every member of a group has a held report or has left: released once the parent's turn has ended. */
 export declare const complete: (members: ReadonlyArray<Member>) => boolean;
+/** How long the provider asked to wait after a failed turn, if it did: a positive number of milliseconds, at most `RETRY_MAX_MS`. */
+export declare function retryDelay(error: {
+    readonly retryAfterMs?: unknown;
+}): number | undefined;
 export {};

package/dist/tree/domain.js

@@ -111,3 +111,10 @@ export function standingOf(member) {
 }
 /** Whether every member of a group has a held report or has left: released once the parent's turn has ended. */
 export const complete = (members) => members.every((member) => member.report || member.left);
+/** Longer than this is no wait a notice can plan around; OpenCode clamps a header to 2^53 ms, past what a `Date` holds. */
+const RETRY_MAX_MS = 30 * 24 * 3_600_000;
+/** How long the provider asked to wait after a failed turn, if it did: a positive number of milliseconds, at most `RETRY_MAX_MS`. */
+export function retryDelay(error) {
+    const wait = error.retryAfterMs;
+    return typeof wait === "number" && Number.isFinite(wait) && wait > 0 && wait <= RETRY_MAX_MS ? wait : undefined;
+}

package/dist/tree/events.js

@@ -1,6 +1,6 @@
 import { envelope } from "../kernel/protocol.js";
 import { claim, SEEN_MAX, setBounded } from "../platform/bounded.js";
-import { endsIdle } from "./domain.js";
+import { endsIdle, retryDelay } from "./domain.js";
 import { forgetChild, forgetDeleted } from "./forget.js";
 import { hasCompleteGroup, leave, outIn } from "./group.js";
 import { awaited, reportOf, stoppedSincePrompt } from "./report.js";
@@ -19,9 +19,10 @@ export async function reportFailure(ports, seen, event) {
     const children = childStore(ports.storage);
     const entries = await children.entriesOf(sessionID);
     const at = event.created ?? ports.now();
-    // Not in the way of the notice: kept only so the limits stop counting the child.
+    const wait = retryDelay(error);
+    // Not in the way of the notice: kept only so the limits stop counting the child, and the panel can say when its limit lifts.
     if (entries.length)
-        await children.settled(sessionID, "failed", at).catch((error) => ports.log(`courier watch: could not note the failed turn of ${sessionID}: ${String(error)}`));
+        await children.settled(sessionID, "failed", at, undefined, wait === undefined ? undefined : at + wait).catch((error) => ports.log(`courier watch: could not note the failed turn of ${sessionID}: ${String(error)}`));
     const out = await Promise.all(entries.map((entry) => outIn(ports, entry)));
     // Left before the notice, so the parent waits on the group meanwhile; nudged after it, so the group's
     // message does not overtake the notice, short of an interval tick falling in between.
@@ -33,7 +34,7 @@ export async function reportFailure(ports, seen, event) {
             return [];
         await Promise.all(entries.map((entry, index) => ports.session.synthetic({
             sessionID: entry.parentID,
-            text: envelope(sessionID, failureNotice(entry.title, error, out[index]?.group), { failed: error.type }),
+            text: envelope(sessionID, failureNotice(entry.title, error, out[index]?.group, at), { failed: error.type }),
             description: `Session ${sessionID} failed`,
             metadata: { source: "courier", from: sessionID, failed: true },
             delivery: "steer",

package/dist/tree/panel.js

@@ -65,14 +65,18 @@ async function row(ports, windows, { entry, depth, info, running, endedAt, pendi
     ]);
     const tool = lastTool(messages);
     const context = contextOf(messages, windows);
+    const state = stateOf(info, pending.length + forms.length, stalled !== undefined, running);
+    // A prompt since the failure drops it from the report, so `resumesAt` here is that of the last turn alone.
+    const resumes = state === "idle" && !stopped && report?.resumesAt !== undefined && report.resumesAt > ports.now() ? report.resumesAt : undefined;
     return {
         sessionID,
         parentID: entry.parentID,
         title: info?.title ?? entry.title,
         depth,
-        state: stateOf(info, pending.length + forms.length, stalled !== undefined, running),
+        state,
         ...(stalled !== undefined ? { stalled } : {}),
         ...(info?.outcome ? { outcome: info.outcome } : {}),
+        ...(resumes !== undefined ? { resumes } : {}),
         ...(stopped ? { stopped } : {}),
         ...reportRow(report, status),
         ...(entry.group && standing ? { group: { name: entry.group, standing } } : {}),

package/dist/tree/ports.d.ts

@@ -13,11 +13,12 @@ export type RosterStorage = Storage;
 export type Settled = "report" | "failed" | "interrupted";
 /** The notes kept of a spawned session's report state; docs/maintainers/architecture.md has each. */
 export type ReportField = "prompt" | "settled" | "progress" | "told" | "stopped";
-/** A report note as read: when it was made, and for `settled` how the wait ended and the report's status, as stored. */
+/** A report note as read: when it was made, and for `settled` how the wait ended, the report's status or a failure's `resumesAt`, as stored. */
 export interface ReportNote {
     readonly at: number | undefined;
     readonly by: unknown;
     readonly status: unknown;
+    readonly resumesAt: unknown;
 }
 /** A stored value, as `Storage` gives and takes it. */
 export type Stored = Parameters<Storage["set"]>[1];
@@ -59,8 +60,11 @@ export interface ChildStore {
     }>;
     /** Notes that a prompt or message reached a spawned session at `at`, unless a later one is noted. */
     prompted(sessionID: string, at: number): Promise<void>;
-    /** Notes how a spawned session's wait for a report ended at `at`, with its report's status, unless a later end is noted. */
-    settled(sessionID: string, by: Settled, at: number, status?: Status): Promise<void>;
+    /**
+     * Notes how a spawned session's wait for a report ended at `at`, with its report's status or, for a failed turn, when the
+     * provider's limit lifts (`resumesAt`), unless a later end is noted.
+     */
+    settled(sessionID: string, by: Settled, at: number, status?: Status, resumesAt?: number): Promise<void>;
     /** Notes that a spawned session messaged its parent without a status at `at`, unless a later one is noted. */
     progressed(sessionID: string, at: number): Promise<void>;
     /** Notes that a spawned session's parent was told at `at` that a turn ended without a report, unless a later telling is noted. */
@@ -283,6 +287,8 @@ export interface ExecutionError {
     readonly type: string;
     readonly message: string;
     readonly status?: number;
+    /** How long the provider asked to wait before trying again, counted from the event's `created`; set by rate and quota limits and some provider errors. */
+    readonly retryAfterMs?: number;
 }
 export interface WatchPorts {
     readonly storage: RosterStorage;

package/dist/tree/report.d.ts

@@ -7,9 +7,10 @@ export declare function stoppedSincePrompt(children: Notes, sessionID: string):
 export declare function lastStatus(children: Notes, sessionID: string): Promise<Status | undefined>;
 /**
  * What is known of a spawned session's report: when a prompt last reached it, and whether since then it owes one, has
- * messaged its parent without a status, or failed or was interrupted. Undefined for one spawned before this was kept.
+ * messaged its parent without a status, or failed (`resumesAt`: until when) or was interrupted. Undefined before this was kept.
  */
 export declare function reportOf(children: Notes, sessionID: string): Promise<{
+    resumesAt?: number | undefined;
     prompt: number;
     owes: boolean;
     progressed: boolean;

package/dist/tree/report.js

@@ -13,7 +13,7 @@ export async function lastStatus(children, sessionID) {
 }
 /**
  * What is known of a spawned session's report: when a prompt last reached it, and whether since then it owes one, has
- * messaged its parent without a status, or failed or was interrupted. Undefined for one spawned before this was kept.
+ * messaged its parent without a status, or failed (`resumesAt`: until when) or was interrupted. Undefined before this was kept.
  */
 export async function reportOf(children, sessionID) {
     const { prompt, settled, progress } = await children.notes(sessionID, ["prompt", "settled", "progress"]);
@@ -21,7 +21,14 @@ export async function reportOf(children, sessionID) {
     if (promptAt === undefined)
         return undefined;
     const done = since(settled.at, promptAt);
-    return { prompt: promptAt, owes: !done, progressed: since(progress.at, promptAt), ended: done && settled.by !== "report" };
+    const resumesAt = done && settled.by === "failed" && typeof settled.resumesAt === "number" ? settled.resumesAt : undefined;
+    return {
+        prompt: promptAt,
+        owes: !done,
+        progressed: since(progress.at, promptAt),
+        ended: done && settled.by !== "report",
+        ...(resumesAt === undefined ? {} : { resumesAt }),
+    };
 }
 /**
  * Whether its parent still waits on a spawned session's report: it owes one, and the parent has not

package/dist/tree/rpc-handlers.d.ts

@@ -91,6 +91,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                         readonly name: string;
                         readonly at: number;
                     } | undefined;
+                    readonly resumes?: number | undefined;
                 }[];
                 readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
@@ -133,6 +134,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                         readonly name: string;
                         readonly at: number;
                     } | undefined;
+                    readonly resumes?: number | undefined;
                 }[];
                 readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
@@ -145,6 +147,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     readonly state: import("effect/Schema").Literals<readonly ["running", "waiting", "idle", "stalled", "gone"]>;
                     readonly stalled: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
                     readonly outcome: import("effect/Schema").optionalKey<import("effect/Schema").Literals<readonly ["succeeded", "failed", "interrupted"]>>;
+                    readonly resumes: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
                     readonly stopped: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
                     readonly report: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
                         readonly state: import("effect/Schema").Literals<readonly ["owed", "reported", "ended"]>;

package/dist/tree/rpc.d.ts

@@ -44,6 +44,8 @@ declare const Row: Schema.Struct<{
     readonly stalled: Schema.optionalKey<Schema.Number>;
     /** How its last turn ended. */
     readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["succeeded", "failed", "interrupted"]>>;
+    /** When the provider limit that failed its last turn lifts; left out once that has passed, or when it runs again or was stopped. */
+    readonly resumes: Schema.optionalKey<Schema.Number>;
     /** Set when courier_stop stopped it since its last prompt. */
     readonly stopped: Schema.optionalKey<Schema.Boolean>;
     /** Its report since its last prompt: still owed, arrived (held with its group or delivered), or its turn ended without one. */
@@ -99,6 +101,8 @@ declare const Tree: Schema.Struct<{
         readonly stalled: Schema.optionalKey<Schema.Number>;
         /** How its last turn ended. */
         readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["succeeded", "failed", "interrupted"]>>;
+        /** When the provider limit that failed its last turn lifts; left out once that has passed, or when it runs again or was stopped. */
+        readonly resumes: Schema.optionalKey<Schema.Number>;
         /** Set when courier_stop stopped it since its last prompt. */
         readonly stopped: Schema.optionalKey<Schema.Boolean>;
         /** Its report since its last prompt: still owed, arrived (held with its group or delivered), or its turn ended without one. */
@@ -258,6 +262,7 @@ export declare const treeRpc: {
                         readonly name: string;
                         readonly at: number;
                     } | undefined;
+                    readonly resumes?: number | undefined;
                 }[];
                 readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
@@ -300,6 +305,7 @@ export declare const treeRpc: {
                         readonly name: string;
                         readonly at: number;
                     } | undefined;
+                    readonly resumes?: number | undefined;
                 }[];
                 readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
@@ -319,6 +325,8 @@ export declare const treeRpc: {
                     readonly stalled: Schema.optionalKey<Schema.Number>;
                     /** How its last turn ended. */
                     readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["succeeded", "failed", "interrupted"]>>;
+                    /** When the provider limit that failed its last turn lifts; left out once that has passed, or when it runs again or was stopped. */
+                    readonly resumes: Schema.optionalKey<Schema.Number>;
                     /** Set when courier_stop stopped it since its last prompt. */
                     readonly stopped: Schema.optionalKey<Schema.Boolean>;
                     /** Its report since its last prompt: still owed, arrived (held with its group or delivered), or its turn ended without one. */

package/dist/tree/rpc.js

@@ -41,6 +41,8 @@ const Row = Schema.Struct({
     stalled: Schema.optionalKey(Schema.Number),
     /** How its last turn ended. */
     outcome: Schema.optionalKey(Schema.Literals(["succeeded", "failed", "interrupted"])),
+    /** When the provider limit that failed its last turn lifts; left out once that has passed, or when it runs again or was stopped. */
+    resumes: Schema.optionalKey(Schema.Number),
     /** Set when courier_stop stopped it since its last prompt. */
     stopped: Schema.optionalKey(Schema.Boolean),
     /** Its report since its last prompt: still owed, arrived (held with its group or delivered), or its turn ended without one. */

package/dist/tree/spawn.js

@@ -9,15 +9,15 @@ function titleOf(task) {
     return line.length > 60 ? `${line.slice(0, 57)}...` : line;
 }
 /**
- * The model a child runs on: its parent's, so it does not fall back to OpenCode's default, which
- * the parent may have been moved off for a reason. An agent that names its own model keeps it.
+ * The model a child runs on, always passed on so no OpenCode version falls back to its default:
+ * the named agent's own, else its parent's.
  */
 async function inheritedModel(ports, parentID, agent) {
     const parent = await ports.session.get({ sessionID: parentID });
-    if (!parent.model || !agent)
+    if (!agent)
         return parent.model;
     const named = await ports.agent.get({ agentID: agent, location: { directory: ports.directory } });
-    return named.data.model ? undefined : parent.model;
+    return named.data.model ?? parent.model;
 }
 /** Removes a worktree made for a child that was never created; one that cannot be removed stays. */
 async function dropWorktree(ports, directory) {

package/dist/tree/store.js

@@ -18,7 +18,7 @@ export function reverseKey(sessionID) {
 }
 /**
  * Whether a spawned session has reported since its last prompt, under `report/<sessionID>/`: `prompt`, `settled` (with
- * the report's status), `progress` (a message to its parent without a status) and `told`; docs/maintainers/architecture.md has each.
+ * the report's status, or when a failed turn's wait lifts), `progress` (a message to its parent without a status) and `told`; docs/maintainers/architecture.md has each.
  */
 const REPORT_PREFIX = "report/";
 export const promptKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/prompt`;
@@ -60,7 +60,7 @@ const timeOf = (value) => {
     const at = obj(value).at;
     return typeof at === "number" && Number.isFinite(at) ? at : undefined;
 };
-const noteOf = (value) => ({ at: timeOf(value), by: obj(value).by, status: obj(value).status });
+const noteOf = (value) => ({ at: timeOf(value), by: obj(value).by, status: obj(value).status, resumesAt: obj(value).resumesAt });
 /** The `ChildStore` over the plugin's storage. */
 export function childStore(storage) {
     const entry = async (parentID, sessionID) => (await storage.get(rosterKey(parentID, sessionID)));
@@ -173,9 +173,9 @@ export function childStore(storage) {
             if ((timeOf(await storage.get(promptKey(sessionID))) ?? -Infinity) < at)
                 await storage.set(promptKey(sessionID), { at });
         },
-        async settled(sessionID, by, at, status) {
+        async settled(sessionID, by, at, status, resumesAt) {
             if ((timeOf(await storage.get(settledKey(sessionID))) ?? -Infinity) <= at)
-                await storage.set(settledKey(sessionID), { at, by, ...(status ? { status } : {}) });
+                await storage.set(settledKey(sessionID), { at, by, ...(status ? { status } : {}), ...(resumesAt === undefined ? {} : { resumesAt }) });
         },
         async progressed(sessionID, at) {
             if ((timeOf(await storage.get(progressKey(sessionID))) ?? -Infinity) <= at)

package/dist/tree/text.d.ts

@@ -61,7 +61,11 @@ export declare function keepReason(state: {
     readonly changes: readonly string[];
     readonly commits: readonly string[];
 }): string | undefined;
-export declare function failureNotice(title: string, error: ExecutionError, group?: string): string;
+/**
+ * What the parent is told when a session it started failed its turn; `at` is when the failure happened, which the provider's
+ * retry time (`retryAfterMs`) counts from. Message the child before that and it fails again, so the notice says to wait.
+ */
+export declare function failureNotice(title: string, error: ExecutionError, group?: string, at?: number): string;
 /**
  * What the parent is told when a session it started ends its turn without a report to it;
  * `progressed` when it messaged the parent without a status since its last prompt.

package/dist/tree/text.js

@@ -1,6 +1,7 @@
 /** The tree's model-facing texts: the child brief, the role part, refusals, reports, notices and tool results. */
 import { obj, str } from "../platform/json.js";
 import { clipText, defuse, END_TURN, ROOT_SPLIT_LINE, SKILL_ID, SPLIT_LINE, STATUSES } from "../kernel/protocol.js";
+import { retryDelay } from "./domain.js";
 // The envelope and the child brief.
 /** How a text names the statuses a report may carry. */
 const STATUS_LIST = `${STATUSES.slice(0, -1).join(", ")} or ${STATUSES.at(-1)}`;
@@ -217,12 +218,39 @@ function preview(items) {
     return items.length > 5 ? `${items.slice(0, 5).join(", ")}, ...` : items.join(", ");
 }
 // Turn failures.
-export function failureNotice(title, error, group) {
+/** A wait in whole minutes, rounded up: "1 minute", "45 minutes", "2 hours 5 minutes". */
+function wait(ms) {
+    const minutes = Math.ceil(ms / 60_000);
+    if (minutes < 60)
+        return count(minutes, "minute");
+    const rest = minutes % 60;
+    return [count(Math.floor(minutes / 60), "hour"), rest ? count(rest, "minute") : ""].filter(Boolean).join(" ");
+}
+/** A time as the notices say it, in UTC, with its date when it is not the day of `from`. */
+function clock(at, from) {
+    const iso = new Date(at).toISOString();
+    return iso.slice(0, 10) === new Date(from).toISOString().slice(0, 10) ? `${iso.slice(11, 16)} UTC` : `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+}
+/** The line saying how long the provider asked to wait, and until when if the failure's time `at` is known. */
+function waitLine(delay, at) {
+    const until = at === undefined ? "" : `, until about ${clock(at + delay, at)}`;
+    return `The provider asked to wait about ${wait(delay)} before trying again${until}.`;
+}
+/**
+ * What the parent is told when a session it started failed its turn; `at` is when the failure happened, which the provider's
+ * retry time (`retryAfterMs`) counts from. Message the child before that and it fails again, so the notice says to wait.
+ */
+export function failureNotice(title, error, group, at) {
     const status = error.status === undefined ? "" : `, status ${error.status}`;
+    const delay = retryDelay(error);
     return [
         `This session, "${title}", which you started with courier_spawn, failed: ${error.message} (${error.type}${status}).`,
+        ...(delay === undefined ? [] : [waitLine(delay, at)]),
         "Its turn ended without finishing, so it will not report back on its own.",
-        "Message it with courier_send to have it try again, start a replacement, or carry on without it.",
+        delay === undefined
+            ? "Message it with courier_send to have it try again, start a replacement, or carry on without it."
+            : "Do not message it with courier_send before then, as the turn would fail again. Message it after, start a replacement, or carry on without it; " +
+                "courier_later can remind you when the wait is over.",
         ...(group
             ? [
                 `It is a member of group "${group}", which no longer waits for it: its other members' reports reach you once they have ` +

package/dist/tree/tui.d.ts

@@ -98,9 +98,9 @@ export declare function bar(counts: {
 /** What a paused session waits on, such as "asks permission: shell echo hi" or "shows a form: Web Search". */
 export declare function waitLine(wait: Wait): string;
 /** What a row's session is doing, its report and its group standing: "idle · reported done · group pair held". */
-export declare function statusLine(row: Row): string;
+export declare function statusLine(row: Row, now?: number): string;
 /** The parts of `statusLine`, each with the row part the panel colours it as. */
-export declare function statusParts(row: Row): {
+export declare function statusParts(row: Row, now?: number): {
     text: string;
     kind: "state" | "report" | "plain";
 }[];

package/dist/tui.js

@@ -1452,6 +1452,7 @@ var Row = Schema3.Struct({
   state: Schema3.Literals(["running", "waiting", "idle", "stalled", "gone"]),
   stalled: Schema3.optionalKey(Schema3.Number),
   outcome: Schema3.optionalKey(Schema3.Literals(["succeeded", "failed", "interrupted"])),
+  resumes: Schema3.optionalKey(Schema3.Number),
   stopped: Schema3.optionalKey(Schema3.Boolean),
   report: Schema3.optionalKey(Schema3.Struct({ state: Schema3.Literals(["owed", "reported", "ended"]), status: Schema3.optionalKey(Schema3.String), progressed: Schema3.Boolean })),
   group: Schema3.optionalKey(Schema3.Struct({ name: Schema3.String, standing: Schema3.String })),
@@ -1723,12 +1724,12 @@ function waitLine(wait) {
     return `asks permission: ${[wait.action, ...wait.resources].join(" ")}`;
   return wait.type === "form" ? `shows a form: ${wait.title}` : `asks: ${wait.question}`;
 }
-function statusLine(row) {
-  return statusParts(row).map((part) => part.text).join(" \xB7 ");
+function statusLine(row, now = Date.now()) {
+  return statusParts(row, now).map((part) => part.text).join(" \xB7 ");
 }
-function statusParts(row) {
+function statusParts(row, now = Date.now()) {
   const parts = [{
-    text: stateWord(row),
+    text: stateWord(row, now),
     kind: "state"
   }, {
     text: reportWords(row.report, row.stopped),
@@ -1785,13 +1786,21 @@ function rowMark(row, theme, frame) {
     color: undefined
   };
 }
-function stateWord(row) {
+function resumeTime(at, now) {
+  const time = new Date(at);
+  const pad = (value) => String(value).padStart(2, "0");
+  const clock = `${pad(time.getHours())}:${pad(time.getMinutes())}`;
+  return time.toDateString() === new Date(now).toDateString() ? clock : `${pad(time.getMonth() + 1)}-${pad(time.getDate())} ${clock}`;
+}
+function stateWord(row, now) {
   if (row.state === "waiting")
     return "waiting on you";
   if (row.state === "stalled")
     return "stalled";
   if (row.state === "idle" && row.stopped)
     return "stopped";
+  if (row.state === "idle" && row.outcome === "failed" && row.resumes !== undefined && row.resumes > now)
+    return `limit, resumes ${resumeTime(row.resumes, now)}`;
   if (row.state === "idle" && (row.outcome === "failed" || row.outcome === "interrupted"))
     return row.outcome;
   return row.state;
@@ -2485,7 +2494,7 @@ function TreePanel(props) {
           _$setProp(_el$30, "flexShrink", 0);
           _$insert(_el$25, _$createComponent(For, {
             get each() {
-              return statusParts(row);
+              return statusParts(row, now());
             },
             children: (part, at) => [_$createComponent(Show, {
               get when() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-courier",
-  "version": "0.10.3",
+  "version": "0.11.1",
   "description": "Multi-session orchestration for OpenCode V2: spawn child sessions, be woken by them. No polling.",
   "license": "MIT",
   "author": "Ivo Pogace <71701666+ivopogace@users.noreply.github.com>",
@@ -56,14 +56,14 @@
     "test:e2e": "e2e/run.sh"
   },
   "peerDependencies": {
-    "@opencode/plugin": "2.1.2",
+    "@opencode/plugin": "2.1.4",
     "effect": "4.0.1"
   },
   "devDependencies": {
-    "@opencode/plugin": "2.1.2",
-    "@opencode/theme": "2.1.2",
-    "@opentui/core": "0.6.6",
-    "@opentui/solid": "0.6.6",
+    "@opencode/plugin": "2.1.4",
+    "@opencode/theme": "2.1.4",
+    "@opentui/core": "0.6.8",
+    "@opentui/solid": "0.6.8",
     "@types/bun": "1.4.2",
     "@types/node": "26.6.4",
     "effect": "4.0.1",