commandmate 0.27.1 → 0.29.0

package/dist/server/src/lib/detection/terminal-columns.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Terminal COLUMNS, as distinct from UTF-16 units (Issue #2112).
+ *
+ * Extracted verbatim from `opencode-pane-obstruction.ts`, where Issue #2095
+ * introduced it as a private helper, because #2112 reads a second geometry off
+ * the same frames — a rectangle's left and right edges rather than a box's right
+ * edge — and needs the identical answer to "which character sits at column N".
+ * Two copies of a column-counting rule is how the two readings would come to
+ * disagree about the same frame while both claiming to measure columns; the
+ * repository already makes that argument for `excerpt.ts` and for
+ * `status-evidence.ts`.
+ *
+ * A leaf module by design: it imports nothing, so the detector modules, the
+ * payload builder and the client components can all share it.
+ *
+ * @module lib/detection/terminal-columns
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indexAtColumn = indexAtColumn;
+exports.sliceColumns = sliceColumns;
+exports.visibleWidth = visibleWidth;
+/** One code point that occupies no terminal column. See {@link indexAtColumn}. */
+const COMBINING_MARK = /^\p{M}$/u;
+/**
+ * The UTF-16 index at which terminal column `column` begins.
+ *
+ * `String.prototype.slice` counts UTF-16 units and this rule is about terminal
+ * COLUMNS. The two disagree in two ways, and only one of them can invent a
+ * column that is not there:
+ *
+ *  - **Combining marks are one code point and ZERO columns**, so a row of
+ *    heavily-combining script — Thai, Devanagari, Hebrew with nikud, macOS's
+ *    NFD Latin — is LONGER in units than in columns. Uncorrected, a box that
+ *    owns the full pane width could slice to a non-empty tail and report a
+ *    sidebar on a pane that has none. This skips them, which removes the case
+ *    rather than making it unlikely. They are consumed greedily once the column
+ *    is reached, too: a lone mark left in the tail would survive `trim()` and be
+ *    counted as evidence.
+ *  - **East Asian wide characters are one code point and TWO columns**, so a row
+ *    of Japanese is SHORTER in units than in columns. That is NOT corrected
+ *    here, deliberately: undercounting cuts LATER than the true column, which
+ *    can only shorten an excerpt or miss a second column — never invent one.
+ *    It is also exactly what a plain `slice` already did, so nothing regresses.
+ *    Carrying a wcwidth table to buy back a few characters of excerpt would put
+ *    a second source of truth about character widths in the repository for no
+ *    verdict's benefit.
+ *
+ * Iterates code points, never UTF-16 units, so a surrogate pair is one step.
+ */
+function indexAtColumn(line, column) {
+    // Exact, not an approximation: counted columns can never exceed the unit
+    // count, so a line this short consumes whole in the loop below and returns
+    // the same answer. It is here because it is the case every full-width box row
+    // takes, on every poll and every render.
+    if (line.length <= column)
+        return line.length;
+    let columns = 0;
+    let index = 0;
+    for (const char of line) {
+        const width = COMBINING_MARK.test(char) ? 0 : 1;
+        if (width === 1 && columns >= column)
+            break;
+        columns += width;
+        index += char.length;
+    }
+    return index;
+}
+/**
+ * The text occupying terminal columns `[left, right)` of one already-stripped
+ * row.
+ *
+ * Both edges go through {@link indexAtColumn}, so the same undercounting applies
+ * to both and a slice can only be SHORTER than the true column range — never
+ * wider than the rectangle a caller asked about.
+ */
+function sliceColumns(line, left, right) {
+    return line.slice(indexAtColumn(line, left), indexAtColumn(line, right));
+}
+/**
+ * How many terminal columns an already-stripped row occupies.
+ *
+ * Counted with the same rule {@link indexAtColumn} walks, so "column
+ * `visibleWidth(line)`" is always one past the row's last cell and never lands
+ * inside it.
+ */
+function visibleWidth(line) {
+    let columns = 0;
+    for (const char of line) {
+        if (!COMBINING_MARK.test(char))
+            columns += 1;
+    }
+    return columns;
+}

package/dist/server/src/lib/detection/tools/opencode/detect.js

@@ -12,6 +12,7 @@ exports.opencodeStatusDetector = exports.VERIFIED_AGAINST = void 0;
 exports.readIdleEvidence = readIdleEvidence;
 const cli_patterns_1 = require("../../cli-patterns");
 const status_reason_1 = require("../../status-reason");
+const opencode_modal_overlay_1 = require("../../opencode-modal-overlay");
 const prompt_1 = require("./prompt");
 const frame_1 = require("../frame");
 const run_detection_1 = require("../run-detection");
@@ -90,6 +91,7 @@ exports.opencodeStatusDetector = (0, run_detection_1.createToolStatusDetector)({
         // A. "esc interrupt" in footer → actively processing (running)
         // B. Find footer boundary via "ctrl+t" keybinding line, extract content above it, check for thinking → running
         // C. Same content window, check for a selection list → waiting
+        // C2. A modal overlay painted over the transcript → waiting (Issue #2112)
         // D. Same content window, check for ▣ Build completion WITH a duration → ready
         // E. Idle composer placeholder inside the input box gutter → ready (Issue #1883)
         // A0. Permission dialog (Issue #1893) — ahead of every other opencode branch.
@@ -170,6 +172,47 @@ exports.opencodeStatusDetector = (0, run_detection_1.createToolStatusDetector)({
                 evidence: 'positive',
             };
         }
+        // C2. A modal overlay painted over the transcript (Issue #2112).
+        //
+        // Branch C above only recognises three ALLOWLISTED headings (`Select model`
+        // / `Select provider` / `Connect a provider`, narrowed there by #1896), and
+        // opencode has five more dialogs drawn in the same chrome. `Select agent`,
+        // `Sessions` and `Timeline` all fell through to branch D, which matched the
+        // `▣ Build · <model> · 2.8s` marker of the turn BEFORE the dialog was
+        // opened and published a pane blocked on a human as `ready` /
+        // `opencode_response_complete` — measured on the #2046 fixtures
+        // `dialog-{agent-list,session-list,timeline}.txt`.
+        //
+        // This has to be a GATE ahead of branch D and not a wider allowlist. A
+        // wider allowlist fixes only the missing NavigationButtons; the false
+        // completion is the `ready` itself, and `ready` is POSITIVE evidence, so
+        // the frame never reaches the unclassified path #1017 / #1494 built for
+        // unknown overlays. `claude`'s `/help` is the benign shape of the same
+        // thing — it lands on `running` / `default`, where the 60-second hatch
+        // opens; these landed on `ready`, where `commandmate wait` exits 0.
+        //
+        // The rule is the LAYOUT, never the heading: a background-painted rectangle
+        // whose rows share both edges and whose header carries opencode's own `esc`
+        // hatch right-aligned inside it. See `lib/detection/opencode-modal-overlay`
+        // for why a word list is not an option here (it is the inference #1883
+        // deleted) and for what a non-match does and does not mean.
+        //
+        // Ordered AFTER branches A0/A/B on purpose. A permission dialog, an `esc
+        // interrupt` footer and a spinner all already answer something that is not
+        // `ready`, and putting this first would only rename their verdicts.
+        //
+        // `frame.raw` rather than `frame.clean`: the rectangle is SGR, and every
+        // production caller of `detectSessionStatus` passes the `capture-pane -e`
+        // bytes (`lib/tmux/tmux.ts` always passes `-e`).
+        if ((0, opencode_modal_overlay_1.detectOpenCodeModalOverlay)(frame.raw) !== null) {
+            return {
+                status: 'waiting',
+                confidence: 'high',
+                reason: status_reason_1.STATUS_REASON.OPENCODE_MODAL_OVERLAY,
+                hasActivePrompt: false,
+                evidence: 'positive',
+            };
+        }
         // D. Check last few content lines for the finished-turn marker.
         //
         // Issue #1893 made the duration mandatory here (OPENCODE_TURN_COMPLETE_PATTERN

package/dist/server/src/lib/detection/tools/opencode/prompt.js

@@ -44,6 +44,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectOpenCodeDialog = detectOpenCodeDialog;
 const cli_patterns_1 = require("../../cli-patterns");
+const opencode_modal_overlay_1 = require("../../opencode-modal-overlay");
 /** Splits the button strip into its buttons: two or more spaces separate them. */
 const BUTTON_SEPARATOR = /\s{2,}/;
 /**
@@ -81,5 +82,24 @@ function detectOpenCodeDialog(frame, context) {
     if (cli_patterns_1.OPENCODE_SELECTION_LIST_PATTERN.test(context.contentWindow)) {
         return { kind: 'picker', options: [], answerMode: 'keys' };
     }
+    // Issue #2112: the five dialogs the allowlist above does not name — session
+    // list, agent list, timeline, command palette — recognised from the rectangle
+    // they are painted as. Reported here as well as in `detect.ts` branch C2 so
+    // this seam keeps the promise the branch-C comment makes: the dialog rule
+    // reports the dialog the status branch reports.
+    //
+    // `answerMode: 'keys'`, like every other opencode surface, for the reason the
+    // docblock above gives — a typed number is swallowed and the Enter after it
+    // confirms whatever is highlighted. `options` is empty because opencode draws
+    // no numbers to enumerate.
+    //
+    // On the Auto-Yes path this cannot match: that caller hands over a frame whose
+    // ANSI has already been removed (`captureAndCleanOutput`) and the rectangle IS
+    // the SGR. The gate outcome is identical either way — `null` and `keys` both
+    // mean "do not send" — which is the same trade the permission branch's gutter
+    // anchor makes two paragraphs up.
+    if ((0, opencode_modal_overlay_1.detectOpenCodeModalOverlay)(frame.raw) !== null) {
+        return { kind: 'picker', options: [], answerMode: 'keys' };
+    }
     return null;
 }

package/dist/server/src/lib/detection/tools/verified-against.js

@@ -45,10 +45,21 @@ exports.COPILOT_VERIFIED_AGAINST = {
     capturedAt: '2026-08-21',
     paneGeometry: '200x1000',
 };
-/** opencode these rules were read off (#1883 / #1893 / #1896 fixtures). */
+/**
+ * opencode these rules were read off (#1883 / #1893 / #1896 fixtures; re-measured
+ * against 1.18.22 by the canary in #2050).
+ *
+ * Bumped from 1.18.21 because the frames were RE-CAPTURED, not because the
+ * version number moved: `npm run canary -- --tool opencode` drove 1.18.22 into
+ * all five states branches A0-E read (idle composer / `esc interrupt` /
+ * `Allow once   Allow always   Reject` / `/models` picker / `▣ … · <duration>`)
+ * at the production 80x200 geometry and every rule answered as it did on
+ * 1.18.21. The frames are `tests/fixtures/canary/opencode-*.ts` and the run is
+ * written up in `docs/design/opencode-server-live-verification.md` §18.
+ */
 exports.OPENCODE_VERIFIED_AGAINST = {
-    version: '1.18.21',
-    capturedAt: '2026-08-21',
+    version: '1.18.22',
+    capturedAt: '2026-08-26',
     paneGeometry: '80x200',
 };
 /** agy these rules were read off (#988 / #995). */

package/dist/server/src/lib/detection/upstream-faults.js

@@ -29,6 +29,7 @@ exports.UPSTREAM_FAULT_TRUNCATION_MARKER = exports.UPSTREAM_FAULT_EXCERPT_MAX_BY
 exports.matchUpstreamFault = matchUpstreamFault;
 exports.findUpstreamFault = findUpstreamFault;
 const ansi_1 = require("./ansi");
+const excerpt_1 = require("./excerpt");
 /**
  * Patterns are anchored on ERROR wording, not on the words "usage limit".
  * Claude's own banner advertises "up to 50% of your weekly usage limit on
@@ -61,31 +62,15 @@ exports.UPSTREAM_FAULT_EXCERPT_MAX_BYTES = 200;
 /** Appended when {@link UPSTREAM_FAULT_EXCERPT_MAX_BYTES} cut the excerpt. */
 exports.UPSTREAM_FAULT_TRUNCATION_MARKER = '…[truncated]';
 /**
- * Truncate to a UTF-8 byte budget on a code-point boundary.
+ * Truncate to this module's UTF-8 byte budget.
  *
- * A local copy rather than `truncateToUtf8Bytes` from `lib/auto-yes-state`: that
- * module reaches the database and the Auto-Yes state machine, and this one is a
- * leaf the canary imports from outside Next. Accumulating code points (never
- * UTF-16 units) is what keeps a surrogate pair whole.
+ * The arithmetic moved to `./excerpt` when Issue #2095 published a second
+ * screen-read excerpt under the same rules; still not `truncateToUtf8Bytes`
+ * from `lib/auto-yes-state`, which reaches the database and the Auto-Yes state
+ * machine, because this module is a leaf the canary imports from outside Next.
  */
 function truncateExcerpt(text) {
-    const encoder = new TextEncoder();
-    if (encoder.encode(text).length <= exports.UPSTREAM_FAULT_EXCERPT_MAX_BYTES)
-        return text;
-    // The marker is inside the budget, not on top of it: the bound is a promise
-    // about the published field, and a caller sizing a log line by it must not be
-    // handed twelve more characters than it asked for.
-    const budget = exports.UPSTREAM_FAULT_EXCERPT_MAX_BYTES - encoder.encode(exports.UPSTREAM_FAULT_TRUNCATION_MARKER).length;
-    let bytes = 0;
-    let out = '';
-    for (const char of text) {
-        const size = encoder.encode(char).length;
-        if (bytes + size > budget)
-            break;
-        bytes += size;
-        out += char;
-    }
-    return `${out}${exports.UPSTREAM_FAULT_TRUNCATION_MARKER}`;
+    return (0, excerpt_1.truncateToByteBudget)(text, exports.UPSTREAM_FAULT_EXCERPT_MAX_BYTES, exports.UPSTREAM_FAULT_TRUNCATION_MARKER);
 }
 /**
  * The first upstream fault visible in the frame, with its line.

package/dist/server/src/lib/hooks/agent-session-telemetry.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * What the agent says about the conversation this instance is in (Issue #2040).
+ *
+ * `capture --json` could say what a session is *doing* — running, waiting, which
+ * dialog is open — and nothing at all about what it has *spent*. An orchestrator
+ * watching a fleet has to be able to answer "is this worker still worth its
+ * budget?" and "which model is it actually on?", and neither question is
+ * answerable from a terminal frame: the numbers exist only inside the agent.
+ *
+ * opencode publishes them. `session.updated` carries the whole `Session` object
+ * on the SSE stream CommandMate already subscribes to — measured against
+ * 1.18.22's own OpenAPI document (`GET /doc`): `Session` declares `title`,
+ * `agent`, `model: { id, providerID, variant? }`, `cost: number` and
+ * `tokens: { input, output, reasoning, cache: { read, write } }`. So this record
+ * costs no request: it is read off a frame that was already arriving and that
+ * mapped to none of the seven event words.
+ *
+ * ## Exposure only
+ *
+ * Nothing reads this back to decide anything — not `sessionStatus`, not
+ * Auto-Yes, not `wait`. It is published as `structuredEvents.session` and that
+ * is the whole contract, exactly like `./permission-decision-state` (#1898) and
+ * `./tool-input-normalization-state` (#1902). A number that steered a verdict
+ * would need a staleness policy this record deliberately does not have.
+ *
+ * ## Why the shape is not the agent's shape, in one respect
+ *
+ * The values are verbatim — nothing here rounds a cost, renames a model or
+ * totals a token count, for the reason `CurrentOutputPayload.model` states: a
+ * reader compares them against what the agent reports about itself, and any
+ * tidying on the way out breaks that comparison exactly when it matters. What
+ * IS changed is the nesting: `tokens.cache.read` is published as
+ * `tokens.cacheRead`, so a CLI contract has one optional level rather than two.
+ *
+ * ## Lifetime
+ *
+ * One record per (worktree, tool, instance), overwritten by every frame, and
+ * dropped when the subscription that fills it is closed — which is when the pane
+ * is killed. That is the honest bound: the record describes a conversation a
+ * process was having, so outliving the process would make it assert something
+ * false, the same argument `buildCurrentOutput` makes for blanking `model` on a
+ * session that is not running. {@link AgentSessionRecord.at} dates it for the
+ * window in between.
+ *
+ * The `globalThis` indirection is load-bearing for the reason it is everywhere
+ * else in this subsystem (#1736): the writer is the opencode subscription and
+ * the reader is `/api/worktrees/:id/current-output`, which `next dev` bundles
+ * separately and would otherwise give a private copy of this map each.
+ *
+ * ## What the record deliberately does not answer (Issue #2042)
+ *
+ * "How full is the context?" is not in here, and cannot be derived from what
+ * is: `Session.tokens` is **cumulative for the session** — measured over two
+ * turns it read `input 6 / output 11 / cache.read 8482 / cache.write 8500`,
+ * which is exactly what `opencode stats` prints — while opencode's own footer
+ * shows the **last assistant message's** footprint, 8,508. Summing the record
+ * would have answered 16,999 and `2%` where the agent says 8,508 and `1%`, and
+ * the gap grows with every turn. The second half of this file therefore asks the
+ * agent's server two further questions and keeps the arithmetic in a record of
+ * its own — see {@link AgentSessionContextUsage} and
+ * `docs/design/opencode-server-live-verification.md` §14.
+ *
+ * @module lib/hooks/agent-session-telemetry
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_AGENT_SESSION_NAME_LENGTH = exports.MAX_AGENT_SESSION_TITLE_LENGTH = void 0;
+exports.recordAgentSessionTelemetry = recordAgentSessionTelemetry;
+exports.getAgentSessionTelemetry = getAgentSessionTelemetry;
+exports.forgetAgentSessionTelemetry = forgetAgentSessionTelemetry;
+exports.resetAgentSessionTelemetry = resetAgentSessionTelemetry;
+exports.readOpencodeSessionFrame = readOpencodeSessionFrame;
+exports.agentSessionContextPercent = agentSessionContextPercent;
+exports.getAgentSessionContextUsage = getAgentSessionContextUsage;
+exports.recordAgentSessionContextUsage = recordAgentSessionContextUsage;
+exports.forgetAgentSessionContextUsage = forgetAgentSessionContextUsage;
+exports.resetAgentSessionContextUsage = resetAgentSessionContextUsage;
+exports.ensureAgentSessionContextUsage = ensureAgentSessionContextUsage;
+exports.refreshAgentSessionContextUsage = refreshAgentSessionContextUsage;
+const auto_yes_state_1 = require("../../lib/auto-yes-state");
+const client_1 = require("./sources/opencode/client");
+const ports_1 = require("./sources/opencode/ports");
+/**
+ * Longest session title kept.
+ *
+ * opencode titles a session after its first prompt, so this is prose the agent
+ * wrote and the payload is served over HTTP. Truncated rather than refused,
+ * unlike an id (#1932 DR4-001): nothing matches on a title, it is displayed, so
+ * a shortened one misinforms visibly instead of colliding silently.
+ */
+exports.MAX_AGENT_SESSION_TITLE_LENGTH = 200;
+/**
+ * Longest model / agent / provider name kept.
+ *
+ * Same rule as the title, a tighter bound: these are identifiers a provider
+ * chose (`claude-sonnet-4.6`, `github-copilot`, `build`), not sentences.
+ */
+exports.MAX_AGENT_SESSION_NAME_LENGTH = 120;
+/** compositeKey -> the most recent session description for that instance. */
+const records = globalThis.__agentSessionTelemetry ??
+    (globalThis.__agentSessionTelemetry = new Map());
+/** Record what the agent last said about this instance's session. */
+function recordAgentSessionTelemetry(target, record) {
+    records.set((0, auto_yes_state_1.buildCompositeKey)(target.worktreeId, target.cliToolId, target.instanceId), record);
+}
+/**
+ * @returns What the agent last said, or null — the ordinary answer for every
+ *   tool that publishes none, and for an opencode pane whose stream has not
+ *   reported a session yet.
+ */
+function getAgentSessionTelemetry(worktreeId, cliToolId, instanceId) {
+    return records.get((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId)) ?? null;
+}
+/**
+ * Drop one instance's record. Called when its subscription closes.
+ *
+ * Issue #2042 hangs the derived context measurement off the same call rather
+ * than off a second one at the call site: the measurement describes the record,
+ * so a lifetime it did not share would leave a pane reporting "87% full" about a
+ * conversation that ended.
+ */
+function forgetAgentSessionTelemetry(target) {
+    records.delete((0, auto_yes_state_1.buildCompositeKey)(target.worktreeId, target.cliToolId, target.instanceId));
+    forgetAgentSessionContextUsage(target);
+}
+/** Drop every record. Test seam. */
+function resetAgentSessionTelemetry() {
+    records.clear();
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** A bounded string, or null when the field is absent or not a string. */
+function readBoundedString(source, key, max) {
+    const value = source[key];
+    if (typeof value !== 'string' || value.length === 0)
+        return null;
+    return value.slice(0, max);
+}
+/**
+ * A finite number, or null.
+ *
+ * `Number.isFinite` rather than `typeof === 'number'`: `NaN` and `Infinity` are
+ * numbers that survive `JSON.parse` and would reach `capture --json` as `null`
+ * anyway (`JSON.stringify(NaN)` is `null`), so admitting them would publish a
+ * null that means "the agent said NaN" next to a null that means "the agent said
+ * nothing", with no way to tell them apart.
+ */
+function readFiniteNumber(source, key) {
+    const value = source[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/** The empty usage, for a session that has reported no counts. */
+function noTokenUsage() {
+    return { input: null, output: null, reasoning: null, cacheRead: null, cacheWrite: null, total: null };
+}
+function readTokenUsage(info) {
+    const tokens = isPlainObject(info.tokens) ? info.tokens : null;
+    if (!tokens)
+        return noTokenUsage();
+    const cache = isPlainObject(tokens.cache) ? tokens.cache : {};
+    return {
+        input: readFiniteNumber(tokens, 'input'),
+        output: readFiniteNumber(tokens, 'output'),
+        reasoning: readFiniteNumber(tokens, 'reasoning'),
+        cacheRead: readFiniteNumber(cache, 'read'),
+        cacheWrite: readFiniteNumber(cache, 'write'),
+        total: readFiniteNumber(tokens, 'total'),
+    };
+}
+/**
+ * Read a `session.updated` frame, or answer null (Issue #2040).
+ *
+ * ## Why a sub-agent's session is refused
+ *
+ * `Session.parentID` is present only on a session opencode opened *inside*
+ * another one (a `task` tool call), and its cost is the sub-agent's rather than
+ * the pane's. Recording it would make `structuredEvents.session` flip between
+ * the conversation the operator is having and a background job that is about to
+ * end, on a field whose whole purpose is to be compared over time. The gate is
+ * frame-local on purpose — `./sources/opencode/turn-gate` learns parentage from
+ * the same field, and a second reader of one fact is cheaper than a dependency
+ * between the two.
+ *
+ * @param frame - The raw `{ type, properties }` frame off the stream
+ * @param at - Epoch ms the frame was received
+ * @returns The record to store, or null when this frame is not one to store
+ */
+function readOpencodeSessionFrame(frame, at) {
+    const properties = isPlainObject(frame.properties) ? frame.properties : null;
+    if (!properties)
+        return null;
+    const info = isPlainObject(properties.info) ? properties.info : null;
+    if (!info)
+        return null;
+    if (typeof info.parentID === 'string' && info.parentID.length > 0)
+        return null;
+    const model = isPlainObject(info.model) ? info.model : {};
+    return {
+        id: readBoundedString(info, 'id', exports.MAX_AGENT_SESSION_NAME_LENGTH),
+        title: readBoundedString(info, 'title', exports.MAX_AGENT_SESSION_TITLE_LENGTH),
+        agent: readBoundedString(info, 'agent', exports.MAX_AGENT_SESSION_NAME_LENGTH),
+        model: readBoundedString(model, 'id', exports.MAX_AGENT_SESSION_NAME_LENGTH),
+        provider: readBoundedString(model, 'providerID', exports.MAX_AGENT_SESSION_NAME_LENGTH),
+        cost: readFiniteNumber(info, 'cost'),
+        tokens: readTokenUsage(info),
+        at,
+    };
+}
+/** compositeKey -> the last context occupancy measured for that instance. */
+const contextUsages = globalThis.__agentSessionContextUsage ??
+    (globalThis.__agentSessionContextUsage = new Map());
+/** compositeKeys with a refresh in flight, so a poll storm makes one request. */
+const contextRefreshes = globalThis.__agentSessionContextRefreshes ??
+    (globalThis.__agentSessionContextRefreshes = new Set());
+/**
+ * The percentage opencode's own footer shows, by opencode's own rule.
+ *
+ * `Math.round(tokens / limit * 100)`, transcribed from the 1.18.22 bundle
+ * (`docs/design/opencode-server-live-verification.md` §14.2) rather than
+ * guessed, because the alternatives are all plausible and all wrong: the
+ * denominator is `limit.context` and not `limit.input` (1,000,000 not 936,000 on
+ * the measured model), and the rounding is `round` and not `ceil`, so a session
+ * holding less than half a percent reads `0%` rather than `1%`.
+ *
+ * @returns The whole-number percentage, or null when either input is unknown
+ */
+function agentSessionContextPercent(tokens, limit) {
+    if (tokens === null || limit === null)
+        return null;
+    if (!Number.isFinite(tokens) || !Number.isFinite(limit) || limit <= 0)
+        return null;
+    return Math.round((tokens / limit) * 100);
+}
+/** What this instance's context last measured, or null. Synchronous. */
+function getAgentSessionContextUsage(worktreeId, cliToolId, instanceId) {
+    return contextUsages.get((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId)) ?? null;
+}
+/** Store one measurement. Exported for the suites that stand in for the fetch. */
+function recordAgentSessionContextUsage(target, usage) {
+    contextUsages.set((0, auto_yes_state_1.buildCompositeKey)(target.worktreeId, target.cliToolId, target.instanceId), usage);
+}
+/** Drop one instance's measurement. */
+function forgetAgentSessionContextUsage(target) {
+    contextUsages.delete((0, auto_yes_state_1.buildCompositeKey)(target.worktreeId, target.cliToolId, target.instanceId));
+}
+/** Drop every measurement and every in-flight marker. Test seam. */
+function resetAgentSessionContextUsage() {
+    contextUsages.clear();
+    contextRefreshes.clear();
+}
+/**
+ * Answer with what is cached, and start a refresh when it is stale (#2042).
+ *
+ * **Never awaits and never throws**, which is the whole shape of it. The caller
+ * is `buildCurrentOutput`, on the path `commandmate capture` and every terminal
+ * pane poll take several times a second, and the two numbers here need two HTTP
+ * round trips to an agent's own server. Awaiting them would put a foreign
+ * process's latency in front of a payload that is mostly a terminal frame; so
+ * the poll that notices the record moved answers `null` (or the previous turn's
+ * numbers) and the next one, a second or two later, answers the new ones.
+ *
+ * Staleness is `record.at`, not a clock: `session.updated` fires a handful of
+ * times per turn, so a refresh happens per *turn* rather than per poll, and a
+ * session nobody is talking to makes no requests at all.
+ *
+ * @param target - The instance whose context is being described
+ * @param record - Its current telemetry, or null when the agent has said nothing
+ * @returns The cached measurement, or null when there is none yet
+ */
+function ensureAgentSessionContextUsage(target, record) {
+    const key = (0, auto_yes_state_1.buildCompositeKey)(target.worktreeId, target.cliToolId, target.instanceId);
+    const cached = contextUsages.get(key) ?? null;
+    // No session, or one the agent has not named: nothing to ask about. The
+    // cached value is left in place rather than cleared — the subscription's
+    // close is what retires it, the same lifetime the record itself has.
+    if (!record || !record.id)
+        return cached;
+    if (cached && cached.sessionAt === record.at)
+        return cached;
+    if (contextRefreshes.has(key))
+        return cached;
+    contextRefreshes.add(key);
+    void refreshAgentSessionContextUsage(target, record).finally(() => {
+        contextRefreshes.delete(key);
+    });
+    return cached;
+}
+/**
+ * Ask the instance's own server the two questions and store the answer.
+ *
+ * Exported so a caller that *can* wait — a test, or a future CLI path — can,
+ * and so the fire-and-forget above has a name to point at. Resolves to the
+ * measurement it stored, or null when the instance has no reachable server:
+ * `getAssignedOpencodePort` answers null for every tool but opencode and for an
+ * opencode pane whose port was never written down.
+ */
+async function refreshAgentSessionContextUsage(target, record) {
+    const sessionId = record.id;
+    if (!sessionId)
+        return null;
+    const port = (0, ports_1.getAssignedOpencodePort)(target);
+    if (port === null)
+        return null;
+    const [tokens, limit] = await Promise.all([
+        (0, client_1.fetchOpencodeContextTokens)(port, sessionId),
+        record.provider && record.model
+            ? (0, client_1.fetchOpencodeModelContextLimit)(port, record.provider, record.model)
+            : Promise.resolve(null),
+    ]);
+    // Both null means the two calls found nothing to say — a fresh session and an
+    // unrecognised model. Stored anyway, with `sessionAt` set: the point of the
+    // record is to stop this pair of requests repeating every poll, and a null
+    // that is dated is what says "asked, and the answer was nothing".
+    const usage = {
+        tokens,
+        limit,
+        percent: agentSessionContextPercent(tokens, limit),
+        sessionAt: record.at,
+        at: Date.now(),
+    };
+    recordAgentSessionContextUsage(target, usage);
+    return usage;
+}

package/dist/server/src/lib/hooks/pending-decision-kind.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Telling an approval from a question in the *retained* dialog record
+ * (Issue #2040).
+ *
+ * `AgentEventSource.listPending()` answers with a `PendingDecision`, which
+ * carries `kind: 'permission' | 'question'` because the source read it off the
+ * agent's own payload. `structuredEvents.pendingDecisions` does not come from
+ * there: it comes from `agent-event-state`'s retained record, which is written
+ * from hook events and from the opencode ingest and has never carried a kind.
+ * A reader of `capture --json` therefore could not tell "this worker is blocked
+ * on `rm -rf`" from "this worker is being asked which colour" — two situations
+ * an orchestrator answers completely differently.
+ *
+ * The kind is not stored, it is **recovered**, and this module is the one place
+ * that says how. Both writers already mark the record: a question opens it with
+ * a tool name of its own, and the two names below are the two markers in use.
+ * Naming them here rather than repeating the strings is what keeps the writer
+ * and the reader from drifting apart — {@link OPENCODE_QUESTION_TOOL_NAME} is
+ * imported by `./sources/opencode/ingest`, which is what writes it.
+ *
+ * ## Why this is a derivation and not a new field
+ *
+ * Adding `kind` to `StructuredPendingDecision` would be the direct fix, and it
+ * is the right one eventually. It is not this Issue's: the record is written on
+ * five paths across `agent-event-state` and `permission-decision-service`, and a
+ * field that four of them leave undefined is a field whose absence has to be
+ * interpreted anyway. Deriving it from what the writers already record has the
+ * same answer today and no half-filled column tomorrow.
+ *
+ * @module lib/hooks/pending-decision-kind
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUESTION_DECISION_TOOL_NAMES = exports.OPENCODE_QUESTION_TOOL_NAME = void 0;
+exports.pendingDecisionKind = pendingDecisionKind;
+const permission_request_payload_1 = require("./permission-request-payload");
+/**
+ * The tool name the opencode ingest opens a `question.asked` record under.
+ *
+ * Not a tool at all — opencode's question is a first-class event rather than a
+ * tool call, so there is no name to copy and this word is the marker CommandMate
+ * chose. Exported so the writer and this reader cannot disagree about it.
+ */
+exports.OPENCODE_QUESTION_TOOL_NAME = 'question';
+/**
+ * The tool names that mean "a human is being asked to choose", not "a human is
+ * being asked to approve".
+ *
+ * Claude's is a real tool (`AskUserQuestion`, which raises a `PermissionRequest`
+ * that is never allowed — allowing it does not dismiss the picker); opencode's
+ * is the marker above.
+ */
+exports.QUESTION_DECISION_TOOL_NAMES = [
+    permission_request_payload_1.ASK_USER_QUESTION_TOOL,
+    exports.OPENCODE_QUESTION_TOOL_NAME,
+];
+/**
+ * Recover the kind of one retained dialog record.
+ *
+ * `'permission'` is the default rather than a third "unknown" value, and that
+ * asymmetry is deliberate: a record with no tool name is a `PermissionRequest`
+ * this server declined to decide — the overwhelmingly common case — and a reader
+ * that has to handle a third value would end up defaulting it to the same thing
+ * with less information about why.
+ *
+ * @param toolName - `StructuredPendingDecision.toolName`, as retained
+ */
+function pendingDecisionKind(toolName) {
+    return toolName !== null && exports.QUESTION_DECISION_TOOL_NAMES.includes(toolName)
+        ? 'question'
+        : 'permission';
+}