commandmate 0.26.0 → 0.27.0

package/dist/server/src/lib/tui-accumulator.js

@@ -97,9 +97,76 @@ function normalizeCopilotLine(line) {
  */
 function extractCopilotContentLines(rawOutput) {
     const strippedOutput = (0, cli_patterns_1.stripAnsi)(rawOutput);
-    const lines = strippedOutput.split('\n');
+    const allLines = strippedOutput.split('\n');
+    // Issue #1895, and it must run BEFORE the #1897 chrome trim below, against
+    // `allLines`. The two checks are complementary, not alternatives, and the
+    // order is forced in BOTH directions — measured over the 16 live fixtures:
+    //
+    //  - Trim-then-ask MISSES the real picker. `/model` draws its search field as
+    //    rule / `❯  Search models…` / rule with the key-hint footer where the
+    //    status bar would be, which is structurally a composer, so
+    //    `findCopilotChromeStart` accepts it (996, six rows off the end) instead
+    //    of returning -1 — and the six rows it takes are the only evidence that
+    //    this frame is a picker. 112 non-blank rows of model list stay behind and
+    //    `isCopilotSelectionFrame` on what is left answers no. (The other ten
+    //    pickers do give -1, so for them the order is merely harmless.)
+    //  - Trim-then-ask also INVENTS a picker. On
+    //    `picker-vocabulary-in-response.txt` — a finished turn whose reply quotes
+    //    two key-hint bars — the trim removes the status bar, which is exactly the
+    //    guard `isCopilotSelectionFrame` leans on, and the quoted bars are then the
+    //    bottom rows. Asked after the trim it answers yes and the whole reply is
+    //    discarded. Asked before, it answers no and the 54 rows survive.
+    //
+    // While a picker is open the frame carries NO response content at all: copilot
+    // draws the list instead of the transcript. The poller feeds this function the
+    // whole pane on every tick (`response-checker.ts`), so an operator who opens
+    // `/model` and reads it for a minute would otherwise have the model list
+    // appended to the saved response once per poll. Line patterns cannot fix that:
+    // `Recommended models` and `GPT-5.6 Luna 328K Medium` are not distinguishable
+    // from prose, and the pattern that used to sit in `COPILOT_SKIP_PATTERNS` for
+    // this (`Search \w+\.\.\.|Select Model`) matched none of the chrome and DID
+    // match copilot's own answers about the picker. The frame-level question has an
+    // exact answer, so ask that instead.
+    //
+    // Returning [] leaves the accumulator untouched (`accumulateTuiContent`
+    // early-returns on empty), which is the wanted behaviour: the picker is a
+    // transient overlay over a transcript whose earlier polls are already
+    // accumulated, and the next poll after it closes resumes normally.
+    if ((0, cli_patterns_1.isCopilotSelectionFrame)(allLines))
+        return [];
+    // Issue #1897: this accumulator, not extractResponse(), is what actually feeds
+    // cleanCopilotResponse() in checkForResponse(), so copilot's bottom-pinned
+    // chrome has to be cut HERE or the status bar joins the transcript on every
+    // poll and is saved as the agent's reply (" Working esc interrupt GPT-5.6
+    // Terra"). Cut positionally: copilot prints its own status-bar vocabulary as
+    // body text when asked to, so no wording rule can tell the two apart.
+    const chromeStart = (0, cli_patterns_1.findCopilotChromeStart)(allLines);
+    const lines = chromeStart >= 0 ? allLines.slice(0, chromeStart) : allLines;
     const contentLines = [];
+    // Issue #1897: copilot wraps a long prompt echo onto indented continuation rows.
+    // Normalisation trims them, so downstream they are indistinguishable from reply
+    // text and `cleanCopilotResponse`'s "everything after the last ❯" rule opened
+    // the saved reply with the tail of the operator's own question. The echo row
+    // itself is kept — it is the turn boundary the cleaner anchors on.
+    let inUserEcho = false;
     for (const line of lines) {
+        // Issue #1897: tested before normalisation. normalizeCopilotLine() deletes
+        // every U+2500..U+257F glyph, so COPILOT_SKIP_PATTERNS' `[╭╮╰╯│]` rule can
+        // never fire below -- which is how copilot's reasoning block (rows of
+        // `│ <chain of thought>` under a `⌄ Thought for 41s` header) reached History
+        // as the reply.
+        if (cli_patterns_1.COPILOT_BOX_ROW_PATTERN.test(line)) {
+            inUserEcho = false;
+            continue;
+        }
+        if (cli_patterns_1.COPILOT_USER_ECHO_PATTERN.test(line)) {
+            inUserEcho = true;
+        }
+        else if (inUserEcho) {
+            if (cli_patterns_1.COPILOT_TRANSCRIPT_CONTINUATION_PATTERN.test(line))
+                continue;
+            inUserEcho = false;
+        }
         const normalized = normalizeCopilotLine(line);
         if (!normalized)
             continue;

package/dist/server/src/lib/verification/gate-runner.js

@@ -35,6 +35,10 @@ const db_1 = require("../../lib/db");
 const tasks_db_1 = require("../../lib/db/tasks-db");
 const git_default_branch_1 = require("../../lib/git/git-default-branch");
 const logger_1 = require("../../lib/logger");
+// Issue #2000: deep path, not the `@/lib/push` barrel — several suites replace
+// that barrel with a stub declaring only `notifyPushSubscribers`, and a call
+// reached through it would be `undefined` in exactly those tests.
+const failure_push_notifier_1 = require("../../lib/push/failure-push-notifier");
 const contract_message_1 = require("../../lib/tasks/contract-message");
 const task_transition_service_1 = require("../../lib/tasks/task-transition-service");
 const env_clean_gate_1 = require("./env-clean-gate");
@@ -264,6 +268,42 @@ class TailBuffer {
         return this.chunks.length === 0 ? '' : Buffer.concat(this.chunks).toString('utf8');
     }
 }
+/**
+ * The environment a gate command runs in (Issue #1994).
+ *
+ * A gate is a re-run of the repository's CI check, so what it must inherit is
+ * CI's shape — not the shape of whatever process happens to be hosting the
+ * runner. `CI=true` was already normalized for that reason; `NODE_ENV` is the
+ * variable where the omission bit.
+ *
+ * Gates are spawned by the CommandMate **server**, and the server has a
+ * NODE_ENV of its own — `production` under `commandmate start`, `development`
+ * under `commandmate start --dev` and `npm run dev`. A gate that shells out to
+ * a framework build reads it. Measured on this branch: `npm run build`
+ * (Next.js 15) exits 0 with NODE_ENV unset and **exits 1 with
+ * NODE_ENV=development**, on `<Html> should not be imported outside of
+ * pages/_document` while prerendering `/404`, `/500` and `/offline`. A `build`
+ * gate would therefore have been red for every worker on every run whenever an
+ * operator had started the server with `--dev`: a verdict about the host,
+ * reported as a verdict about the diff.
+ *
+ * GitHub Actions leaves NODE_ENV unset, so dropping it is precisely what makes
+ * the gate match CI. A command that needs one says so itself, as this
+ * repository's scripts already do (`NODE_ENV=test vitest run`,
+ * `NODE_ENV=production next build`).
+ */
+function gateProcessEnv(gateEnv) {
+    const env = { ...process.env, CI: 'true', ...gateEnv };
+    // Removed rather than set to `undefined`: an explicitly-undefined key can
+    // still reach the child as an empty string, and `NODE_ENV=` is not the same
+    // thing as "unset".
+    delete env.NODE_ENV;
+    // `next/types/global.d.ts` augments NodeJS.ProcessEnv with a *required*
+    // readonly NODE_ENV, so the absence this function exists to produce cannot be
+    // expressed in that type. The runtime contract `spawn` uses is a plain string
+    // map, which is what is built above.
+    return env;
+}
 /**
  * Run one shell command and report its exit code.
  *
@@ -286,7 +326,7 @@ function runCommand(command, cwd, timeoutSec, maxLogTailBytes, gateEnv) {
             // a different fileParallelism otherwise, and a gate that passes here but
             // fails in CI is worse than no gate. `gateEnv` carries the per-worktree
             // identity (#1771) and is code-supplied, never user input.
-            env: { ...process.env, CI: 'true', ...gateEnv },
+            env: gateProcessEnv(gateEnv),
             detached: true,
             stdio: ['ignore', 'pipe', 'pipe'],
         });
@@ -939,6 +979,40 @@ function findDetachedContract(db, input, task) {
         return null;
     return latest.contract.success.requireScopeClean ? latest : null;
 }
+/**
+ * Tell the operator's phone that a run did not pass (Issue #2000).
+ *
+ * Called from both terminal paths — the synchronous config failure and the
+ * executed run — because both leave the caller with no verdict and something to
+ * fix. Whether it actually notifies (a contract run does not) and how it is
+ * logged belongs to `push/failure-push-notifier`; this wrapper exists only to
+ * gather the failing gate ids and to guarantee that a broken notifier cannot
+ * take a verification run down with it.
+ *
+ * Fire-and-forget: the run's verdict is already recorded and the caller is
+ * waiting on it.
+ */
+function notifyRunFailure(db, input, runId, taskId, status) {
+    let failedGateIds;
+    try {
+        failedGateIds = (0, db_1.getVerificationRun)(db, runId)
+            ?.gates.filter((gate) => gate.status !== 'passed' && gate.status !== 'skipped')
+            .map((gate) => gate.gateId);
+    }
+    catch {
+        // The row is gone (worktree deleted mid-run). The notification is still
+        // worth sending; it just cannot name the gates.
+    }
+    void (0, failure_push_notifier_1.notifyVerificationFailurePush)({
+        worktreeId: input.worktreeId,
+        runId,
+        taskId,
+        status,
+        trigger: input.trigger,
+        instanceId: input.instanceId ?? null,
+        failedGateIds,
+    }).catch(() => { });
+}
 /**
  * Open a verification run and execute it in the background.
  *
@@ -1036,6 +1110,10 @@ async function startVerification(input) {
         });
         (0, db_1.finishVerificationRun)(db, run.id, 'error');
         logger.warn('verification-config-unusable', { runId: run.id, worktreeId: input.worktreeId });
+        // Issue #2000: an unusable config leaves the verdict as absent as a red
+        // gate does, and the operator's next move is the same — so this path
+        // notifies too, subject to the same contract-task exclusion.
+        notifyRunFailure(db, input, run.id, taskId, 'error');
         if (trackedTask) {
             // The run opened and immediately errored, so the task passes through
             // `verifying` the same way it would for gates that ran: an unusable config
@@ -1086,6 +1164,11 @@ async function startVerification(input) {
             if (trackedTask) {
                 recordTaskTransition(db, trackedTask.id, taskEventForRunStatus(terminalStatus), run.id);
             }
+            // Issue #2000. In the `finally` so a crashed run (which is recorded as
+            // `error` in the catch above) notifies exactly like a judged one, and
+            // after the task transition so the run's own history is complete before
+            // anything is said about it.
+            notifyRunFailure(db, input, run.id, taskId, terminalStatus);
             releaseSlot();
             inFlight.delete(run.id);
         }

package/dist/server/src/lib/ws-server.js

@@ -19,7 +19,12 @@ const net_1 = require("net");
 const auth_1 = require("./security/auth");
 const ip_restriction_1 = require("./security/ip-restriction");
 const types_1 = require("./cli-tools/types");
-const manager_1 = require("./cli-tools/manager");
+// Issue #1984: `CLIToolManager` ではなくセッション名の規則だけを引く。ここで欲しいのは
+// `getTool(id).getSessionName(...)` の戻り値 1 つで、7 ツールの実装は module load 時には
+// 1 つも要らない。manager 経由の静的 import は
+// `ws-server -> cli-tools/manager -> polling/response-poller -> ... -> ws-server` という
+// モジュールスコープの循環の一辺でもあった。
+const session_name_1 = require("./cli-tools/session-name");
 const db_instance_1 = require("./db/db-instance");
 const db_1 = require("./db");
 const tmux_control_mode_metrics_1 = require("./tmux/tmux-control-mode-metrics");
@@ -588,8 +593,7 @@ async function handleTerminalSubscribe(ws, message) {
         await clientInfo.terminalSubscription.unsubscribe();
         clientInfo.terminalSubscription = null;
     }
-    const cliTool = manager_1.CLIToolManager.getInstance().getTool(cliToolId);
-    const sessionName = cliTool.getSessionName(worktreeId);
+    const sessionName = (0, session_name_1.resolveSessionName)(cliToolId, worktreeId);
     const transport = (0, control_mode_tmux_transport_1.getControlModeTmuxTransport)();
     if (transport.getSubscriberCount(sessionName) >= MAX_TERMINAL_SUBSCRIBERS_PER_SESSION) {
         sendTerminalEvent(ws, {
@@ -837,8 +841,7 @@ function migrateWorktreeRooms(renames) {
         try {
             if (!(0, types_1.isCliToolType)(subscription.cliToolId))
                 continue;
-            const cliTool = manager_1.CLIToolManager.getInstance().getTool(subscription.cliToolId);
-            subscription.sessionName = cliTool.getSessionName(newId);
+            subscription.sessionName = (0, session_name_1.resolveSessionName)(subscription.cliToolId, newId);
             subscription.worktreeId = newId;
         }
         catch (error) {

package/dist/server/src/types/cli-tool-contracts.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * The vocabulary an `ICLITool` uses to describe its own TUI (Issue #1933).
+ *
+ * 設計方針書 §4 D4 / §6.3 / §10.12 / §13.2. Three questions used to be answered
+ * by tables keyed on `CLIToolType` scattered outside the tool classes — "where
+ * is this tool's composer?", "how does it quit?", "how many rows must a status
+ * capture ask for?" — and each table had to be found and edited by anybody
+ * adding a tool. They are declarations now, and a tool answers its own.
+ *
+ * This module lives in `src/types/**` for the same reason `./terminal-keys`
+ * does: `src/lib/tmux/**` and `src/lib/cli-tools/**` both need the vocabulary,
+ * and putting it in either one would make the other import across a boundary
+ * `.eslintrc.json`'s `no-restricted-imports` rule exists to keep closed. Values
+ * and types only — nothing here touches a process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GRACEFUL_EXIT_FAILURE_REASONS = exports.KEY_SEQUENCE_KEY_NAMES = void 0;
+exports.keyStep = keyStep;
+exports.literalStep = literalStep;
+exports.isLiteralStep = isLiteralStep;
+exports.isKeyStep = isKeyStep;
+exports.isKeySequenceKeyName = isKeySequenceKeyName;
+// ---------------------------------------------------------------------------
+// Key sequences (受入条件 S9)
+// ---------------------------------------------------------------------------
+/**
+ * The key names a {@link KeySequence} step may name.
+ *
+ * Deliberately the same five values as `SPECIAL_KEY_VALUES` in
+ * `src/lib/tmux/tmux.ts` — `tests/unit/lib/key-sequence-1933.test.ts` pins the
+ * two lists equal. The list is duplicated rather than imported because this
+ * module must stay free of `src/lib/tmux/**` (see the module docblock); the
+ * pin is what keeps the duplication from drifting.
+ */
+exports.KEY_SEQUENCE_KEY_NAMES = ['Escape', 'C-c', 'C-d', 'C-m', 'Enter'];
+/** Build a key step. */
+function keyStep(name, delayAfterMs) {
+    return delayAfterMs === undefined ? { kind: 'key', name } : { kind: 'key', name, delayAfterMs };
+}
+/** Build a literal-text step. Text is always sent verbatim, never as a key. */
+function literalStep(text, delayAfterMs) {
+    return delayAfterMs === undefined
+        ? { kind: 'literal', text }
+        : { kind: 'literal', text, delayAfterMs };
+}
+/** Whether a step sends text rather than a key. */
+function isLiteralStep(step) {
+    return step.kind === 'literal';
+}
+/** Whether a step sends a named key rather than text. */
+function isKeyStep(step) {
+    return step.kind === 'key';
+}
+/**
+ * Whether `name` is a key name a {@link KeySequence} step may carry.
+ *
+ * Defense in depth against a JavaScript caller or an `as` cast: the executor
+ * refuses anything else rather than handing an unvalidated string to tmux.
+ */
+function isKeySequenceKeyName(name) {
+    return exports.KEY_SEQUENCE_KEY_NAMES.includes(name);
+}
+/**
+ * Why a graceful exit's postcondition was not met.
+ *
+ *   `graceful_exit_timeout` - the tmux session still existed after the tool's
+ *      own exit window. The TUI did not quit; the pane must be force-killed.
+ *   `port_orphaned` - the pane is gone but the port it was allocated is still
+ *      answering `/global/health` as opencode. Handing that number to the next
+ *      instance makes two owners of one port: the new instance's subscription
+ *      attaches to the old server and files its events against the wrong
+ *      worktree, silently. The number must not be reused until it goes quiet.
+ */
+exports.GRACEFUL_EXIT_FAILURE_REASONS = ['graceful_exit_timeout', 'port_orphaned'];

package/dist/server/src/types/terminal-keys.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Terminal navigation key vocabulary (Issue #1922).
+ *
+ * This lives outside `src/lib/tmux/**` on purpose. `NavigationKey` is the one
+ * tmux-adjacent symbol the browser bundle needs (`NavigationButtons.tsx` /
+ * `TerminalEscapeHatch.tsx` type their key props with it), and as long as it was
+ * declared in `src/lib/tmux/tmux.ts` those two client components had to import
+ * from the tmux module to get it — a client → tmux dependency edge that the
+ * `no-restricted-imports` guard added for §4 D4 of
+ * `docs/design/multi-agent-state-architecture.md` exists to remove.
+ *
+ * The alternative considered and rejected (D4, DR3-001) was switching the guard
+ * to `@typescript-eslint/no-restricted-imports` with `allowTypeImports: true`.
+ * That would permanently bless the edge and leave a path where deleting the word
+ * `type` from an import turns a compile-time reference into a runtime one. Moving
+ * the declaration costs one file and closes the edge outright.
+ *
+ * Values only — no tmux process access — so this module is safe from any layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAVIGATION_KEY_VALUES = void 0;
+/**
+ * Navigation keys accepted by the special-keys API and the terminal UI.
+ *
+ * Separate from `SPECIAL_KEY_VALUES` (the `sendSpecialKey()` control keys) and
+ * from `ALLOWED_SPECIAL_KEYS` (the broader `sendSpecialKeys()` TUI set).
+ *
+ * [DR3-001] Named NAVIGATION_KEY_VALUES to avoid collision with existing SPECIAL_KEY_VALUES.
+ * [DR2-004] Exported as an `as const` array + type guard (not a Set) for immutability.
+ */
+exports.NAVIGATION_KEY_VALUES = [
+    'Up', 'Down', 'Left', 'Right', 'Enter', 'Escape', 'Tab', 'BTab',
+    // Issue #1017: Codex pager / edit-previous mode keys surfaced by NavigationButtons.
+    // 'q' is the pager quit key (literal char). PageUp/PageDown/Home/End are tmux named keys.
+    'PageUp', 'PageDown', 'Home', 'End', 'q',
+];

package/dist/types/cli-tool-contracts.d.ts

@@ -0,0 +1,235 @@
+/**
+ * The vocabulary an `ICLITool` uses to describe its own TUI (Issue #1933).
+ *
+ * 設計方針書 §4 D4 / §6.3 / §10.12 / §13.2. Three questions used to be answered
+ * by tables keyed on `CLIToolType` scattered outside the tool classes — "where
+ * is this tool's composer?", "how does it quit?", "how many rows must a status
+ * capture ask for?" — and each table had to be found and edited by anybody
+ * adding a tool. They are declarations now, and a tool answers its own.
+ *
+ * This module lives in `src/types/**` for the same reason `./terminal-keys`
+ * does: `src/lib/tmux/**` and `src/lib/cli-tools/**` both need the vocabulary,
+ * and putting it in either one would make the other import across a boundary
+ * `.eslintrc.json`'s `no-restricted-imports` rule exists to keep closed. Values
+ * and types only — nothing here touches a process.
+ */
+/**
+ * The key names a {@link KeySequence} step may name.
+ *
+ * Deliberately the same five values as `SPECIAL_KEY_VALUES` in
+ * `src/lib/tmux/tmux.ts` — `tests/unit/lib/key-sequence-1933.test.ts` pins the
+ * two lists equal. The list is duplicated rather than imported because this
+ * module must stay free of `src/lib/tmux/**` (see the module docblock); the
+ * pin is what keeps the duplication from drifting.
+ */
+export declare const KEY_SEQUENCE_KEY_NAMES: readonly ["Escape", "C-c", "C-d", "C-m", "Enter"];
+/** A tmux key name a {@link KeySequence} step may send. */
+export type KeySequenceKeyName = typeof KEY_SEQUENCE_KEY_NAMES[number];
+/**
+ * One step of a keystroke sequence — a *key*, or *text*.
+ *
+ * ## Why this is a discriminated union and not a string
+ *
+ * `tmux send-keys` looks its argument up in the key table before it sends
+ * anything, so the SAME string means two different things depending on a flag
+ * nobody was passing. Measured on tmux 3.5a against a private socket, with a
+ * pane running `cat` on a raw pty so the bytes are the bytes the TUI receives:
+ *
+ * ```
+ * send-keys -t X    'Escape'   -> 1b                    (the ESC key)
+ * send-keys -t X -l 'Escape'   -> 45 73 63 61 70 65     ("Escape")
+ * send-keys -t X    'Enter'    -> 0d                    (CR)
+ * send-keys -t X -l 'Enter'    -> 45 6e 74 65 72        ("Enter")
+ * ```
+ *
+ * `grep -n "'-l'" src/lib/tmux/*.ts` returned **zero** hits before this Issue,
+ * and `sendMessageWithSubmitVerification` types the user's message body with
+ * `sendKeys(sessionName, message, false)`. So a message whose body was exactly
+ * `Escape` interrupted the agent instead of being typed, `Enter` submitted an
+ * empty composer, and `C-c` sent SIGINT — none of which produced an error, or
+ * even a differing log line.
+ *
+ * The same probe found a second, worse shape. tmux parses its arguments with
+ * getopt, and the body is positional:
+ *
+ * ```
+ * send-keys -t X '-l'         -> rc 0, NOTHING sent   (parsed as the -l flag)
+ * send-keys -t X '-N hello'   -> rc 1, "repeat count invalid"
+ * send-keys -t X -l -- '-l'   -> 2d 6c                ("-l")
+ * ```
+ *
+ * i.e. a body starting with `-` was silently swallowed and reported as a
+ * successful send. Both halves are why a literal step must reach tmux as
+ * `send-keys -l -- <text>` and a key step as `send-keys -- <name>`; see
+ * `keySequenceArgs` in `src/lib/tmux/key-sequence.ts`, which is the only place
+ * that mapping is written.
+ *
+ * `delayAfterMs` is optional and carries what a sequence's own measurements
+ * say has to elapse before the next step (opencode's 100 ms between `/exit`
+ * and its Enter, gemini's 300 ms after `C-c`). It is metadata about the step,
+ * not a third member of the union: every step is still a key or a literal.
+ */
+export type KeySequence = {
+    readonly kind: 'key';
+    readonly name: KeySequenceKeyName;
+    /** ms to pause after this keystroke before the next step. */
+    readonly delayAfterMs?: number;
+} | {
+    readonly kind: 'literal';
+    readonly text: string;
+    /** ms to pause after this text before the next step. */
+    readonly delayAfterMs?: number;
+};
+/** Build a key step. */
+export declare function keyStep(name: KeySequenceKeyName, delayAfterMs?: number): Extract<KeySequence, {
+    kind: 'key';
+}>;
+/** Build a literal-text step. Text is always sent verbatim, never as a key. */
+export declare function literalStep(text: string, delayAfterMs?: number): Extract<KeySequence, {
+    kind: 'literal';
+}>;
+/** Whether a step sends text rather than a key. */
+export declare function isLiteralStep(step: KeySequence): step is Extract<KeySequence, {
+    kind: 'literal';
+}>;
+/** Whether a step sends a named key rather than text. */
+export declare function isKeyStep(step: KeySequence): step is Extract<KeySequence, {
+    kind: 'key';
+}>;
+/**
+ * Whether `name` is a key name a {@link KeySequence} step may carry.
+ *
+ * Defense in depth against a JavaScript caller or an `as` cast: the executor
+ * refuses anything else rather than handing an unvalidated string to tmux.
+ */
+export declare function isKeySequenceKeyName(name: string): name is KeySequenceKeyName;
+/**
+ * How a tool's input box is located on a captured frame.
+ *
+ *   `input-line-marker` - the composer is a row that starts with a prompt
+ *      marker (`>` / `❯` / `›`, optionally behind vibe-local's `ctx:N%`).
+ *      Every supported tool except opencode.
+ *   `opencode-box` - a bordered box with a gutter and no marker anywhere, whose
+ *      rows are found structurally (#1911's chrome walk) and whose emptiness is
+ *      said by its own `Ask anything...` placeholder (#1883).
+ *   `unreadable` - nobody has measured this tool's box. Every send is then
+ *      classified `submitted` without evidence, which is what #1906 found
+ *      opencode had been doing since #1471 — so this is a state to declare
+ *      knowingly, never a default to fall into.
+ */
+export type ComposerReader = 'input-line-marker' | 'opencode-box' | 'unreadable';
+/**
+ * What the submit-verified sender needs to know about one tool's composer.
+ *
+ * Returned by `ICLITool.describeComposer()`; `sendMessageWithSubmitVerification`
+ * takes one so the sender no longer keys three separate module-level tables on
+ * `CLIToolType`.
+ */
+export interface ComposerSpec {
+    /** How the composer is found on a frame. */
+    readonly reader: ComposerReader;
+    /**
+     * Rows of pane to ask tmux for when reading the submit back.
+     *
+     * A tail window for the marker tools, whose composer is the last thing on the
+     * pane. opencode needs the whole visible frame: it centres its box under the
+     * banner until the first turn is answered, roughly 100 rows above the bottom
+     * of a 200-row pane (measured live on opencode 1.18.21 in #1906).
+     */
+    readonly verifyCaptureLines: number;
+    /**
+     * Whether this layer may empty the composer before typing into it (#1880).
+     *
+     * True only for a tool whose input box has been captured at the production
+     * geometry, placeholder and dialogs included. Blind `C-e`+`C-u` into a box
+     * nobody has measured replaces a residual-text problem with a data-loss one.
+     */
+    readonly clearBeforeSend: boolean;
+    /**
+     * Enter presses for the INITIAL submit.
+     *
+     * 2 for vibe-local, whose IME mode makes the first Enter insert a newline.
+     */
+    readonly submitEnterCount: number;
+}
+/**
+ * What a status probe must ask tmux for, per tool.
+ *
+ * Returned by `ICLITool.captureSpec()`. Replaces the `if (cliToolId === …)`
+ * ladder that `src/lib/session/worktree-status-helper.ts` carried, which is
+ * outside `src/lib/cli-tools/**` and therefore had to import two tool modules
+ * for their pane heights.
+ */
+export interface CaptureSpec {
+    /**
+     * Rows of pane the status DETECTION path captures.
+     *
+     * A tool that paints a fixed-height alternate screen asks for exactly its own
+     * pane height, because that is all `capture-pane` can ever return for it.
+     */
+    readonly statusLines: number;
+    /**
+     * Whether the tool renders in the terminal's alternate screen (#1268).
+     *
+     * When true tmux keeps no scrollback, every capture returns exactly
+     * `pane_height` rows, and a captured line COUNT is a screen-row count rather
+     * than a monotonic cursor — so it must never be used to decide "have I
+     * already read this?".
+     */
+    readonly usesAlternateScreen: boolean;
+}
+/**
+ * How a tool is asked to quit, and what must be true afterwards.
+ *
+ * Returned by `ICLITool.gracefulExitSequence()`.
+ */
+export interface GracefulExitSpec {
+    /** The keystrokes that ask the TUI to quit, in order. */
+    readonly keys: readonly KeySequence[];
+    /**
+     * ms to wait after the last keystroke before the postcondition is checked.
+     *
+     * Per tool because the shutdowns differ by an order of magnitude: copilot
+     * 1.0.80 was measured between 1.006 s and 2.193 s (#1905), opencode 1.18.21
+     * at ~0.45 s, and the Ctrl-D tools inside the generic 500 ms.
+     */
+    readonly exitWaitMs: number;
+    /**
+     * Whether this tool owns a loopback HTTP server whose port is handed back on
+     * exit — opencode alone, whose TUI *is* an HTTP server once it is given
+     * `--port` (#1758 §5.1.2).
+     *
+     * When true, "the pane is gone" is not the whole postcondition: the assigned
+     * port must also stop answering `/global/health` before it may be handed to
+     * the next instance. See {@link GracefulExitFailureReason}.
+     */
+    readonly ownsLoopbackServer: boolean;
+}
+/**
+ * Why a graceful exit's postcondition was not met.
+ *
+ *   `graceful_exit_timeout` - the tmux session still existed after the tool's
+ *      own exit window. The TUI did not quit; the pane must be force-killed.
+ *   `port_orphaned` - the pane is gone but the port it was allocated is still
+ *      answering `/global/health` as opencode. Handing that number to the next
+ *      instance makes two owners of one port: the new instance's subscription
+ *      attaches to the old server and files its events against the wrong
+ *      worktree, silently. The number must not be reused until it goes quiet.
+ */
+export declare const GRACEFUL_EXIT_FAILURE_REASONS: readonly ["graceful_exit_timeout", "port_orphaned"];
+/** Reason token for a graceful exit that did not meet its postcondition. */
+export type GracefulExitFailureReason = typeof GRACEFUL_EXIT_FAILURE_REASONS[number];
+/**
+ * The postcondition's verdict.
+ *
+ * `ok: false` always carries a reason, and the reason is always one a caller can
+ * act on: both of them mean "force kill", and `port_orphaned` additionally means
+ * "do not hand this port out yet".
+ */
+export type GracefulExitVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: GracefulExitFailureReason;
+};
+//# sourceMappingURL=cli-tool-contracts.d.ts.map

package/dist/types/cli-tool-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-tool-contracts.d.ts","sourceRoot":"","sources":["../../src/types/cli-tool-contracts.ts"],"names":[],"mappings":"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"}