opencode-courier 0.10.0 → 0.10.2

package/README.md

@@ -21,7 +21,7 @@ The edge cases on the live terminal UI, narrated ([what it shows](#demos)).
 ## Quickstart
 
 ```bash
-npm install -g @opencode/cli@2.0.32   # OpenCode V2, at the version courier is tested on
+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
 ```
@@ -42,7 +42,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`). Each release is pinned to one V2 version and tested against it end to end;
-the current one is tested on **OpenCode 2.0.32**. CI also runs the live suite on the newest OpenCode
+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?
@@ -108,20 +108,20 @@ version than the pinned one writes one line to the server log
 <!-- 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 | 2.1.2 |
+| 0.10.1 | 2.1.0 |
 | 0.7.3, 0.8.0, 0.9.0, 0.10.0 | 2.0.32 |
-| 0.7.2 | 2.0.31 |
-| 0.7.1 | 2.0.30 |
 <!-- compat-table:end -->
 
 Older releases and their versions: [every release](docs/reference.md#the-opencode-version).
 
 The [terminal part](#in-the-terminal) relies on the host to provide its UI modules and is tested on
-OpenCode 2.0.32 only; the server part works on older V2 hosts from 2.0.4 on.
+OpenCode 2.1.2 only; the server part works 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.32
+npm install -g @opencode/cli@2.1.2
 ```
 
 ### The plugin
@@ -175,7 +175,7 @@ From a local clone, `bun install && npm run build`, then list its `dist` **direc
 |---|---|
 | `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, last reply and what it waits on. For check-ins, not for waiting. |
+| `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. |
@@ -239,7 +239,10 @@ options in the plugin's `options`, in the global config:
 | `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, or a session below it is live.
+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)).
 

package/dist/memory/domain.d.ts

@@ -88,7 +88,10 @@ export interface TreeRecord {
     readonly split: string;
     /** Absent until the top states a split line worded otherwise than `split`; newest last, at most `MAX_REVISIONS`. */
     readonly revisions?: ReadonlyArray<Revision>;
-    /** Whether, at the last refresh, no session in the tree ran and every part had settled: none was out or stalled. */
+    /**
+     * Whether, at the last refresh, no session in the tree ran or had a courier message waiting in its inbox for a turn, and
+     * every part had settled: none was out or stalled.
+     */
     readonly finished: boolean;
     readonly recalled?: Recalled;
     /** Absent until a session of the tree that is not a leaf wrote one; a second note replaces the first. */

package/dist/memory/events.js

@@ -1,5 +1,5 @@
 import { claim } from "../platform/bounded.js";
-import { childrenOf, indexedLineage } from "../tree/index.js";
+import { childrenOf, endsIdle, indexedLineage } from "../tree/index.js";
 import { refresh } from "./record.js";
 const TURN_ENDS = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"]);
 /**
@@ -16,13 +16,15 @@ export async function topOf(ports, state, sessionID) {
 }
 /** A turn ended in a tree: its record is written again, once however many subscriptions see the event. Returns the top refreshed. */
 export async function noteTurnEnd(ports, state, event) {
-    // A shutdown's interruption is resumed on the next start: nothing ended.
-    if (event.data.reason === "shutdown")
-        return undefined;
     const top = await topOf(ports, state, event.data.sessionID);
+    if (top === undefined)
+        return undefined;
+    // A shutdown's interruption is resumed on the next start, unless a plain decline ended the turn: its transcript ends on an aborted step.
+    if (event.data.reason === "shutdown" && !endsIdle(await ports.session.context({ sessionID: event.data.sessionID }).catch(() => [])))
+        return undefined;
     // Claimed after the lookup, so other sessions' turns do not crowd `seen`; released on a failure, as a write is
     // the same twice, so the hub's other subscription may still make it.
-    if (top === undefined || !claim(state.seen, event.id))
+    if (!claim(state.seen, event.id))
         return undefined;
     try {
         await refresh(ports, state, top, event.created ?? ports.now(), event.data.sessionID);

package/dist/memory/record.js

@@ -1,5 +1,5 @@
 import { finite, isNotFound, millis } from "../platform/json.js";
-import { busy, contextOf, reportState, stalledAmong, subtree } from "../tree/index.js";
+import { contextOf, reportState, stalledAmong, subtree, turnIn, turnOf, waitsInInbox } from "../tree/index.js";
 import { isSettled, isStated, mergeParts, NOT_STATED, partStatus, replacingMention, revise, splitLinesOf, splitOf, unreadPart } from "./domain.js";
 import { memoryStore } from "./store.js";
 /** A session's replies, in order, each with when it was created, for its split lines; only the `finished` ones when asked. */
@@ -24,19 +24,27 @@ const keptUse = (last) => ({
 /** A session's info, or `gone` when OpenCode no longer knows it; neither when it could not be read for another reason. */
 const infoOf = (ports, sessionID) => ports.session.get({ sessionID }).then((info) => ({ info, gone: false }), (error) => ({ gone: isNotFound(error) }));
 /**
- * One session of the tree as its record keeps it, without its use when its messages were not read (only when its turn
- * `ended` or it is `known` to no record yet), without a duration when its info was not, and whether it runs now.
+ * One session of the tree as its record keeps it, without its use when its messages were not read for it (only when its turn
+ * `ended` or it is `known` to no record yet), without a duration when its info was not, and whether it runs or is owed a turn.
  */
 async function part(ports, windows, { entry, depth }, stalled, at, known, ended) {
     const { sessionID } = entry;
-    const [{ info, gone }, use, report] = await Promise.all([
-        infoOf(ports, sessionID),
-        ended || !known ? ports.session.context({ sessionID }).then((messages) => useOf(messages, windows), () => undefined) : undefined,
+    // Read once: for its use, and for whether it runs when its times do not show rest.
+    const readAt = Date.now();
+    const messages = ended || !known ? ports.session.context({ sessionID }) : undefined;
+    const [{ info, gone, running, endedAt }, use, report, waiting] = await Promise.all([
+        infoOf(ports, sessionID).then(async (one) => {
+            if (!one.info)
+                return { ...one, running: false };
+            const turn = messages ? turnIn(ports.session, sessionID, one.info.time, messages, readAt) : turnOf(ports.session, sessionID, one.info.time);
+            return { ...one, ...(await turn) };
+        }),
+        messages?.then((read) => useOf(read, windows), () => undefined),
         reportState(ports.storage, sessionID).catch(() => undefined),
+        waitsInInbox(ports, sessionID).catch(() => true),
     ]);
-    const running = info !== undefined && busy(info.time);
     const created = finite(millis(info?.time.created)) ?? entry.createdAt;
-    const end = info && !running && info.time.idle !== undefined ? millis(info.time.idle) : at;
+    const end = info && !running && endedAt !== undefined ? endedAt : at;
     const cost = finite(info?.cost);
     const record = {
         sessionID,
@@ -48,7 +56,8 @@ async function part(ports, windows, { entry, depth }, stalled, at, known, ended)
         ...(info ? { duration: Math.max(0, end - created) } : {}),
         ...(cost !== undefined ? { cost } : {}),
     };
-    return { record, use, running, unread: info === undefined, gone };
+    // A courier message waiting to be taken keeps it unfinished, unless OpenCode no longer knows it, which then takes none.
+    return { record, use, running: running || (waiting && !gone), unread: info === undefined, gone };
 }
 /** Of the parts last recorded, those the roster has forgotten before they settled whose session OpenCode no longer knows. */
 async function goneSince(ports, parts, onRoster) {
@@ -56,6 +65,13 @@ async function goneSince(ports, parts, onRoster) {
     const looked = await Promise.all(unsettled.map(async ({ sessionID }) => ({ sessionID, ...(await infoOf(ports, sessionID)) })));
     return new Set(looked.flatMap((one) => (one.gone ? [one.sessionID] : [])));
 }
+/** The top's turn: from the transcript read at `readAt`, unless a stamp since then moved its times, which `turnOf` reads again. */
+async function topTurnAfter(ports, top, info, messages, readAt) {
+    const fresh = await ports.session.get({ sessionID: top }).catch(() => undefined);
+    if (fresh && millis(fresh.time.updated) > readAt)
+        return turnOf(ports.session, top, fresh.time);
+    return messages ? turnIn(ports.session, top, info.time, messages, readAt) : turnOf(ports.session, top, info.time);
+}
 /**
  * Writes the record of the tree under `top` as it stands at `at`, after the turn of `ended`; a part the roster has forgotten
  * keeps its last recorded state, unless found gone before it settled. Nothing for a top unknown to OpenCode or with memory off.
@@ -77,9 +93,9 @@ export async function refresh(ports, state, top, at, ended) {
     // The split lines are in the top's own replies, so only its own turn end can revise one stated already; another's reads
     // them while none is stated, and only the replies finished, never a line the top is still writing.
     const own = ended === top;
-    const replies = own || !isStated(previous?.split ?? NOT_STATED)
-        ? ports.session.context({ sessionID: top }).then((messages) => repliesOf(messages, !own), () => [])
-        : [];
+    const topReadAt = Date.now();
+    const topMessages = own || !isStated(previous?.split ?? NOT_STATED) ? ports.session.context({ sessionID: top }) : undefined;
+    const replies = topMessages ? topMessages.then((messages) => repliesOf(messages, !own), () => []) : [];
     const stalled = await stalledAmong(ports, nodes.map((node) => node.entry.sessionID));
     const windows = [...state.windows.values()];
     const known = new Set(previous?.parts.map((one) => one.sessionID));
@@ -87,7 +103,10 @@ export async function refresh(ports, state, top, at, ended) {
         Promise.all(nodes.map((node) => part(ports, windows, node, stalled.has(node.entry.sessionID), at, known.has(node.entry.sessionID), node.entry.sessionID === ended))),
         goneSince(ports, previous?.parts ?? [], new Set(nodes.map((node) => node.entry.sessionID))),
     ]);
-    const said = await replies;
+    // A courier message waiting in the top's inbox is a turn its transcript does not show yet, as for a part; a store that
+    // cannot be read counts as one waiting, as `runs` counts a transcript it cannot read as running.
+    const topTurn = topTurnAfter(ports, top, info, topMessages, topReadAt);
+    const [said, topRunning, topOwed] = await Promise.all([replies, topTurn.then((turn) => turn.running), waitsInInbox(ports, top).catch(() => true)]);
     // Read again just before the write: a courier_recall or courier_note call, or another turn end's refresh, wrote meanwhile.
     const latest = (await store.get(info.projectID, top).catch(() => previous)) ?? previous;
     const last = new Map(latest?.parts.map((one) => [one.sessionID, one]));
@@ -114,7 +133,7 @@ export async function refresh(ports, state, top, at, ended) {
         title: info.title ?? previous?.title ?? "",
         split,
         ...(revisions ? { revisions } : {}),
-        finished: !busy(info.time) && !read.some(({ running }) => running) && parts.every((one) => isSettled(one.status)),
+        finished: !topRunning && !topOwed && !read.some(({ running }) => running) && parts.every((one) => isSettled(one.status)),
         ...(recalled ? { recalled } : {}),
         ...(lesson ? { lesson } : {}),
         parts,

package/dist/scheduling/later.d.ts

@@ -11,8 +11,8 @@ export interface LaterEntry {
 }
 export interface LaterPorts {
     readonly storage: Storage;
-    /** `get` for the release of a join group, which waits for its parent's turn to end. */
-    readonly session: Pick<Context["session"], "synthetic" | "get">;
+    /** `get` for the release of a join group, which waits for its parent's turn to end; `get` and `context` for a missed wake (`ctx.session`). */
+    readonly session: Pick<Context["session"], "synthetic" | "get" | "context">;
     readonly now: () => number;
     readonly newID: () => string;
     readonly log: (message: string) => void;

package/dist/tree/domain.d.ts

@@ -24,13 +24,37 @@ export declare function readNativeChildren(options: unknown): {
 };
 /** A session's times, as `session.get` gives them. */
 type Times = Awaited<ReturnType<Context["session"]["get"]>>["time"];
-/** Whether a session with these times runs: it has never finished a turn, or something reached it after the last one ended. */
-export declare const busy: (time: Pick<Times, "updated" | "idle">) => boolean;
+/** A session's times as `busy` reads them. */
+export type BusyTimes = Pick<Times, "updated" | "idle">;
 /**
- * Whether a session a tree is read of is live: it runs (as the limits count it: busy, and its turn has not failed or
- * been interrupted since its last prompt), waits on a request or form, or owes a report; one OpenCode no longer knows is not.
+ * Whether a session may run by its times: it has never finished a turn, or `updated` was stamped after the last one ended, as
+ * a step does, and as much that is no activity does (a rename, an archive, a waiting inbox item), so only its transcript tells.
  */
-export declare const isLive: (time: Pick<Times, "updated" | "idle"> | undefined, waits: number, report: {
+export declare const busy: (time: BusyTimes) => boolean;
+/** A stored message as `turnEnd` reads it: an assistant message's `error` says how its step ended. */
+type Stored = {
+    readonly type: string;
+    readonly error?: {
+        readonly type: string;
+    };
+    readonly time?: {
+        readonly created?: unknown;
+        readonly completed?: unknown;
+    };
+};
+/**
+ * The message a transcript's last turn ended on, unless one runs, past asides made since: an `idle` message, or a step
+ * interrupted with none after it, as a declined permission or dismissed question ends a turn, recording no `idle` (#326).
+ */
+export declare function turnEnd<M extends Stored>(messages: ReadonlyArray<M>): M | undefined;
+export declare const endsIdle: (messages: ReadonlyArray<Stored>) => boolean;
+/** When the turn `end` ended: the session's idle time for an `idle` message, else when its interrupted step ended. */
+export declare function endedAt(end: Stored, time: BusyTimes): number | undefined;
+/**
+ * Whether a session of a tree read is live, for a cut listing's order: it runs (its turn not failed or interrupted since its last
+ * prompt), waits on a request or form, or owes a report, but not, unlike for the limits, for a message waiting in its inbox.
+ */
+export declare const isLive: (running: boolean | undefined, waits: number, report: {
     readonly owes: boolean;
     readonly ended: boolean;
 } | undefined) => boolean;

package/dist/tree/domain.js

@@ -23,13 +23,32 @@ export function readNativeChildren(options) {
         return { nativeChildren: value === true, problems: [] };
     return { nativeChildren: false, problems: [`nativeChildren must be true or false, not ${JSON.stringify(value)}; using false`] };
 }
-/** Whether a session with these times runs: it has never finished a turn, or something reached it after the last one ended. */
+/**
+ * Whether a session may run by its times: it has never finished a turn, or `updated` was stamped after the last one ended, as
+ * a step does, and as much that is no activity does (a rename, an archive, a waiting inbox item), so only its transcript tells.
+ */
 export const busy = (time) => time.idle === undefined || millis(time.updated) > millis(time.idle);
+/** The messages the person's switch of agent or model, move or shell command appends, at rest or mid-turn alike. */
+const ASIDES = new Set(["agent-switched", "model-switched", "location-switched", "shell"]);
+/**
+ * The message a transcript's last turn ended on, unless one runs, past asides made since: an `idle` message, or a step
+ * interrupted with none after it, as a declined permission or dismissed question ends a turn, recording no `idle` (#326).
+ */
+export function turnEnd(messages) {
+    const last = messages.findLast((message) => !ASIDES.has(message.type));
+    return last?.type === "idle" || (last?.type === "assistant" && last.error?.type === "aborted") ? last : undefined;
+}
+export const endsIdle = (messages) => turnEnd(messages) !== undefined;
+/** When the turn `end` ended: the session's idle time for an `idle` message, else when its interrupted step ended. */
+export function endedAt(end, time) {
+    const at = end.type === "idle" ? millis(time.idle) : millis(end.time?.completed ?? end.time?.created);
+    return Number.isFinite(at) ? at : undefined;
+}
 /**
- * Whether a session a tree is read of is live: it runs (as the limits count it: busy, and its turn has not failed or
- * been interrupted since its last prompt), waits on a request or form, or owes a report; one OpenCode no longer knows is not.
+ * Whether a session of a tree read is live, for a cut listing's order: it runs (its turn not failed or interrupted since its last
+ * prompt), waits on a request or form, or owes a report, but not, unlike for the limits, for a message waiting in its inbox.
  */
-export const isLive = (time, waits, report) => time !== undefined && ((busy(time) && !report?.ended) || waits > 0 || (report?.owes ?? false));
+export const isLive = (running, waits, report) => running !== undefined && ((running && !report?.ended) || waits > 0 || (report?.owes ?? false));
 /**
  * Which sessions a listing of at most `max` keeps, of a tree read in the order it is drawn: the live ones first, then
  * the newest, each with the sessions above it so the tree still draws; `leftOut` counts the rest.

package/dist/tree/events.d.ts

@@ -46,8 +46,8 @@ export declare function notePrompt(ports: WatchPorts, event: SessionEvent & {
     };
 }, inbox?: Map<string, string>): Promise<boolean>;
 /**
- * Notes that a spawned session's turn was stopped, which takes it out of its group without a report; one
- * stopped by a shutdown resumes on the next start.
+ * Notes that a spawned session's turn was stopped, which takes it out of its group without a report; a
+ * shutdown's is left to `reportDeclined`, as one stopped between steps resumes on the next start.
  */
 export declare function noteInterrupted(ports: WatchPorts, event: SessionEvent): Promise<boolean>;
 /**
@@ -64,6 +64,11 @@ export declare const together: (...suppliers: Waits[]) => Waits;
  * prompt, unless it waits; finds the session by the reverse index alone. Returns the parents told.
  */
 export declare function reportSilent(ports: WatchPorts, seen: Set<string>, event: SessionEvent, outside: Waits): Promise<string[]>;
+/**
+ * A session's turn that OpenCode reports as a shutdown ended in a plain decline, if its transcript ends on an aborted step: its
+ * parent is told as for a turn that succeeded without a report. A real shutdown during a step reads the same, and is told too.
+ */
+export declare function reportDeclined(ports: WatchPorts, seen: Set<string>, event: SessionEvent, outside: Waits): Promise<string[]>;
 /**
  * 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.

package/dist/tree/events.js

@@ -1,5 +1,6 @@
 import { envelope } from "../kernel/protocol.js";
 import { claim, SEEN_MAX, setBounded } from "../platform/bounded.js";
+import { endsIdle } from "./domain.js";
 import { forgetChild, forgetDeleted } from "./forget.js";
 import { hasCompleteGroup, leave, outIn } from "./group.js";
 import { awaited, reportOf, stoppedSincePrompt } from "./report.js";
@@ -70,8 +71,8 @@ export async function notePrompt(ports, event, inbox) {
     return true;
 }
 /**
- * Notes that a spawned session's turn was stopped, which takes it out of its group without a report; one
- * stopped by a shutdown resumes on the next start.
+ * Notes that a spawned session's turn was stopped, which takes it out of its group without a report; a
+ * shutdown's is left to `reportDeclined`, as one stopped between steps resumes on the next start.
  */
 export async function noteInterrupted(ports, event) {
     if (event.data.reason === "shutdown")
@@ -165,8 +166,19 @@ export async function reportSilent(ports, seen, event, outside) {
     }
     return [entry.parentID];
 }
+/**
+ * A session's turn that OpenCode reports as a shutdown ended in a plain decline, if its transcript ends on an aborted step: its
+ * parent is told as for a turn that succeeded without a report. A real shutdown during a step reads the same, and is told too.
+ */
+export async function reportDeclined(ports, seen, event, outside) {
+    if (event.data.reason !== "shutdown" || (await childStore(ports.storage).indexedParent(event.data.sessionID)) === undefined)
+        return [];
+    if (!endsIdle(await ports.session.context({ sessionID: event.data.sessionID }).catch(() => [])))
+        return [];
+    return reportSilent(ports, seen, event, outside);
+}
 const TURN_ENDS = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"]);
-/** A session's turn ended, sealing its groups: one that is complete has the scheduler deliver it now. */
+/** A session's turn ended, sealing its groups: one that is complete has the scheduler deliver it now; not a shutdown's, which stamps no idle time. */
 async function sealGroups(ports, event) {
     if (event.data.reason === "shutdown")
         return;
@@ -184,8 +196,10 @@ function routeTree(ports, state, outside, event) {
         return reportFailure(ports, state.seen, event);
     if (event.type === "session.execution.succeeded")
         return reportSilent(ports, state.seen, event, outside);
-    if (event.type === "session.execution.interrupted")
-        return noteInterrupted(ports, event);
+    if (event.type === "session.execution.interrupted") {
+        const interrupted = event;
+        return interrupted.data.reason === "shutdown" ? reportDeclined(ports, state.seen, interrupted, outside) : noteInterrupted(ports, interrupted);
+    }
     if (event.type === "session.inbox.enqueued")
         return noteEnqueued(ports, state.inbox, event);
     if (event.type === "session.inbox.delivered")

package/dist/tree/group.js

@@ -131,8 +131,8 @@ async function releaseClaimed(ports, claimed, key, { parentID, group }) {
     }
 }
 /**
- * Whether the parent's turn that started a group's last member has ended, so no more join it; `gone` when OpenCode no
- * longer knows the parent. A turn ending stamps the session's `time.idle`, which a shutdown does not.
+ * Whether the parent's turn that started a group's last member has ended, so no more join it; `gone` when OpenCode no longer knows the
+ * parent. Only a turn ending stamps `time.idle`: a shutdown, or a plain permission decline reported as one, holds it until the next ends.
  */
 async function sealed(ports, parentID, members) {
     const joined = Math.max(...members.map((member) => member.joinedAt));

package/dist/tree/index.d.ts

@@ -1,12 +1,13 @@
 export { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
 export { shapeContext } from "./context.js";
-export { busy, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
+export { endsIdle, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
 export { contextOf } from "./panel.js";
 export type { CleanupPorts, CourierPorts, ModelWindow, Pending, PendingPrompt, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
 export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS, type ReportState } from "./roster.js";
+export { runs, turnIn, turnOf, type Turn } from "./running.js";
 export { subtree, type Below } from "./subtree.js";
 export { registerTreeRpc } from "./rpc-handlers.js";
 export { addTreeTools } from "./tools.js";
-export { stalledAmong, wakeMissed } from "./wake.js";
+export { stalledAmong, waitsInInbox, wakeMissed } from "./wake.js";

package/dist/tree/index.js

@@ -2,12 +2,13 @@
 // for `src/index.ts`, the lineage and subtree queries and types `person/` reads, and what `memory/` reads of each session.
 export { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
 export { shapeContext } from "./context.js";
-export { busy, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
+export { endsIdle, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
 export { contextOf } from "./panel.js";
 export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS } from "./roster.js";
+export { runs, turnIn, turnOf } from "./running.js";
 export { subtree } from "./subtree.js";
 export { registerTreeRpc } from "./rpc-handlers.js";
 export { addTreeTools } from "./tools.js";
-export { stalledAmong, wakeMissed } from "./wake.js";
+export { stalledAmong, waitsInInbox, wakeMissed } from "./wake.js";

package/dist/tree/limits.js

@@ -1,11 +1,13 @@
 import { isNotFound } from "../platform/json.js";
-import { busy, bySession, lineageBy } from "./domain.js";
+import { bySession, lineageBy } from "./domain.js";
 import { reportOf } from "./report.js";
+import { runs } from "./running.js";
 import { childStore } from "./store.js";
 import { childrenRefusal, depthRefusal, totalRefusal } from "./text.js";
+import { waitsInInbox } from "./wake.js";
 /**
- * Whether a spawned session counts against the limits: it runs, unless its turn failed or was
- * interrupted since its last prompt, or it owes its parent a report. One OpenCode no longer knows does not.
+ * Whether a spawned session counts against the limits: it runs (its turn not failed or interrupted since its last prompt), owes
+ * its parent a report, or has a courier message waiting in its inbox that it is to be woken for. One OpenCode no longer knows does not.
  */
 async function live(ports, sessionID) {
     const [time, report] = await Promise.all([
@@ -15,8 +17,9 @@ async function live(ports, sessionID) {
     if (time === null)
         return false;
     // One whose first prompt failed never ran, and has no idle time to tell so.
-    const runs = time !== undefined && busy(time) && !report?.ended;
-    return runs || (report?.owes ?? false);
+    const running = time !== undefined && !report?.ended && (await runs(ports.session, sessionID, time));
+    // A waiting message is in no transcript until delivered, so `runs` misses it; a stalled one, which nothing wakes it for, is not counted.
+    return running || (report?.owes ?? false) || (await waitsInInbox(ports, sessionID, { stalled: false }).catch(() => true));
 }
 /**
  * Checks the limits for a spawn from `parentID`, then holds its place in `gate` until `release`;
@@ -42,9 +45,9 @@ async function check(ports, parentID) {
     const top = chain.at(-1)?.parentID ?? parentID;
     const chains = new Map(entries.map((entry) => [entry.sessionID, lineageBy(parents, entry.sessionID)]));
     const tree = entries.filter((entry) => chains.get(entry.sessionID).at(-1)?.parentID === top);
-    const runs = await Promise.all(tree.map((entry) => live(ports, entry.sessionID)));
+    const counting = await Promise.all(tree.map((entry) => live(ports, entry.sessionID)));
     // A session waiting on a live descendant is live too: the brief tells it to end its turn meanwhile.
-    const active = new Set(tree.filter((_, i) => runs[i]).flatMap((entry) => [entry.sessionID, ...chains.get(entry.sessionID).map((above) => above.parentID)]));
+    const active = new Set(tree.filter((_, i) => counting[i]).flatMap((entry) => [entry.sessionID, ...chains.get(entry.sessionID).map((above) => above.parentID)]));
     const counted = tree.filter((entry) => active.has(entry.sessionID));
     // A spawn whose child is on the roster already is counted there, if it is live, not by its reservation.
     const recorded = new Set(tree.map((entry) => entry.sessionID));

package/dist/tree/panel.d.ts

@@ -6,7 +6,7 @@ export declare function lastTool(messages: Messages): {
     name: string;
     at: number;
 } | undefined;
-/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.0.32): the last usage since the last compaction over its model's window. */
+/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.1.0): the last usage since the last compaction over its model's window. */
 export declare function contextOf(messages: Messages, windows: ReadonlyArray<ModelWindow>): number | undefined;
 /** A request as the panel says what a paused session waits on: a permission request, or its first question. */
 export declare const waitOf: (pending: Pending) => Wait;

package/dist/tree/panel.js

@@ -1,4 +1,3 @@
-import { busy } from "./domain.js";
 import { lastStatus, stoppedSincePrompt } from "./report.js";
 import { standingIn } from "./status.js";
 import { childStore } from "./store.js";
@@ -15,7 +14,7 @@ export function lastTool(messages) {
     }
     return undefined;
 }
-/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.0.32): the last usage since the last compaction over its model's window. */
+/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.1.0): the last usage since the last compaction over its model's window. */
 export function contextOf(messages, windows) {
     const compacted = messages.findLastIndex((message) => message.type === "compaction" && message.status === "completed");
     const last = messages.findLast((message, index) => index > compacted && message.type === "assistant" && message.tokens !== undefined);
@@ -44,7 +43,7 @@ function reportRow(report, status) {
 }
 /**
  * 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.
+ * OpenCode no longer knows it. A message waiting in its inbox is no turn (`runs`); a stalled one reads stalled.
  */
 function stateOf(info, waits, stalled, running) {
     if (!info)
@@ -56,7 +55,7 @@ function stateOf(info, waits, stalled, running) {
     return running ? "running" : "idle";
 }
 /** One session of the panel: what it is doing, its report and group standing, its last tool call, context use and cost. */
-async function row(ports, windows, { entry, depth, info, pending, forms, report }, stalled) {
+async function row(ports, windows, { entry, depth, info, running, endedAt, pending, forms, report }, stalled) {
     const { sessionID } = entry;
     const [messages, status, standing, stopped] = await Promise.all([
         ports.session.context({ sessionID }).catch(() => []),
@@ -64,7 +63,6 @@ async function row(ports, windows, { entry, depth, info, pending, forms, report
         entry.group ? standingIn(ports, entry, entry.group) : undefined,
         stoppedSincePrompt(childStore(ports.storage), sessionID).catch(() => false),
     ]);
-    const running = info !== undefined && busy(info.time);
     const tool = lastTool(messages);
     const context = contextOf(messages, windows);
     return {
@@ -80,7 +78,7 @@ async function row(ports, windows, { entry, depth, info, pending, forms, report
         ...(entry.group && standing ? { group: { name: entry.group, standing } } : {}),
         isolated: entry.isolated,
         created: info?.time.created ?? entry.createdAt,
-        ...(info && !running && info.time.idle !== undefined ? { idle: info.time.idle } : {}),
+        ...(info && !running && endedAt !== undefined ? { idle: endedAt } : {}),
         ...(info ? { cost: info.cost } : {}),
         ...(context !== undefined ? { context } : {}),
         ...(tool ? { tool } : {}),

package/dist/tree/ports.d.ts

@@ -227,7 +227,7 @@ export interface SpawnGate {
 }
 export interface LimitPorts {
     readonly storage: RosterStorage;
-    readonly session: Pick<Context["session"], "get">;
+    readonly session: Pick<Context["session"], "get" | "context">;
     readonly limits: Limits;
     readonly gate: SpawnGate;
 }

package/dist/tree/running.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from "@opencode/plugin";
+import { type BusyTimes } from "./domain.js";
+type Session = Pick<Plugin.Context["session"], "context">;
+/** Whether a session runs and, when it does not, when its last turn ended, where known. */
+export interface Turn {
+    readonly running: boolean;
+    readonly endedAt?: number;
+}
+type Messages = Awaited<ReturnType<Session["context"]>>;
+/**
+ * Whether a session runs and, at rest, when its last turn ended: by its times when they show rest, else by its transcript
+ * (#324, #326), kept until the next stamp, a rest for `REST_MS` and not within `FRESH_MS` of it; one unread or empty runs.
+ */
+export declare function turnOf(session: Session, sessionID: string, time: BusyTimes, now?: number): Promise<Turn>;
+/** `turnOf` for a caller that reads the transcript itself: it answers from these `messages`, read just now, and keeps the answer. */
+export declare function turnIn(session: Session, sessionID: string, time: BusyTimes, messages: Promise<Messages>, now?: number): Promise<Turn>;
+export declare const runs: (session: Session, sessionID: string, time: BusyTimes, now?: number) => Promise<boolean>;
+export {};

package/dist/tree/running.js

@@ -0,0 +1,58 @@
+import { millis } from "../platform/json.js";
+import { setBounded } from "../platform/bounded.js";
+import { busy, endedAt, turnEnd } from "./domain.js";
+/** How many sessions' answers each session port remembers. */
+const ANSWERS_MAX = 500;
+/** How long after its stamp an answer of rest is read again: an item enqueued then may be delivered, stamping nothing until its step. */
+const FRESH_MS = 10_000;
+/** How long an answer of rest is kept: an item waiting since a lost wake is delivered on the wake sent again, which stamps nothing. */
+const REST_MS = 30_000;
+const RUNNING = { running: true };
+const rest = (at) => (at === undefined ? { running: false } : { running: false, endedAt: at });
+/** Each session port's last answer per session, which holds until the next stamp, but for those `turnOf` drops or keeps `until`. */
+const answers = new WeakMap();
+/**
+ * Whether a session runs and, at rest, when its last turn ended: by its times when they show rest, else by its transcript
+ * (#324, #326), kept until the next stamp, a rest for `REST_MS` and not within `FRESH_MS` of it; one unread or empty runs.
+ */
+export function turnOf(session, sessionID, time, now = Date.now()) {
+    return resolve(session, sessionID, time, now, () => session.context({ sessionID }), true);
+}
+/** `turnOf` for a caller that reads the transcript itself: it answers from these `messages`, read just now, and keeps the answer. */
+export function turnIn(session, sessionID, time, messages, now = Date.now()) {
+    return resolve(session, sessionID, time, now, () => messages, false);
+}
+function resolve(session, sessionID, time, now, load, cached) {
+    if (!busy(time))
+        return Promise.resolve(rest(millis(time.idle)));
+    const known = answers.get(session) ?? new Map();
+    answers.set(session, known);
+    const stamp = `${millis(time.updated)} ${millis(time.idle)}`;
+    const found = known.get(sessionID);
+    if (cached && found?.stamp === stamp && now < found.until)
+        return found.turn;
+    // Only its own answer: a newer read of the session may have taken its place meanwhile.
+    const forget = () => {
+        if (known.get(sessionID) === answer)
+            known.delete(sessionID);
+    };
+    const turn = load().then((messages) => {
+        const end = turnEnd(messages);
+        if (!messages.length)
+            forget();
+        if (!end)
+            return RUNNING;
+        if (now - millis(time.updated) < FRESH_MS)
+            forget();
+        answer.until = now + REST_MS;
+        return rest(endedAt(end, time));
+    }, () => {
+        forget();
+        return RUNNING;
+    });
+    const answer = { stamp, turn, until: Number.POSITIVE_INFINITY };
+    known.delete(sessionID);
+    setBounded(known, sessionID, answer, ANSWERS_MAX);
+    return turn;
+}
+export const runs = (session, sessionID, time, now) => turnOf(session, sessionID, time, now).then((turn) => turn.running);