commandmate 0.26.1 → 0.27.0

package/dist/server/src/lib/session/provisional-turn.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * The per-instance turn model (Issue #1930, 方針書 §4 D3 決定 2・3 / §5.2 / §6.2).
+ *
+ * ## What this replaces
+ *
+ * Issue #1926 landed the CONTRACT — `turnId` / `openedAt` / `closedAt` /
+ * `closedBy` on `structuredEvents` — and derived it from the single most recent
+ * structured event, because that was all `agent-event-state` retained. Its own
+ * module doc said what was wrong with that and named the fix:
+ *
+ * > It is not a stable turn identity yet. The retained record is one event, so
+ * > a `pre_tool_use` arriving mid-turn re-stamps `openedAt` and therefore the
+ * > id. […] that is exactly what the Phase 4 `TurnRecord` fixes.
+ *
+ * This module is that `TurnRecord`. The state it describes is held by
+ * `agent-event-state` (one record per `(worktree, tool, instance)`); everything
+ * here is pure, so the whole state machine can be driven from a test with no
+ * tmux session, no database and no clock behind it.
+ *
+ * ## The two rules the old model could not express
+ *
+ *  1. **An event that carries no verdict does not close a turn, and does not
+ *     erase one either** (§4 D3 決定 2). Under "the newest event is the
+ *     verdict", a `session_start`, a `session_end`, an unrecognised
+ *     `Notification` or a `permission.replied` frame each overwrote the record
+ *     the verdict was read from, so an event that said nothing published
+ *     "nothing is known". Issue #1903 fixed the one instance of that which was
+ *     measured (copilot's late `SessionStart`) by *holding the delivery*; here
+ *     the rule is general, and the hold is only about which event is displayed.
+ *  2. **A turn has an identity**, so `turnId` survives the tool calls inside it
+ *     and does not survive a session that was recreated underneath it.
+ *
+ * ## Why the file is still called `provisional-turn.ts`
+ *
+ * Because the published field names are a contract that `capture --json`,
+ * `wait` and the header chip already read, and renaming the module would move
+ * that contract for no reader's benefit. The *provisional* derivation is gone;
+ * see {@link derivePublishedTurn}, which now reads a real record.
+ *
+ * @module lib/session/provisional-turn
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_TURN = exports.MAX_EXTERNAL_ID_LENGTH = exports.MAX_PENDING_DECISIONS_PER_TURN = exports.SCRAPER_COMPLETION_POLLS = exports.DIALOG_PENDING_MAX_MS = exports.TURN_STALE_AFTER_MS = exports.TURN_CLOSE_REASONS = exports.TURN_ACTIVITY_EVENTS = void 0;
+exports.derivePublishedTurn = derivePublishedTurn;
+exports.acceptExternalId = acceptExternalId;
+exports.boundDisplayText = boundDisplayText;
+exports.boundDecisionMessage = boundDecisionMessage;
+exports.boundDecisionToolName = boundDecisionToolName;
+exports.isDecisionLive = isDecisionLive;
+exports.isDeliveryExpired = isDeliveryExpired;
+exports.closesTurn = closesTurn;
+const agent_event_types_1 = require("../../lib/hooks/agent-event-types");
+const structured_prompt_1 = require("../../lib/session/structured-prompt");
+/**
+ * The events that mean "the agent is mid-turn".
+ *
+ * The same three `wait.ts` adopts a turn from (`TURN_OPENING_EVENT_TYPES`), and
+ * that is not a coincidence to be tidied away: `wait`'s `adoptTurnStart` reads
+ * {@link PublishedTurn.openedAt} since Issue #1930, so a derivation that opened
+ * a turn on a different set would silently change `wait`'s completion gate.
+ * `tests/unit/session/status-contract-1926.test.ts` pins the two sets equal —
+ * the CLI cannot import this module (`tsconfig.cli.json` sets `"paths": {}`),
+ * so the pin is the only thing holding them together.
+ *
+ * `stop` is not here and `notification(idle_prompt)` is not either: #1839
+ * measured Claude emitting `idle_prompt` 62 s into a turn that ran nothing, so
+ * only `Stop` ends a turn and nothing but these three opens one.
+ */
+exports.TURN_ACTIVITY_EVENTS = new Set([
+    'user_prompt_submit',
+    'pre_tool_use',
+    'post_tool_use',
+]);
+/**
+ * Why a turn ended.
+ *
+ * The vocabulary §7 reserved and this Issue fills in. Every value is a
+ * different *kind* of evidence, and an operator reading `capture --json` or a
+ * `wait` diagnostic has to be able to tell them apart:
+ *
+ *  - `stop` — the agent's own `Stop`, for the session that opened the turn.
+ *    The only value that is the agent speaking.
+ *  - `session_end` — the agent's session ended under the turn (`/clear`, exit).
+ *    Not a completion: the work was abandoned, so no `ready` is published.
+ *  - `stale` — nothing has been heard for {@link TURN_STALE_AFTER_MS}. The
+ *    bound that stops a lost `Stop` from asserting `running` forever.
+ *  - `scraper_evidence` — the terminal frame said "done" on
+ *    {@link SCRAPER_COMPLETION_POLLS} consecutive polls with positive evidence.
+ *    The screen, not the agent.
+ *  - `resync_idle` — a source that can be re-read (`capabilities.resync`) was
+ *    asked after a dropped transport and answered "not busy".
+ *  - `generation` — the process that owned the turn was replaced.
+ */
+exports.TURN_CLOSE_REASONS = [
+    'stop',
+    'session_end',
+    'stale',
+    'scraper_evidence',
+    'resync_idle',
+    'generation',
+];
+/**
+ * How long a turn is trusted after the last thing that was heard about it
+ * (Issue #1723, renamed here in #1930).
+ *
+ * Hooks are fail-open by design: a timeout or a refused connection costs the
+ * event and never the agent's turn (`agent-hooks-live-verification.md` §1.1).
+ * A *lost* `Stop` is therefore possible, and without a bound it would leave
+ * this layer asserting `running` for a session that finished — `commandmate
+ * wait` would then poll until `--timeout` on a session the scraper could have
+ * called done. The bound converts "forever" into "at most this long", after
+ * which the scraper takes the session back.
+ *
+ * Deliberately generous. A single agent turn running past 30 minutes is
+ * ordinary for the workloads this tool exists to babysit, and expiring a live
+ * verdict mid-turn costs the whole benefit of the two-layer split.
+ *
+ * Re-exported by `agent-event-state` as `STRUCTURED_STATE_MAX_AGE_MS`, which is
+ * the name `status-evidence` and the suites already read. One expression, two
+ * names — §4 D1 決定 2 forbids two expressions, not two spellings.
+ */
+exports.TURN_STALE_AFTER_MS = 30 * 60 * 1000;
+/**
+ * How long a dialog record is held without being answered (Issue #1930).
+ *
+ * §4 D3 asks for `dialogPendingMaxMs` as a **retention** bound, and separates it
+ * from the **delivery** bound (`decisionTimeoutSeconds`, #1924). The two answer
+ * different questions and are allowed to disagree:
+ *
+ *  - delivery — "can a verdict from this server still reach the agent?"
+ *    copilot gives up after ~10 s. Past it the record is reported as
+ *    `deliveryExpired`; the dialog is **still on screen**, so `waiting` is kept.
+ *    Expiring the state there would tell an operator the pane is free while a
+ *    human is still blocked on it.
+ *  - retention — "is this record still describing something?" Two values,
+ *    because the two sources of a record are different kinds of statement:
+ *
+ *    `predicted` (20 s) is a `PermissionRequest` this server declined to decide.
+ *    It fires *before* the dialog, so it is a prediction — an accurate one (D5
+ *    measured `{}` landing in the ordinary TUI approval flow), but about a
+ *    version of the agent, a permission mode and a rule set this server does not
+ *    get to see in full. A prediction that nothing confirms must expire, because
+ *    the cost of it sticking is a `wait --on-prompt agent` that exits 10 on a
+ *    session with no dialog in it. 20 s is generous against both confirmations:
+ *    `Notification(permission_prompt)` lands at ~6 s, and the scraper reads the
+ *    pane through a 5 s capture cache on a 5 s poll.
+ *
+ *    `confirmed` is the turn's own staleness bound: something independent saw
+ *    the dialog, so it is as trustworthy as the turn around it.
+ */
+exports.DIALOG_PENDING_MAX_MS = {
+    predicted: 20_000,
+    confirmed: exports.TURN_STALE_AFTER_MS,
+};
+/**
+ * Consecutive positive "the agent is back at its composer" polls that close a
+ * turn as {@link TurnCloseReason} `scraper_evidence`.
+ *
+ * Three rather than one, because one poll is one capture and a capture taken
+ * mid-repaint is exactly the frame the detector is worst at. Three at the 5 s
+ * poll is ~15 s of agreement, which is far inside the 30-minute staleness bound
+ * it exists to shorten and far outside any single-frame artefact.
+ *
+ * **This does not complete a `wait`.** `wait`'s turn-boundary gate is
+ * `lastStopEventAt`, and #1839 measured why: a 529 storm returns Claude to its
+ * composer in ~3 s having executed nothing, with the frame reading positively
+ * as `ready`. Closing the turn here retires the *structured verdict* — so
+ * `capture --json` and `instances` stop saying `running` for a session nothing
+ * is running in — and leaves the completion question exactly where #1839 and
+ * #1975 put it.
+ */
+exports.SCRAPER_COMPLETION_POLLS = 3;
+/**
+ * Cap on the decisions one turn retains (S14(d)).
+ *
+ * The list is fed by frames from a process CommandMate did not start. An agent
+ * that raised hundreds of approvals in one turn must cost a bounded record, and
+ * the overflow has to be *counted* rather than dropped in silence — see
+ * `getAgentEventDropCounts`.
+ */
+exports.MAX_PENDING_DECISIONS_PER_TURN = 16;
+/**
+ * Longest external id this layer will store (S1).
+ *
+ * Ids arrive from the agent and reach a Map key, a log line and a JSON payload.
+ * An id longer than this is **discarded, never truncated**: a truncated id
+ * compares equal to a different id that shares its prefix, which would let one
+ * approval's reply retire another's record. The discard is counted
+ * (`idsDiscarded`) so an operator can see it happened.
+ */
+exports.MAX_EXTERNAL_ID_LENGTH = 128;
+/** Nothing has been reported, so nothing can be said about a turn. */
+exports.NO_TURN = {
+    turnId: null,
+    openedAt: null,
+    closedAt: null,
+    closedBy: null,
+};
+/**
+ * Publish the turn fields for one instance.
+ *
+ * Pure, and takes the *effective* record — the caller has already applied the
+ * generation fence and the staleness bound, because those need state this
+ * module does not hold.
+ */
+function derivePublishedTurn(turn) {
+    if (turn === null)
+        return exports.NO_TURN;
+    return {
+        turnId: turn.turnId,
+        openedAt: turn.openedAt,
+        closedAt: turn.closedAt,
+        closedBy: turn.closedBy,
+    };
+}
+/**
+ * Accept an external id, or refuse it (S1).
+ *
+ * Refusal is the whole point: an id that is empty, over-long, or carrying
+ * control characters is **discarded**, and the caller then behaves as it does
+ * for a source that publishes no id at all — a path every consumer already has,
+ * because five of the six sources take it. Truncating instead would manufacture
+ * collisions between ids that share a prefix, and the failure that produces
+ * (one approval's reply retiring another's record) is silent.
+ *
+ * @returns The id, or null when it must not be used
+ */
+function acceptExternalId(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    if (raw.length === 0 || raw.length > exports.MAX_EXTERNAL_ID_LENGTH)
+        return null;
+    for (let i = 0; i < raw.length; i++) {
+        const code = raw.charCodeAt(i);
+        // An id reaches a Map key, a log line and a JSON payload; control
+        // characters in any of the three are somebody else's parsing bug.
+        if (code < 0x20 || code === 0x7f)
+            return null;
+    }
+    return raw;
+}
+/** Bound a human-facing line before it is retained (S3). */
+function boundDisplayText(raw, max) {
+    if (typeof raw !== 'string' || raw === '')
+        return null;
+    return raw.slice(0, max);
+}
+/** {@link boundDisplayText} at the message bound. */
+function boundDecisionMessage(raw) {
+    return boundDisplayText(raw, structured_prompt_1.MAX_STRUCTURED_PROMPT_MESSAGE_LENGTH);
+}
+/** {@link boundDisplayText} at the detail bound — tool names, subtypes. */
+function boundDecisionToolName(raw) {
+    return boundDisplayText(raw, agent_event_types_1.MAX_EVENT_DETAIL_LENGTH);
+}
+/**
+ * Whether this decision is still describing something, at `now`.
+ *
+ * The retention bound of {@link DIALOG_PENDING_MAX_MS}, applied on read. A
+ * decision that has fallen out is not mutated in place — the caller drops it and
+ * counts it — so this stays a pure predicate.
+ */
+function isDecisionLive(decision, now) {
+    const bound = decision.confirmedAt === null
+        ? exports.DIALOG_PENDING_MAX_MS.predicted
+        : exports.DIALOG_PENDING_MAX_MS.confirmed;
+    return now - decision.at < bound;
+}
+/**
+ * Whether a verdict from this server can still reach the agent, at `now`.
+ *
+ * Independent of {@link isDecisionLive} on purpose — see
+ * {@link DIALOG_PENDING_MAX_MS}. An expired delivery window keeps `waiting`:
+ * the dialog is on the pane whether or not this server can still answer it.
+ *
+ * The timeout is passed in rather than stored on the record, because it is a
+ * *declared capability* of the source (#1924) and `agent-event-state` cannot
+ * reach the source registry — its module graph pulls in `better-sqlite3`, which
+ * is why every capability arrives there as a value the caller hands over. The
+ * one layer that already holds both is `current-output-builder`, which is where
+ * this is computed for the payload.
+ *
+ * @param decisionTimeoutSeconds - `capabilities.decisionTimeoutSeconds`; null
+ *   for a source that waits forever, which can never expire
+ */
+function isDeliveryExpired(decision, decisionTimeoutSeconds, now) {
+    if (decisionTimeoutSeconds === null)
+        return false;
+    return now - decision.at >= decisionTimeoutSeconds * 1000;
+}
+/**
+ * Whether a turn-ending event naming `eventSessionId` ends `turn`.
+ *
+ * §4 D3 決定 2: a `stop` closes **the turn of the session that sent it**. The
+ * acceptance case is "another session's idle": opencode publishes `session.idle`
+ * for every session its server holds, including ones belonging to other
+ * processes entirely (#1758 §5.6), and one of those completing must not
+ * complete this pane's work.
+ *
+ * When either side is anonymous the two are treated as the same session,
+ * because "no id" is the shape a hand-configured #1549 relay hook posts and the
+ * rule has to survive it. That residue is bounded by {@link TURN_STALE_AFTER_MS}
+ * and by the generation fence.
+ */
+function closesTurn(turn, eventSessionId) {
+    if (turn.sessionId === null || eventSessionId === null)
+        return true;
+    return turn.sessionId === eventSessionId;
+}

package/dist/server/src/lib/session/resolve-session-target.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * The one place tool / instance resolution happens (Issue #1925, design §4 D5).
+ *
+ * Before this module the answer to "which CLI tool and which instance does this
+ * request target?" had four implementations (design §3 P4): the server-side
+ * `resolveInstanceCliTool`, the CLI's own two-stage copy, `kill-session`'s
+ * inline expression and `capture`'s `resolvePaneCliTool`. They disagreed —
+ * `kill-session` let an explicit `?cliTool` override the roster and never
+ * reported the contradiction, and the CLI copy had no primary-anchor stage — so
+ * the same (worktree, instance, tool) triple resolved differently depending on
+ * which door the request came through. The tool id is part of the tmux session
+ * name, so disagreeing means starting or reading the wrong agent under a
+ * session name that claims otherwise.
+ *
+ * Precedence (design §4 D5 決定 2, matching the #1629 implementation):
+ *
+ *   instanceId omitted -> the explicit request, or the worktree default.
+ *                         The roster is not consulted at all (DR3-020).
+ *   instanceId given   -> roster entry
+ *                      -> explicit request (only for an instance the roster
+ *                         does not know: the ad-hoc `send --instance <new-id>`)
+ *                      -> instanceId when it is itself a CLI tool id (the
+ *                         primary-instance anchor, #868)
+ *                      -> worktree default
+ *                      -> DEFAULT_SESSION_CLI_TOOL
+ *
+ * The roster outranks the explicit request because it is the user-maintained
+ * declaration of what a named instance is; a contradiction is reported rather
+ * than silently resolved. Callers decide what to do with it: routes with a side
+ * effect answer 400, read-only routes answer 200 and surface the conflict in
+ * the payload (design §4 D5 / DR3-015).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTANCE_TOOL_CONFLICT = exports.DEFAULT_SESSION_CLI_TOOL = void 0;
+exports.resolveSessionTarget = resolveSessionTarget;
+exports.resolveSessionTargetStrict = resolveSessionTargetStrict;
+exports.describeSessionTargetConflict = describeSessionTargetConflict;
+const worktree_db_1 = require("../../lib/db/worktree-db");
+const agent_instances_db_1 = require("../../lib/db/agent-instances-db");
+const types_1 = require("../../lib/cli-tools/types");
+/**
+ * Last-resort CLI tool when nothing else in the precedence chain has an answer.
+ *
+ * Design §4 D5 決定 4 names this module as the single place the default agent
+ * may be named as a literal: every other copy of it scattered through the
+ * resolution paths is a duplicated default that this function exists to absorb.
+ * Reaching it is a warning, not a normal outcome — see `resolvedBy: 'fallback'`.
+ */
+exports.DEFAULT_SESSION_CLI_TOOL = 'claude';
+/** Machine-readable reason code for a contradiction, shared by every route. */
+exports.INSTANCE_TOOL_CONFLICT = 'instance_tool_conflict';
+/**
+ * Resolve the CLI tool and instance a request targets.
+ *
+ * Always returns a target: a contradiction is reported through `conflict`
+ * rather than by failing, because the two classes of caller need different
+ * outcomes from the same facts. Use {@link resolveSessionTargetStrict} for the
+ * routes that must refuse instead.
+ *
+ * @param db - Database instance
+ * @param worktreeId - Worktree ID (already canonicalized and validated)
+ * @param options - Targeting signals carried by the request
+ * @returns The resolved target, with `conflict` set when the request contradicts the roster
+ */
+function resolveSessionTarget(db, worktreeId, options = {}) {
+    const { instanceId, requestedCliTool } = options;
+    // DR3-020: without an instanceId there is nothing to look up, and reading the
+    // roster here would let an unrelated instance's tool leak into a request that
+    // never named one.
+    if (!instanceId) {
+        if (requestedCliTool) {
+            return {
+                cliToolId: requestedCliTool,
+                instanceId: requestedCliTool,
+                resolvedBy: 'explicit',
+            };
+        }
+        return worktreeDefaultTarget(db, worktreeId, undefined);
+    }
+    const registered = (0, agent_instances_db_1.getAgentInstance)(db, worktreeId, instanceId);
+    if (registered && (0, types_1.isCliToolType)(registered.cliTool)) {
+        const target = {
+            cliToolId: registered.cliTool,
+            instanceId,
+            resolvedBy: 'roster',
+        };
+        if (requestedCliTool && requestedCliTool !== registered.cliTool) {
+            target.conflict = {
+                instanceId,
+                rosterCliTool: registered.cliTool,
+                requestedCliTool,
+            };
+        }
+        return target;
+    }
+    // The roster does not know this instance (the ad-hoc `send --instance <new-id>`
+    // flow), so an explicit tool is the only declaration there is.
+    if (requestedCliTool) {
+        return { cliToolId: requestedCliTool, instanceId, resolvedBy: 'explicit' };
+    }
+    // #868: an instance id that names a CLI tool *is* that tool's primary
+    // instance, which holds without a roster row.
+    if ((0, types_1.isCliToolType)(instanceId)) {
+        return { cliToolId: instanceId, instanceId, resolvedBy: 'primary' };
+    }
+    return worktreeDefaultTarget(db, worktreeId, instanceId);
+}
+/**
+ * The tail of the chain: the worktree's own CLI tool, then the last-resort
+ * default. Split out so both entry points into it read the same.
+ */
+function worktreeDefaultTarget(db, worktreeId, instanceId) {
+    const worktree = (0, worktree_db_1.getWorktreeById)(db, worktreeId);
+    const worktreeCliTool = worktree?.cliToolId;
+    if (worktreeCliTool && (0, types_1.isCliToolType)(worktreeCliTool)) {
+        return {
+            cliToolId: worktreeCliTool,
+            instanceId: instanceId ?? worktreeCliTool,
+            resolvedBy: 'worktree-default',
+        };
+    }
+    return {
+        cliToolId: exports.DEFAULT_SESSION_CLI_TOOL,
+        instanceId: instanceId ?? exports.DEFAULT_SESSION_CLI_TOOL,
+        resolvedBy: 'fallback',
+    };
+}
+/**
+ * {@link resolveSessionTarget} for routes with a side effect (design §4 D5 決定 3
+ * / DR3-015): `send`, `respond`, `interrupt`, `kill-session`, `terminal`,
+ * `special-keys` and `auto-yes` POST answer 400 rather than guess which of the
+ * two contradicting declarations the operator meant.
+ *
+ * @param db - Database instance
+ * @param worktreeId - Worktree ID (already canonicalized and validated)
+ * @param options - Targeting signals carried by the request
+ * @returns The resolved target, or the conflict to answer 400 with
+ */
+function resolveSessionTargetStrict(db, worktreeId, options = {}) {
+    const target = resolveSessionTarget(db, worktreeId, options);
+    if (target.conflict) {
+        return { ok: false, error: exports.INSTANCE_TOOL_CONFLICT, conflict: target.conflict };
+    }
+    return { ok: true, target };
+}
+/**
+ * The sentence shown to a human when the roster and the request disagree.
+ * Names both declarations and the three ways out, because the operator has to
+ * pick which one is wrong.
+ */
+function describeSessionTargetConflict(conflict) {
+    return (`Agent instance '${conflict.instanceId}' is registered as ${conflict.rosterCliTool}, `
+        + `but ${conflict.requestedCliTool} was requested. `
+        + `Omit the agent, pass ${conflict.rosterCliTool}, or update the instance's roster entry.`);
+}

package/dist/server/src/lib/session/send-user-message.js

@@ -12,7 +12,7 @@
  *   1. savePendingAssistantResponse  — persist the previous assistant reply
  *   2. orphan detection              — Issue #379 duplicate-message guard
  *   3. copilot /model command        — Issue #576 (copilot only)
- *   4. send to CLI tool              — image / copilot / normal branches
+ *   4. send to CLI tool              — image branch / ICLITool.sendMessage
  *   5. createMessage (role: 'user')  — INSERT INTO chat_messages (History source)
  *   6. orphan deletion               — remove prior duplicate after persist
  *   7. updateLastUserMessage
@@ -30,11 +30,8 @@ const manager_1 = require("../../lib/cli-tools/manager");
 const types_1 = require("../../lib/cli-tools/types");
 const response_poller_1 = require("../../lib/polling/response-poller");
 const assistant_response_saver_1 = require("../../lib/assistant-response-saver");
-const tmux_1 = require("../../lib/tmux/tmux");
-const tmux_capture_cache_1 = require("../../lib/tmux/tmux-capture-cache");
 const logger_1 = require("../../lib/logger");
 const prompt_waiting_guard_1 = require("../../lib/session/prompt-waiting-guard");
-const copilot_constants_1 = require("../../config/copilot-constants");
 const logger = (0, logger_1.createLogger)('session/send-user-message');
 function getErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -140,21 +137,20 @@ async function sendUserMessage(db, params) {
                 await cliTool.sendMessage(worktreeId, messageWithPath, instanceId);
             }
         }
-        else if (cliToolId === 'copilot') {
-            // Copilot: use sendKeys directly to avoid waitForPrompt blocking (#559).
-            // Copilot CLI auto-enters multi-line mode when text exceeds pane width.
-            // In multi-line mode, C-m (bundled with text) adds a newline instead of
-            // submitting. Sending Enter as a separate tmux command after a delay
-            // allows the TUI to process the text first, then accept Enter as submit.
-            const sessionName = cliTool.getSessionName(worktreeId, instanceId);
-            // Replace newlines with spaces to prevent Copilot CLI multi-line mode
-            const copilotContent = content.replace(/\n+/g, ' ').trim();
-            await (0, tmux_1.sendKeys)(sessionName, copilotContent, false);
-            await new Promise(resolve => setTimeout(resolve, copilot_constants_1.COPILOT_SEND_ENTER_DELAY_MS));
-            await (0, tmux_1.sendSpecialKeys)(sessionName, ['Enter']);
-            (0, tmux_capture_cache_1.invalidateCache)(sessionName);
-        }
         else {
+            // Issue #1906: every tool — copilot included — goes through its own
+            // `ICLITool.sendMessage`. copilot used to be special-cased here with a raw
+            // `sendKeys` + delayed Enter, which skipped `CopilotTool.sendMessage`
+            // entirely: no `waitForPrompt` (so a folder-trust dialog was typed into,
+            // #1886), no selection-list branch (#1895), and — because nothing read the
+            // pane back — no #1471 "the Enter was swallowed" failure, so a typed-but-
+            // unsent message was reported as sent. It also flattened `\n+` to spaces,
+            // which silently turned a contract preamble or a Markdown body into one
+            // line. Measured on copilot 1.0.80 (private tmux socket, `tmux -L`):
+            // `send-keys` with literal newlines leaves the body multi-line in the
+            // composer (`❯ line one` / `  line two` / `  line three`) and a SEPARATE
+            // Enter submits all of it — the transcript echo keeps the line breaks — so
+            // the flattening is not needed to make Enter submit and is now gone.
             await cliTool.sendMessage(worktreeId, content, instanceId);
         }
     }

package/dist/server/src/lib/session/session-start-error.js

@@ -29,13 +29,24 @@
  * @module lib/session/session-start-error
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionStartFailedError = exports.SessionStartTimeoutError = exports.SESSION_START_FAILED_CODE = exports.SESSION_STARTING_CODE = void 0;
+exports.SessionStartUnavailableError = exports.SessionStartFailedError = exports.SessionStartTimeoutError = exports.SESSION_START_UNAVAILABLE_CODE = exports.SESSION_START_FAILED_CODE = exports.SESSION_STARTING_CODE = void 0;
 exports.isSessionStartTimeoutError = isSessionStartTimeoutError;
 exports.isSafeSessionStartError = isSafeSessionStartError;
+exports.isSessionStartUnavailableError = isSessionStartUnavailableError;
 /** Code for a session that exists and is still coming up. */
 exports.SESSION_STARTING_CODE = 'SESSION_STARTING';
 /** Code for a session that started and then reported a terminal error. */
 exports.SESSION_START_FAILED_CODE = 'SESSION_START_FAILED';
+/**
+ * Code for a start that could not even be attempted — the CLI is not on PATH.
+ *
+ * Issue #2009: every one of the seven tools already detects this, and every one
+ * of them threw a bare `Error`, so nothing downstream could tell "the binary is
+ * missing" (install it) from "tmux refused" (something else is wrong) from "it
+ * is merely slow" (wait). The code is what lets the ONE notification decision in
+ * `lib/push/failure-push-notifier` answer all three differently.
+ */
+exports.SESSION_START_UNAVAILABLE_CODE = 'SESSION_START_UNAVAILABLE';
 /** The codes {@link isSafeSessionStartError} recognises. */
 const SAFE_CODES = [exports.SESSION_STARTING_CODE, exports.SESSION_START_FAILED_CODE];
 /**
@@ -99,6 +110,35 @@ class SessionStartFailedError extends Error {
     }
 }
 exports.SessionStartFailedError = SessionStartFailedError;
+/**
+ * The CLI tool is not installed, so no session could be attempted.
+ *
+ * Issue #2009. The message defaults to the wording `POST /api/worktrees/:id/send`
+ * used to compose at the HTTP layer, so a tool that has nothing more useful to
+ * say keeps the body its callers already read; a tool that DOES (copilot ships
+ * an install hint) passes its own.
+ *
+ * Deliberately NOT in {@link SAFE_CODES}: that list is #1637's exception to
+ * SEC-SF-002 for `startClaudeSession`'s catch, and widening it would change
+ * which messages that catch lets past. Nothing throws this from inside that
+ * try block — claude's own install check runs before it — so membership would
+ * buy nothing and cost the reader a reason to re-audit #1637.
+ */
+class SessionStartUnavailableError extends Error {
+    toolName;
+    /** @see SESSION_START_UNAVAILABLE_CODE */
+    code = exports.SESSION_START_UNAVAILABLE_CODE;
+    /**
+     * @param toolName - Display name of the CLI tool (e.g. `Codex CLI`)
+     * @param message - Tool-specific wording; defaults to the generic advice
+     */
+    constructor(toolName, message = `${toolName} is not installed. Please install it first.`) {
+        super(message);
+        this.toolName = toolName;
+        this.name = 'SessionStartUnavailableError';
+    }
+}
+exports.SessionStartUnavailableError = SessionStartUnavailableError;
 /**
  * Whether `error` reports a session that is still initializing.
  *
@@ -117,6 +157,18 @@ function isSafeSessionStartError(error) {
     const code = readErrorCode(error);
     return code !== undefined && SAFE_CODES.includes(code);
 }
+/**
+ * Whether `error` reports a CLI tool that is not installed (Issue #2009).
+ *
+ * Duck-typed on `code` for the reason the module docblock gives: the thrower
+ * (seven separate tool modules) and the reader (the push notifier, the API
+ * route) never share a class identity under bundling.
+ *
+ * @param error - Value caught from a `startSession()` call
+ */
+function isSessionStartUnavailableError(error) {
+    return readErrorCode(error) === exports.SESSION_START_UNAVAILABLE_CODE;
+}
 function readErrorCode(error) {
     if (typeof error !== 'object' || error === null)
         return undefined;