opencode-courier 0.6.0 → 0.7.1

package/README.md

@@ -14,15 +14,14 @@ polling.
 [![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)
 
-![A parent spawns two slow children, writes a README itself, and is woken by each report](docs/demo-async-tui.gif)
+https://github.com/user-attachments/assets/74a50b9c-462a-43f5-8737-bc7dd1917988
 
-A parent writes a README while two slow children work, and each report wakes it ([the
-prompt](#demos)).
+The edge cases on the live terminal UI, narrated ([what it shows](#demos)).
 
 ## Quickstart
 
 ```bash
-npm install -g @opencode/cli@2.0.29   # OpenCode V2, at the version courier is tested on
+npm install -g @opencode/cli@2.0.30   # 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
 ```
@@ -44,7 +43,7 @@ sometimes stall on a request; if nothing moves for a few minutes, send the promp
 
 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.29**. CI also runs the live
+against it end to end; the current one is tested on **OpenCode 2.0.30**. CI also runs the live
 suite on the newest OpenCode release, on `main` and nightly, so a host release that breaks the
 plugin shows up there first. Older releases and their versions: [Supported OpenCode version](#supported-opencode-version).
 
@@ -80,21 +79,18 @@ 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."* The recording at the top is this run: the parent writes its README and finishes its
-turn 16 seconds in, while both children still sleep; each report (the `Message from ses_…` line)
-then starts a new turn on its own, and the parent folds it into the README.
+The video at the top (1:46, narrated) is the TUI driven in `tmux` on the scripted stand-in model of
+the live test, with `e2e/tui.sh`'s setup, so each scene is real plugin behaviour:
 
-**A child's question reaches you.** Prompt: *"Spawn a child session to add a multiply function to
-math.js. It must ask me first whether to name it multiply, times or product."*
-
-![A child's question opens as a form in the parent's session, times is picked, and the child carries on](docs/demo-question-tui.gif)
-
-The child's question opens in the parent's session as OpenCode's own question form, `times` is
-picked, and the child adds `times` to math.js and reports. Both recordings are real runs with a free
-model on [OpenCode Zen](https://opencode.ai/zen) (Muse Spark 1.3).
+- **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. You allow it from the asks inbox
+  (`ctrl+x k`), and both reports reach the parent in one message.
+- **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.
 
 ## Recursive orchestration
 
@@ -117,7 +113,8 @@ line to the server log naming both ([more](docs/reference.md#the-opencode-versio
 
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
-| 0.5.0, 0.6.0 | 2.0.29 |
+| 0.7.1 | 2.0.30 |
+| 0.5.0, 0.6.0, 0.7.0 | 2.0.29 |
 | 0.4.0, 0.4.1 | 2.0.28 |
 | 0.2.3, 0.3.0 | 2.0.26 |
 | 0.2.2 | 2.0.24 |
@@ -126,12 +123,12 @@ line to the server log naming both ([more](docs/reference.md#the-opencode-versio
 | 0.1.6 | 0.0.0-beta-19271 (the beta line: `opencode2` from `@opencode-ai/cli`, and `@opencode-ai/plugin`) |
 
 The [terminal part](#in-the-terminal) relies on the host to provide its UI modules and is tested on
-OpenCode 2.0.29 only; the server part works as before on older V2 hosts from 2.0.4 on.
+OpenCode 2.0.30 only; the server part works as before on older V2 hosts from 2.0.4 on.
 
 Check yours with `opencode --version`, and install the matching CLI with:
 
 ```bash
-npm install -g @opencode/cli@2.0.29
+npm install -g @opencode/cli@2.0.30
 ```
 
 ### The plugin
@@ -213,13 +210,20 @@ Each tool's parameters: [the reference](docs/reference.md#the-tools).
   plugin, with the error or its last reply, waking it if idle; one that waits on a request, its own
   children, a scheduled message or a webhook is not, nor is one that answers what you typed in its
   session. [More](docs/reference.md#a-child-that-fails).
+- **A message that fails to wake its session is sent again.** A report, notice or scheduled message
+  (but not a note that a request was answered elsewhere) that waits in an idle session's inbox for 30 seconds without a turn starting for it is sent once
+  more under the same inbox id, which OpenCode takes for the same message, not a second one. 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.** A child's request or question is passed to the
   session at the top of its 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, in that session
   and under its rules, 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. Whichever answer comes first counts, and the other is withdrawn.
-  [More](docs/reference.md#a-child-that-asks-for-permission).
+  A request starts a turn in the top session if it is idle; if you answer it somewhere else, the
+  note that it is settled waits for that session's next turn, usually the child's report or its
+  silence, instead of starting one of its own. [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
@@ -257,8 +261,9 @@ does not. Each spawned session's brief says when to split its task and when to d
 
 The package ships a part for OpenCode's terminal UI, which the TUI loads from the server's plugin
 list; the server half behaves the same whether or not a TUI is attached. In a session that started
-sessions, the prompt's footer shows what the tree under it is doing: how many run, wait on you (a
-permission request, a question or a form they show) or are idle, and for each [join group](docs/reference.md#join-groups) how many of its members have
+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 they show), are [stalled](docs/reference.md#a-missed-wake),
+run or are idle, and for each [join group](docs/reference.md#join-groups) how many of its members have
 reported:
 
 ```
@@ -267,7 +272,7 @@ courier 1 waiting on you · 2 running · group pair 1/2
 
 `/courier tree` opens a panel beside the session with the tree under it, a row per session indented
 by depth, with what it does, its report and its group's standing; a session waiting on you gets a line per
-request or form (`shows a form: Web Search`), a session that started others gets
+request or form (`shows a form: Web Search`), a stalled one since when its message waits, a session that started others gets
 a bar of the parts reported, a leaf how long it ran, its last tool call and its cost. A tree that has
 started more than `maxTotal` sessions over time is listed live ones first, then newest, and the header
 says how many older ones are left out; the footer counts them all. `↑`/`↓` select,

package/dist/index.js

@@ -9,7 +9,7 @@ import { builtVersions, versionNotice } from "./platform/version.js";
 import { addSchedulingTools, cancelScheduled, dueJob, isScheduled } from "./scheduling/index.js";
 import { addPersonTools, asksPermission, asksQuestion, formsShown, joinRelay, noticeCutOff, pendingOf, pendingQuestions, personEvents, portsAt, registerPersonRpc, relayQuestions, } from "./person/index.js";
 import { addSkill } from "./skill.js";
-import { addTreeTools, deliverReleased, dirtyOf, headOf, inspectWorktree, pruneExpired, readLimits, readNativeChildren, registerTreeRpc, shapeContext, together, treeEvents, waitsOn, } from "./tree/index.js";
+import { addTreeTools, deliverReleased, wakeMissed, dirtyOf, headOf, inspectWorktree, pruneExpired, readLimits, readNativeChildren, registerTreeRpc, shapeContext, together, treeEvents, waitsOn, } from "./tree/index.js";
 import { addWebhookTools, joinReceiver, readConfig, receiving, subscribedSince, } from "./webhook/index.js";
 /** The spawns under way in the process, outside the hub, so spawns in other locations, copies and hub versions count them. */
 const gate = sharedState("spawning", () => ({ reserved: new Set(), turn: Promise.resolve() }));
@@ -19,11 +19,12 @@ const inbox = sharedState("inbox", () => new Map());
 const shown = sharedState("formsShown", () => new Map());
 /**
  * What each tick of the scheduler does, in order, through the first loaded member, of whichever copy:
- * due `courier_later` messages, then released join groups. Every hub-v2 member's `later` is its LaterPorts.
+ * due `courier_later` messages, released join groups, then missed wakes. Every hub-v2 member's `later` is its LaterPorts.
  */
 const jobs = [
     dueJob,
     (owner, claimed) => deliverReleased(owner.later, claimed),
+    (owner, claimed) => wakeMissed(owner.later, claimed),
 ];
 const { join, track, nudge } = openInProcess(jobs);
 /** The permission domains of the loaded instances: every member's is its location's, whichever copy joined it. */

package/dist/person/events.d.ts

@@ -7,8 +7,8 @@ import { type PersonPorts, type PersonState } from "./ports.js";
  */
 export declare function reportAsked(ports: PersonPorts, state: PersonState, event: PermissionAsked): Promise<string[]>;
 /**
- * Tells the session told about a request that it was answered some other way, so it does not pass on
- * a stale question; requests answered through courier_answer no longer wait and are skipped.
+ * Tells the session told about a request that it was answered some other way, so it does not pass on a stale
+ * question; requests answered through courier_answer are skipped. Sent with `resume: false`, so it starts no turn.
  */
 export declare function reportReplied(ports: PersonPorts, state: PersonState, event: PermissionReplied): Promise<string[]>;
 /**

package/dist/person/events.js

@@ -36,8 +36,8 @@ export async function reportAsked(ports, state, event) {
     return [topOf(chain)];
 }
 /**
- * Tells the session told about a request that it was answered some other way, so it does not pass on
- * a stale question; requests answered through courier_answer no longer wait and are skipped.
+ * Tells the session told about a request that it was answered some other way, so it does not pass on a stale
+ * question; requests answered through courier_answer are skipped. Sent with `resume: false`, so it starts no turn.
  */
 export async function reportReplied(ports, state, event) {
     if (!claim(state.seen, event.id))
@@ -54,8 +54,9 @@ export async function reportReplied(ports, state, event) {
         sessionID: topOf(chain),
         text: envelope(sessionID, permissionSettledNotice(chain[0].title, requestID, reply), { answered: reply, request: requestID }),
         description: `Session ${sessionID} no longer asks for permission`,
-        metadata: { source: "courier", from: sessionID, answered: reply, requestID },
+        metadata: { source: "courier", from: sessionID, answered: reply, requestID, resume: false },
         delivery: "steer",
+        resume: false,
     });
     return [topOf(chain)];
 }

package/dist/skill.js

@@ -11,17 +11,22 @@ export const SKILL_CONTENT = [
         "opencode-courier role line in your system prompt, names your depth in the session tree and its limits.",
     "",
     "1. Decide: split or do. Split when the task has 2 or more independent, substantial parts touching separate files or " +
-        "areas; do it yourself when it is small, sequential or tightly coupled. Never start exactly one session. " +
-        "An implementation task with one tightly coupled core usually still has independent parts: its e2e scenario, its " +
+        "areas; do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole " +
+        "task: it only adds a hop. What you read and write yourself stays in your context for every later turn, so keep the " +
+        "deciding, checking and integrating, and hand off the long reading and writing. An implementation task with one tightly " +
+        "coupled core usually still has independent parts: finding out what the change needs (a session with isolate: false " +
+        "reads the code, or a library's or a host's source, tries things and reports what it found), its e2e scenario, its " +
         "documentation, sometimes a second test file, and a review of the core by a session with fresh context, which reads the " +
         "committed diff against the task and the repository's rules and reports its findings (isolate: false, it edits nothing). " +
-        "Weigh each of them: do the core yourself first and commit it, so that the names and texts the other parts depend on are " +
-        "fixed, then, if 2 or more remain, start one session per remaining part, in one group. A part that is itself big and " +
-        "divisible is split again by the session that gets it; at the deepest level a session does its part itself. " +
+        "Weigh each of them. When the other parts depend on names and texts the core fixes, split in stages: the core first, " +
+        "yourself when it is small or by one session when it is big, merged and committed before the rest start; then, if 2 or " +
+        "more parts remain, one session per remaining part, in one group. A part that is itself big and divisible is split again " +
+        "by the session that gets it; at the deepest level a session does its part itself. " +
         `Say which in one line of your reply, before you start: ${SPLIT_LINE}, so that a reasoned decision to do it ` +
         "yourself can be told from one never made.",
     "2. Plan the parts so that no two edit the same files. Write each task so the session can do it without you: what to " +
-        "produce and where, how to check it, what to report. Say if it may split its part further.",
+        "produce and where, how to check it, what to report. Say if it may split its part further, and to run its checks " +
+        "through the project's scripts (step 6): each permission request of a session below you wakes you and waits on the person.",
     "3. Start them: one courier_spawn per part, all with the same group name, so you are woken once with every report; " +
         "isolate: true for each part that edits files in parallel with another (commit your own work first if you are isolated " +
         "yourself). For long work, courier_later a check-in for yourself, and courier_cancel it when the reports arrive.",

package/dist/tree/events.js

@@ -6,6 +6,7 @@ import { awaited, reportOf, stoppedSincePrompt } from "./report.js";
 import { childStore, groupStore } from "./store.js";
 import { lastReply } from "./status.js";
 import { failureNotice, silentNotice } from "./text.js";
+import { forgetWakes, settleWake, wakeEnded, wakeStarted, watchWake } from "./wake.js";
 /**
  * Tells the parent of a child whose turn failed, since a child that cannot reach its model cannot
  * call courier_send. Returns the parents told.
@@ -193,13 +194,37 @@ function routeTree(ports, state, outside, event) {
         return noteDeleted(ports, event);
     return undefined;
 }
+/** The events that move a courier message waiting in a session's inbox: enqueued, taken, cancelled, and the turns around it. */
+function routeWake(ports, event) {
+    if (event.type === "session.inbox.enqueued")
+        return watchWake(ports, event);
+    if (event.type === "session.inbox.delivered" || event.type === "session.inbox.cancelled")
+        return settleWake(ports, event);
+    if (event.type === "session.execution.started")
+        return wakeStarted(ports, event);
+    if (TURN_ENDS.has(event.type))
+        return wakeEnded(ports, event);
+    if (event.type === "session.deleted")
+        return forgetWakes(ports, event.data.sessionID);
+    return undefined;
+}
+/** The tree's handling of an event alongside the wake watch's, which touches other keys and never fails the tree's. */
+async function route(ports, state, outside, event) {
+    const watched = routeWake(ports, event)?.catch((error) => ports.log(`courier watch: wake of ${event.type}: ${String(error)}`));
+    try {
+        return await routeTree(ports, state, outside, event);
+    }
+    finally {
+        await watched;
+    }
+}
 /**
  * Tells parents of a child's failed or silent turn, unless it waits on what `outside` says, and notes
  * its prompts, interruptions and deletion; `after` a turn's end, seals the groups of its session.
  */
 export function treeEvents(state, outside) {
     return {
-        handle: (ports, event) => routeTree(ports, state, outside, event),
+        handle: (ports, event) => route(ports, state, outside, event),
         // After: a silent end is judged while the group the nudge may deliver is still there to wait on.
         after: (ports, event) => (TURN_ENDS.has(event.type) ? sealGroups(ports, event) : undefined),
     };

package/dist/tree/index.d.ts

@@ -8,3 +8,4 @@ export { allEntries, answeringTop, lineage, pruneExpired, RETENTION_MS } from ".
 export { subtree } from "./subtree.js";
 export { registerTreeRpc } from "./rpc-handlers.js";
 export { addTreeTools } from "./tools.js";
+export { wakeMissed } from "./wake.js";

package/dist/tree/index.js

@@ -1,4 +1,4 @@
-// What the rest of the plugin uses of the session tree: its tools, RPC, event module, context hook and tick job
+// What the rest of the plugin uses of the session tree: its tools, RPC, event module, context hook and tick jobs
 // for `src/index.ts`, and the lineage and subtree queries and types `person/` reads.
 export { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
 export { shapeContext } from "./context.js";
@@ -9,3 +9,4 @@ export { allEntries, answeringTop, lineage, pruneExpired, RETENTION_MS } from ".
 export { subtree } from "./subtree.js";
 export { registerTreeRpc } from "./rpc-handlers.js";
 export { addTreeTools } from "./tools.js";
+export { wakeMissed } from "./wake.js";

package/dist/tree/panel.d.ts

@@ -12,7 +12,7 @@ export declare const waitOf: (pending: Pending) => Wait;
 export declare const formWait: (form: ShownForm) => Wait;
 /**
  * The tree panel's rows: the sessions under a session as courier_tree lists them, at most `maxTotal`, the live ones
- * first, then the newest, each as `row` reads it; `truncated` counts the older ones left out.
+ * first, then the newest, each as `row` reads it; `truncated` counts the older ones left out, and `stalled` says the root is.
  */
 export declare function panel(ports: CourierPorts, rootID: string): Promise<Tree>;
 export {};

package/dist/tree/panel.js

@@ -3,6 +3,7 @@ import { lastStatus, stoppedSincePrompt } from "./report.js";
 import { standingIn } from "./status.js";
 import { childStore } from "./store.js";
 import { readTree } from "./subtree.js";
+import { stalledAmong } from "./wake.js";
 /** The last tool call in a session's messages, and when it was made. */
 export function lastTool(messages) {
     for (const message of messages.toReversed()) {
@@ -30,16 +31,21 @@ function reportRow(report, status) {
         return { report: { state: "ended", progressed: report.progressed } };
     return { report: { state: "reported", progressed: report.progressed, ...(status ? { status } : {}) } };
 }
-/** What a session does: waiting on a request to the person or a form it shows them, running, idle, or gone when OpenCode no longer knows it. */
-function stateOf(info, waits, running) {
+/**
+ * What a session does: waiting on a request to the person or a form it shows them, stalled, running, idle, or gone when
+ * OpenCode no longer knows it. A message waiting in its inbox makes a stalled session look busy.
+ */
+function stateOf(info, waits, stalled, running) {
     if (!info)
         return "gone";
     if (waits)
         return "waiting";
+    if (stalled)
+        return "stalled";
     return running ? "running" : "idle";
 }
 /** One session of the panel: what it is doing, its report and group standing, its last tool call and its cost. */
-async function row(ports, { entry, depth, info, pending, forms, report }) {
+async function row(ports, { entry, depth, info, pending, forms, report }, stalled) {
     const { sessionID } = entry;
     const [messages, status, standing, stopped] = await Promise.all([
         ports.session.context({ sessionID }).catch(() => []),
@@ -54,7 +60,8 @@ async function row(ports, { entry, depth, info, pending, forms, report }) {
         parentID: entry.parentID,
         title: info?.title ?? entry.title,
         depth,
-        state: stateOf(info, pending.length + forms.length, running),
+        state: stateOf(info, pending.length + forms.length, stalled !== undefined, running),
+        ...(stalled !== undefined ? { stalled } : {}),
         ...(info?.outcome ? { outcome: info.outcome } : {}),
         ...(stopped ? { stopped } : {}),
         ...reportRow(report, status),
@@ -69,10 +76,12 @@ async function row(ports, { entry, depth, info, pending, forms, report }) {
 }
 /**
  * The tree panel's rows: the sessions under a session as courier_tree lists them, at most `maxTotal`, the live ones
- * first, then the newest, each as `row` reads it; `truncated` counts the older ones left out.
+ * first, then the newest, each as `row` reads it; `truncated` counts the older ones left out, and `stalled` says the root is.
  */
 export async function panel(ports, rootID) {
     const { kept, leftOut } = await readTree(ports, rootID);
-    const rows = await Promise.all(kept.map((node) => row(ports, node)));
-    return { rows, ...(leftOut ? { truncated: leftOut } : {}) };
+    const stalled = await stalledAmong(ports, [rootID, ...kept.map((node) => node.entry.sessionID)]);
+    const rows = await Promise.all(kept.map((node) => row(ports, node, stalled.get(node.entry.sessionID))));
+    const own = stalled.get(rootID);
+    return { rows, ...(leftOut ? { truncated: leftOut } : {}), ...(own !== undefined ? { stalled: own } : {}) };
 }

package/dist/tree/ports.d.ts

@@ -80,6 +80,35 @@ export interface ChildStore {
     /** Removes report keys `reported` found, each best effort. */
     dropReported(keys: ReadonlyArray<string>): Promise<void>;
 }
+/**
+ * A courier message waiting in a session's inbox, watched until it is delivered: `running` while the session runs a
+ * turn, which takes it at its next step; `idleAt` since the session was last seen idle with it waiting.
+ */
+export interface Wake {
+    readonly sessionID: string;
+    readonly inboxID: string;
+    /** When OpenCode enqueued it. */
+    readonly at: number;
+    /** Its text and description, which waking the session again sends under the same inbox id. */
+    readonly text: string;
+    readonly description?: string;
+    readonly running: boolean;
+    readonly idleAt?: number;
+    /** When the scheduler woke the session again, the message still waiting. */
+    readonly rewoken?: number;
+    /** When the session was found still not woken after that: it is stalled. */
+    readonly stalled?: number;
+}
+export interface WakeStore {
+    /** Writes a watched message, replacing what was kept of it. */
+    put(wake: Wake): Promise<void>;
+    /** The messages watched in a session's inbox. */
+    of(sessionID: string): Promise<Wake[]>;
+    /** Every message watched. */
+    all(): Promise<Wake[]>;
+    /** Stops watching a message: delivered, cancelled, or its session gone. */
+    remove(sessionID: string, inboxID: string): Promise<void>;
+}
 /** A member of a join group with where it is kept. */
 export interface Membership extends Member {
     readonly parentID: string;

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

@@ -14,26 +14,29 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
             }>;
             readonly output: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly running: number;
-                readonly waiting: number;
                 readonly idle: number;
                 readonly groups: readonly {
                     readonly name: string;
                     readonly reported: number;
                     readonly members: number;
                 }[];
+                readonly waiting: number;
+                readonly stalled?: number | undefined;
             }, {
                 readonly running: number;
-                readonly waiting: number;
                 readonly idle: number;
                 readonly groups: readonly {
                     readonly name: string;
                     readonly reported: number;
                     readonly members: number;
                 }[];
+                readonly waiting: number;
+                readonly stalled?: number | undefined;
             }> & import("effect/Schema").Struct<{
                 readonly running: import("effect/Schema").Int;
                 readonly waiting: import("effect/Schema").Int;
                 readonly idle: import("effect/Schema").Int;
+                readonly stalled: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
                 readonly groups: import("effect/Schema").$Array<import("effect/Schema").Struct<{
                     readonly name: import("effect/Schema").String;
                     readonly reported: import("effect/Schema").Int;
@@ -57,7 +60,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     readonly depth: number;
                     readonly created: number;
                     readonly isolated: boolean;
-                    readonly state: "running" | "idle" | "gone" | "waiting";
+                    readonly state: "running" | "idle" | "gone" | "stalled" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -80,6 +83,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                         readonly state: "reported" | "ended" | "owed";
                         readonly status?: string | undefined;
                     } | undefined;
+                    readonly stalled?: number | undefined;
                     readonly outcome?: "failed" | "interrupted" | "succeeded" | undefined;
                     readonly tool?: {
                         readonly name: string;
@@ -87,6 +91,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     } | undefined;
                     readonly cost?: number | undefined;
                 }[];
+                readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
             }, {
                 readonly rows: readonly {
@@ -96,7 +101,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     readonly depth: number;
                     readonly created: number;
                     readonly isolated: boolean;
-                    readonly state: "running" | "idle" | "gone" | "waiting";
+                    readonly state: "running" | "idle" | "gone" | "stalled" | "waiting";
                     readonly waits: readonly ({
                         readonly type: "permission";
                         readonly action: string;
@@ -119,6 +124,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                         readonly state: "reported" | "ended" | "owed";
                         readonly status?: string | undefined;
                     } | undefined;
+                    readonly stalled?: number | undefined;
                     readonly outcome?: "failed" | "interrupted" | "succeeded" | undefined;
                     readonly tool?: {
                         readonly name: string;
@@ -126,6 +132,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     } | undefined;
                     readonly cost?: number | undefined;
                 }[];
+                readonly stalled?: number | undefined;
                 readonly truncated?: number | undefined;
             }> & import("effect/Schema").Struct<{
                 readonly rows: import("effect/Schema").$Array<import("effect/Schema").Struct<{
@@ -133,7 +140,8 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     readonly parentID: import("effect/Schema").String;
                     readonly title: import("effect/Schema").String;
                     readonly depth: import("effect/Schema").Int;
-                    readonly state: import("effect/Schema").Literals<readonly ["running", "waiting", "idle", "gone"]>;
+                    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 stopped: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
                     readonly report: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
@@ -166,6 +174,7 @@ export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "regist
                     }>]>>;
                 }>>;
                 readonly truncated: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+                readonly stalled: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
             }>;
         };
         readonly stop: {