commandmate 0.26.1 → 0.27.0

package/dist/server/src/lib/session/status-evidence.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * Whether a status verdict rests on something positive, and what the last
+ * positively confirmed verdict was (Issue #1926, 方針書 §4 D1 / §7).
+ *
+ * Two things live here, for one reason: they are the pair a surface needs in
+ * order to say "I cannot read this frame, and here is what it last was".
+ *
+ *  1. {@link isUnclassifiedFrame} — the ONE expression that decides whether the
+ *     detector could classify a frame at all. Issue #1924 introduced the reading
+ *     inline in `current-output-builder`; §4 D1 決定 2 says in as many words that
+ *     two expressions for one fact is how consumers come apart, so it lives here
+ *     and the producer calls it.
+ *  2. {@link observeStatusEvidence} / {@link getLastKnownStatus} — the server-side
+ *     latch of the last verdict that WAS positive, which is what §7's row
+ *     「直前の確定状態（証拠なしの間の表示）」 asks a surface to show while the
+ *     current frame carries no evidence.
+ *
+ * ## The two facts, and why Issue #2011 had to pull them apart again
+ *
+ * Until #1927 this module also held `deriveScraperEvidence`, which computed
+ * {@link StatusEvidence} from `(status, reason)` — and, because the two sets
+ * coincided at the time, doubled as the definition of "unclassified frame".
+ * #1927 moved the evidence producer into the detector (only the detector knows
+ * which rule answered) and left `current-output-builder` deriving the flag from
+ * `evidence === 'none'`. That silently redefined the flag: `'none'` means "I
+ * could not prove this pane is idle", which an ordinary Claude composer frame
+ * satisfies, while the flag's consumers — `TerminalEscapeHatch`, `wait`'s
+ * completion rule, `unclassified_frames` — were all written against "nobody
+ * could read this frame at all". Every idle Claude pane then raised the hatch
+ * and stalled `wait` (#2011).
+ *
+ * So they are two facts now, and both are published:
+ *
+ *  - `statusEvidence` — does the verdict rest on something positive? Produced by
+ *    the detector, per tool, and deliberately widened by the §4 D1 rollout.
+ *  - `isUnclassifiedActive` — could the frame be classified at all? That is
+ *    {@link isUnclassifiedFrame}, and it is a statement about the reason
+ *    vocabulary, not about the strength of the evidence behind it.
+ *
+ * A frame can be `evidence: 'none'` and classified (an idle composer no idle
+ * rule vouches for), and — since #2011's second half — `evidence: 'positive'`
+ * and unclassified (an unreadable pane whose agent reported `Stop`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LATCHES = exports.LAST_KNOWN_STATUS_TTL_MS = void 0;
+exports.isUnclassifiedFrame = isUnclassifiedFrame;
+exports.observeStatusEvidence = observeStatusEvidence;
+exports.getLastKnownStatus = getLastKnownStatus;
+exports.forgetLastKnownStatus = forgetLastKnownStatus;
+exports.clearLastKnownStatuses = clearLastKnownStatuses;
+// From the leaf module rather than the `status-detector` facade that re-exports
+// it: this Set is built at module evaluation, and a suite that partially mocks
+// the facade to stub `detectSessionStatus` would leave `STATUS_REASON` undefined
+// at exactly that moment (`worktree-status-helper.test.ts` does).
+const status_reason_1 = require("../../lib/detection/status-reason");
+const agent_event_state_1 = require("../../lib/session/agent-event-state");
+/**
+ * The reasons that mean "no rule could read this frame" (Issue #2011).
+ *
+ * These are exactly the three verdicts `tools/run-detection.ts` reaches when its
+ * chain has run out: the five-second staleness fallback (`no_recent_output`) and
+ * the two floors (`unknown_frame` for a tool whose own rules looked and found
+ * nothing, `default` for the generic "no pattern matched anywhere"). Every other
+ * reason names something the detector recognised — a completion marker, a
+ * thinking indicator, a parsed dialog, a selection list, a composer row.
+ *
+ * `input_prompt` is deliberately NOT here, and that is the whole of #2011: an
+ * idle composer whose tool-specific idle rule declined to vouch for it is a
+ * frame that WAS classified, published with `evidence: 'none'`. Putting it in
+ * this set is what opened `TerminalEscapeHatch` on every idle Claude pane and
+ * stopped `wait` completing on one.
+ */
+const UNCLASSIFIED_FRAME_REASONS = new Set([
+    status_reason_1.STATUS_REASON.NO_RECENT_OUTPUT,
+    status_reason_1.STATUS_REASON.UNKNOWN_FRAME,
+    status_reason_1.STATUS_REASON.DEFAULT,
+]);
+/**
+ * Whether the detection layer failed to classify this frame (Issue #1497 /
+ * #1708, restated as its own expression by #2011).
+ *
+ * This is the published `isUnclassifiedActive` contract: `capture --json` sends
+ * it, `wait` suppresses its completion check while it holds and exits 10 after
+ * {@link https://github.com/Kewton/CommandMate/issues/1708 60 s} of it, and both
+ * terminal surfaces open the navigation hatch on it. All three are asking the
+ * same question — "is a human looking at something nothing here can drive?" —
+ * and none of them is asking how strong the evidence behind a readable verdict
+ * is.
+ *
+ * The status is checked as well as the reason for the reason the pre-#1924
+ * expression did: `default` on anything but `running` is not the floor. Since
+ * #1927 all three reasons are only ever produced with `running` (§4 D1 決定 3
+ * abolished the `ready` the staleness heuristic used to publish), so this is a
+ * guard against a future producer rather than a live discriminator.
+ *
+ * Pure and total, and the single producer: `current-output-builder` calls it
+ * rather than restating it, and `mergeStructuredStatus` carries its answer
+ * through rather than recomputing one.
+ */
+function isUnclassifiedFrame(status, reason) {
+    return status === 'running' && UNCLASSIFIED_FRAME_REASONS.has(reason);
+}
+/**
+ * How long a latched verdict is still worth showing.
+ *
+ * §7 fixes this at `turnStaleAfterMs`, which §4 D3 決定 2 defines as the current
+ * staleness bound — so it is imported rather than restated. A second literal
+ * here would be the "value の二重定義" S2 exists to forbid, in a field whose
+ * whole job is to be honest about age.
+ */
+exports.LAST_KNOWN_STATUS_TTL_MS = agent_event_state_1.STRUCTURED_STATE_MAX_AGE_MS;
+const latches = globalThis.__lastKnownStatusByKey ??
+    (globalThis.__lastKnownStatusByKey = new Map());
+/**
+ * Cap on retained latches, so a long-lived server cannot grow one per worktree
+ * per tool per instance forever.
+ *
+ * The TTL below already drops anything half an hour old, and
+ * {@link forgetLastKnownStatus} drops a session the moment it is seen not
+ * running, so this is the backstop for neither of those happening — a server
+ * that is polled about thousands of worktrees and restarted before any of them
+ * expires. Map iterates in insertion order, so the head is the oldest write.
+ */
+exports.MAX_LATCHES = 512;
+function expired(latch, now) {
+    return now - latch.at >= exports.LAST_KNOWN_STATUS_TTL_MS;
+}
+/**
+ * Sweep, called on WRITE only.
+ *
+ * Reads are O(1) (they age out their own entry) because they are the hot path:
+ * `GET /api/worktrees` probes every tool of every worktree on every poll, so a
+ * full-map walk per read would be quadratic in the number of sessions for no
+ * benefit. Writes happen only for a session that positively confirmed something,
+ * which is at most the number of live sessions.
+ */
+function prune(now) {
+    for (const [key, latch] of latches) {
+        if (expired(latch, now))
+            latches.delete(key);
+    }
+    while (latches.size > exports.MAX_LATCHES) {
+        const oldest = latches.keys().next();
+        if (oldest.done)
+            break;
+        latches.delete(oldest.value);
+    }
+}
+/**
+ * Fold one poll's verdict into the latch for `key`.
+ *
+ * Only a `'positive'` verdict is latched — that is the whole definition of the
+ * field. A frame with no evidence leaves the previous answer standing, which is
+ * what makes "here is what it last was" mean anything.
+ *
+ * ## Two producers, on purpose
+ *
+ * `current-output-builder` latches the MERGED verdict (scraper folded with the
+ * agent's own events); `worktree-status-helper` latches the scraper's, because
+ * that is all the list API computes today. On a session with hooks the two can
+ * name different statuses for the same moment — but that divergence is the
+ * pre-existing gap between `capture --json` and the sidebar, not something this
+ * latch introduces, and both readings are genuinely "something confirmed this".
+ * Feeding it from both is what keeps the field warm for the surface that needs
+ * it most: the header chip and `commandmate ls` are driven by the list API, and
+ * a latch only `capture --json` could fill would be null on every one of their
+ * polls.
+ *
+ * @param key - Session identity; use the same composite key the pollers use
+ *   (`worktree:cliTool:instance`) so instances of one agent latch separately
+ * @param verdict - The status as published by the caller
+ * @param now - Epoch ms, injectable for tests
+ */
+function observeStatusEvidence(key, verdict, now = Date.now()) {
+    prune(now);
+    if (verdict.evidence !== 'positive')
+        return;
+    // Deleted first so the re-insert moves the entry to the tail of the insertion
+    // order the eviction above walks; otherwise a session that is polled forever
+    // would be evicted ahead of one nobody has asked about since it was created.
+    latches.delete(key);
+    latches.set(key, { status: verdict.status, reason: verdict.reason, at: now });
+}
+/**
+ * The last positively confirmed verdict for `key`, or null.
+ *
+ * Null covers three situations a caller does not have to tell apart: nothing has
+ * ever been confirmed, the last confirmation is older than
+ * {@link LAST_KNOWN_STATUS_TTL_MS}, or the server restarted (§7: 「サーバ再起動で
+ * クリア」 — the latch is in-memory by design).
+ */
+function getLastKnownStatus(key, now = Date.now()) {
+    const latch = latches.get(key);
+    if (latch === undefined)
+        return null;
+    if (expired(latch, now)) {
+        latches.delete(key);
+        return null;
+    }
+    return latch;
+}
+/**
+ * Drop the latch for a session that is no longer running.
+ *
+ * A dead session's last confirmed status describes a process that is gone, and
+ * reporting `running` from twenty minutes ago next to `isRunning: false` would
+ * be the same false confidence `model` is nulled to avoid (#1785). The next
+ * session on the same key starts with no history, which is the truth.
+ */
+function forgetLastKnownStatus(key) {
+    latches.delete(key);
+}
+/** Drop every latch. Test seam. */
+function clearLastKnownStatuses() {
+    latches.clear();
+}

package/dist/server/src/lib/session/structured-prompt.js

@@ -34,12 +34,38 @@
  * @module lib/session/structured-prompt
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_STRUCTURED_PROMPT_MESSAGE_LENGTH = void 0;
+exports.MAX_STRUCTURED_PROMPT_MESSAGE_LENGTH = exports.STRUCTURED_DECISION_OPTIONS = void 0;
 exports.buildStructuredPromptQuestion = buildStructuredPromptQuestion;
 exports.buildStructuredPromptData = buildStructuredPromptData;
 exports.buildStructuredPromptHistoryRecord = buildStructuredPromptHistoryRecord;
 exports.isStructuredPromptWaitingData = isStructuredPromptWaitingData;
 const models_1 = require("../../types/models");
+/**
+ * The three verdicts an approval dialog accepts, in the order `respond` numbers
+ * them (Issue #1898).
+ *
+ * Verdict kinds rather than a tool's wire words: `allowOnce` / `allowAlways` /
+ * `deny` is the shared vocabulary every source encodes for itself
+ * (`AgentEventSource.encodeVerdict`), so this list stays true for the next
+ * source that can be answered out of band. `reply` is opencode's spelling of
+ * the same three, published because it is what its own logs and REST calls say
+ * and an operator correlating the two should not have to translate.
+ */
+exports.STRUCTURED_DECISION_OPTIONS = [
+    // i18n (#1271) deliberately not applied to these three labels: they are part
+    // of the CLI's accepted vocabulary, not display text. `commandmate respond
+    // <id> "Allow once"` matches against them (see
+    // `lib/hooks/structured-decision-response`), and a locale-dependent label
+    // would make the same command work on one machine and fail on another. The
+    // whole of this module is English by the same rule — see
+    // `buildStructuredPromptQuestion`, whose output goes to stderr and stdout.
+    // eslint-disable-next-line no-restricted-syntax -- CLI answer vocabulary, not display text
+    { number: 1, label: 'Allow once', reply: 'once' },
+    // eslint-disable-next-line no-restricted-syntax -- CLI answer vocabulary, not display text
+    { number: 2, label: 'Allow always', reply: 'always' },
+    // eslint-disable-next-line no-restricted-syntax -- CLI answer vocabulary, not display text
+    { number: 3, label: 'Reject', reply: 'reject' },
+];
 /** Bound on the agent's `message`, which is prose and only ever displayed. */
 exports.MAX_STRUCTURED_PROMPT_MESSAGE_LENGTH = 500;
 /** How each source reads in the one-line question. */
@@ -61,10 +87,23 @@ function buildStructuredPromptQuestion(worktreeId, facts) {
         `A dialog is open in ${worktreeId}: the agent reported it via ${SOURCE_LABEL[facts.source]}` +
             `${facts.toolName ? ` for ${facts.toolName}` : ''}, but the detection layer published no ` +
             `options for it.`,
-        `Answer it in the terminal, or send the option NUMBER with ` +
-            `\`commandmate respond ${worktreeId} <number>\` — yes/no is not resolved on a numbered ` +
-            `dialog (Issue #1681).`,
     ];
+    if (facts.decisionOptions && facts.decisionOptions.length > 0) {
+        // Issue #1898. The numbers are real here — they address a decision the
+        // agent is holding, not a line on a screen — so the guidance says which one
+        // to send instead of warning that none of them can be trusted.
+        parts.push(`Answer it with \`commandmate respond ${worktreeId} <number>\`: ` +
+            facts.decisionOptions
+                .map((option) => `${option.number} = ${option.label} (${option.reply})`)
+                .join(', ') +
+            `. The reply goes to the agent's own API, so no keys are sent to the terminal ` +
+            `and the label works too (\`respond ${worktreeId} "Allow once"\`).`);
+    }
+    else {
+        parts.push(`Answer it in the terminal, or send the option NUMBER with ` +
+            `\`commandmate respond ${worktreeId} <number>\` — yes/no is not resolved on a numbered ` +
+            `dialog (Issue #1681).`);
+    }
     if (facts.message) {
         parts.push(`Agent message: "${facts.message}"`);
     }
@@ -88,6 +127,9 @@ function buildStructuredPromptData(worktreeId, facts) {
         ...(facts.message ? { message: facts.message } : {}),
         ...(facts.toolName ? { toolName: facts.toolName } : {}),
         ...(facts.askUserQuestion ? { askUserQuestion: facts.askUserQuestion } : {}),
+        ...(facts.decisionOptions && facts.decisionOptions.length > 0
+            ? { decisionOptions: facts.decisionOptions }
+            : {}),
     };
 }
 /** The prompt-history row for a structured prompt the scraper never saw. */

package/dist/server/src/lib/session/waiting-episode-state.js

@@ -42,6 +42,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.onWaitingTransition = onWaitingTransition;
 exports.observeWaitingEdge = observeWaitingEdge;
 exports.getWaitingEpisode = getWaitingEpisode;
+exports.hasOpenWaitingEpisode = hasOpenWaitingEpisode;
 exports.clearWaitingEpisodes = clearWaitingEpisodes;
 exports.clearWaitingTransitionListeners = clearWaitingTransitionListeners;
 const auto_yes_state_1 = require("../../lib/auto-yes-state");
@@ -120,6 +121,29 @@ function observeWaitingEdge({ worktreeId, cliToolId, instanceId, waiting, kind =
 function getWaitingEpisode(worktreeId, cliToolId, instanceId) {
     return episodes.get((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId)) ?? null;
 }
+/**
+ * Whether **any** instance in this worktree is still waiting (Issue #2001).
+ *
+ * The cross-device dismissal is keyed on the worktree, because that is what the
+ * Service Worker `tag` names (`<worktreeId>:prompt`, `push-sender`): two agent
+ * instances waiting in one worktree share a single notification card on the
+ * phone. So one instance crossing the closing edge is not on its own a reason
+ * to clear that card — the card is still telling the truth until the last of
+ * them has been answered.
+ *
+ * The prefix test is exact rather than heuristic: `buildCompositeKey` puts the
+ * worktree id first and rejects a worktree id containing
+ * {@link COMPOSITE_KEY_SEPARATOR}, so no other worktree's key can start with
+ * `<worktreeId>:`.
+ */
+function hasOpenWaitingEpisode(worktreeId) {
+    const prefix = `${worktreeId}${auto_yes_state_1.COMPOSITE_KEY_SEPARATOR}`;
+    for (const key of episodes.keys()) {
+        if (key.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
 /**
  * Drop every episode. Test seam.
  *

package/dist/server/src/lib/tmux/key-sequence.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * The one place a {@link KeySequence} step becomes a `tmux send-keys` argv
+ * (Issue #1933, 受入条件 S9).
+ *
+ * ## What was wrong
+ *
+ * `tmux send-keys` resolves its positional argument against the key table
+ * before sending anything, and it parses its arguments with getopt. Neither
+ * fact was accounted for anywhere in this repository: `grep -n "'-l'"
+ * src/lib/tmux/*.ts` returned zero hits, and the user's message body is typed
+ * with `sendKeys(sessionName, message, false)`.
+ *
+ * Measured on tmux 3.5a against a private socket (`tmux -L …`), reading the
+ * bytes out of a pane running `cat` on a raw pty:
+ *
+ * | argv                                | bytes delivered              |
+ * |-------------------------------------|------------------------------|
+ * | `send-keys -t X 'Escape'`           | `1b`              (ESC key)  |
+ * | `send-keys -t X -l -- 'Escape'`     | `457363617065` -> `Escape`   |
+ * | `send-keys -t X 'Enter'`            | `0d`              (CR)       |
+ * | `send-keys -t X -l -- 'Enter'`      | `456e746572`   -> `Enter`    |
+ * | `send-keys -t X '-l'`               | **rc 0, nothing sent**       |
+ * | `send-keys -t X '-N hello'`         | rc 1, `repeat count invalid` |
+ * | `send-keys -t X -l -- '-l'`         | `2d6c`         -> `-l`       |
+ *
+ * So before this module a message whose body was exactly `Escape` interrupted
+ * the agent, `Enter` submitted an empty composer, `C-c` sent SIGINT, and a body
+ * beginning with `-` was silently discarded while the send reported success.
+ *
+ * ## Why `--` is on both branches
+ *
+ * The key branch takes a name from a five-value whitelist and could not
+ * collide, but a fixed argv shape is cheaper to reason about than one that
+ * changes with the payload, and the whitelist is re-checked here anyway (a
+ * JavaScript caller or an `as` cast can put anything in a typed field).
+ *
+ * ## Why the builder is separate from the sending
+ *
+ * {@link keySequenceArgs} is pure, so the property S9 asks for — *literal text
+ * always leaves through `-l`* — is pinned by inspecting an array rather than by
+ * trusting a spy on a wrapper. {@link runKeySequence} is the executor and takes
+ * its transport as a parameter, so a test drives the real sequencing (including
+ * the per-step delays) against a stub. `sendKeys(…, { literal: true })` in
+ * `./tmux` builds its argv here too, which is what makes the production
+ * message-body path and the pinned property the same code.
+ *
+ * ## Why these take a target rather than a session name
+ *
+ * `exactTarget()` lives in `./tmux`, and `./tmux` imports this module. Taking
+ * the already-resolved target keeps the dependency one-way instead of putting a
+ * cycle underneath every tmux caller — including the suites that replace
+ * `@/lib/tmux/tmux` with a factory mock, where a cycle would resolve
+ * `exactTarget` to whatever the mock happened to declare.
+ *
+ * @module lib/tmux/key-sequence
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keySequenceArgs = keySequenceArgs;
+exports.runKeySequence = runKeySequence;
+exports.describeKeySequence = describeKeySequence;
+const cli_tool_contracts_1 = require("../../types/cli-tool-contracts");
+/**
+ * The `tmux` arguments that send one step to a pane.
+ *
+ * @param target - An exact tmux target, i.e. `exactTarget(sessionName)`
+ * @param step - The keystroke or the text
+ * @returns Arguments for `execFile('tmux', …)` — never a shell string
+ * @throws Error when a key step names a key outside `KEY_SEQUENCE_KEY_NAMES`
+ *   (defense in depth against `as` casts and JavaScript callers)
+ */
+function keySequenceArgs(target, step) {
+    if (step.kind === 'literal') {
+        // `-l` stops the key-table lookup; `--` stops the getopt parse. Both are
+        // required: without `-l` a body of `Escape` is the ESC key, and without
+        // `--` a body of `-l` is consumed as a flag and nothing is sent at all.
+        return ['send-keys', '-t', target, '-l', '--', step.text];
+    }
+    if (!(0, cli_tool_contracts_1.isKeySequenceKeyName)(step.name)) {
+        throw new Error(`Invalid key sequence key name: ${step.name}`);
+    }
+    return ['send-keys', '-t', target, '--', step.name];
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Send a whole sequence, one tmux invocation per step.
+ *
+ * Never batched into a single `send-keys`: a TUI reading several keys out of one
+ * write treats them as a paste and can swallow the trailing submit — measured on
+ * opencode 1.18.21, where `send-keys '/exit' C-m` leaves the command palette
+ * open with `/exit` still in the composer 10.8 s later, 2 runs out of 2 (#1905).
+ *
+ * A step's `delayAfterMs` is awaited before the next step and is never applied
+ * after the last one.
+ *
+ * @param target - An exact tmux target, i.e. `exactTarget(sessionName)`
+ * @param steps - The sequence, in order
+ * @param transport - How one tmux invocation is run
+ * @param sleep - How a `delayAfterMs` is waited out (defaults to `setTimeout`)
+ */
+async function runKeySequence(target, steps, transport, sleep = defaultSleep) {
+    for (let index = 0; index < steps.length; index += 1) {
+        const step = steps[index];
+        await transport.run(keySequenceArgs(target, step));
+        const delay = step.delayAfterMs;
+        if (delay !== undefined && delay > 0 && index < steps.length - 1) {
+            await sleep(delay);
+        }
+    }
+}
+/**
+ * A sequence rendered for a log line or a test assertion.
+ *
+ * `key:Escape` / `text:/exit` — unambiguous because the prefix says which arm of
+ * the union the value came from, which is exactly the distinction that was
+ * missing from the code this Issue replaces.
+ */
+function describeKeySequence(steps) {
+    return steps.map((step) => (step.kind === 'literal' ? `text:${step.text}` : `key:${step.name}`));
+}

package/dist/server/src/lib/tmux/tmux.js

@@ -12,6 +12,7 @@ exports.hasSession = hasSession;
 exports.listSessions = listSessions;
 exports.createSession = createSession;
 exports.sendKeys = sendKeys;
+exports.sendKeySequence = sendKeySequence;
 exports.sendSpecialKeys = sendSpecialKeys;
 exports.capturePane = capturePane;
 exports.killSession = killSession;
@@ -19,6 +20,7 @@ exports.renameSession = renameSession;
 exports.ensureSession = ensureSession;
 exports.sendSpecialKey = sendSpecialKey;
 exports.clearInputLine = clearInputLine;
+exports.clearComposerLine = clearComposerLine;
 exports.isAllowedSpecialKey = isAllowedSpecialKey;
 exports.sendSpecialKeysAndInvalidate = sendSpecialKeysAndInvalidate;
 const child_process_1 = require("child_process");
@@ -27,6 +29,9 @@ const tmux_capture_cache_1 = require("./tmux-capture-cache");
 const validation_1 = require("../../lib/cli-tools/validation");
 const tmux_pane_config_1 = require("../../config/tmux-pane-config");
 const logger_1 = require("../../lib/logger");
+const terminal_keys_1 = require("../../types/terminal-keys");
+Object.defineProperty(exports, "NAVIGATION_KEY_VALUES", { enumerable: true, get: function () { return terminal_keys_1.NAVIGATION_KEY_VALUES; } });
+const key_sequence_1 = require("./key-sequence");
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
 const logger = (0, logger_1.createLogger)('tmux');
 /**
@@ -294,22 +299,31 @@ async function createSession(sessionNameOrOptions, cwd) {
  * @param sessionName - Target session name
  * @param keys - Keys to send (command text)
  * @param sendEnter - Whether to send Enter key after the command (default: true)
+ * @param options - {@link SendKeysOptions}; pass `{ literal: true }` for text
  *
- * @throws {Error} If session doesn't exist or command fails
+ * @throws {Error} If session doesn't exist, command fails, or `literal` is
+ *   combined with `sendEnter`
  *
  * @example
  * ```typescript
  * await sendKeys('my-session', 'echo hello');
  * await sendKeys('my-session', 'ls -la', true);
  * await sendKeys('my-session', 'incomplete command', false);
+ * // A message body the user typed — never resolved as a key name:
+ * await sendKeys('my-session', userMessage, false, { literal: true });
  * ```
  */
-async function sendKeys(sessionName, keys, sendEnter = true) {
+async function sendKeys(sessionName, keys, sendEnter = true, options) {
+    if (options?.literal && sendEnter) {
+        throw new Error('sendKeys: { literal: true } cannot be combined with sendEnter — a trailing C-m would be typed as text. Send Enter as a separate key.');
+    }
     // execFile() passes arguments directly without shell interpretation,
     // so no shell-level escaping is needed
-    const args = sendEnter
-        ? ['send-keys', '-t', exactTarget(sessionName), keys, 'C-m']
-        : ['send-keys', '-t', exactTarget(sessionName), keys];
+    const args = options?.literal
+        ? (0, key_sequence_1.keySequenceArgs)(exactTarget(sessionName), { kind: 'literal', text: keys })
+        : sendEnter
+            ? ['send-keys', '-t', exactTarget(sessionName), keys, 'C-m']
+            : ['send-keys', '-t', exactTarget(sessionName), keys];
     try {
         await execFileAsync('tmux', args, { timeout: DEFAULT_TIMEOUT });
     }
@@ -318,6 +332,49 @@ async function sendKeys(sessionName, keys, sendEnter = true) {
         throw new Error(`Failed to send keys to tmux session: ${errorMessage}`);
     }
 }
+/**
+ * Send a whole {@link KeySequence} to a session (Issue #1933).
+ *
+ * The executor half of `./key-sequence`, bound to this module's `execFile`
+ * transport. Literal steps go out through `send-keys -l --`, key steps through
+ * `send-keys --` after their name is re-validated, and each step is its own
+ * tmux invocation so a TUI cannot read the whole sequence as one paste.
+ *
+ * ## Status: the runner for `GracefulExitSpec.keys`, not yet its caller
+ *
+ * `ICLITool.gracefulExitSequence()` returns a `KeySequence[]`, so something has
+ * to be able to run one; this is that something, and
+ * `tests/unit/lib/key-sequence-1933.test.ts` drives it against a stubbed
+ * `execFile`. The seven `killSession()` implementations do **not** call it yet,
+ * and that is a deliberate scope line rather than an oversight: rerouting them
+ * changes the argv of calls that `tests/unit/api/kill-session-cli-tool-gateway-1905.test.ts`
+ * pins by exact arity, a file Issue #1933 may not edit — and it would buy no
+ * behaviour, because the exit strings (`/exit`, `/quit`) are tool-owned
+ * constants rather than tmux key names, so `-l` changes not one byte for them.
+ * The user-typed message body, which `-l` changes a great deal for, goes through
+ * {@link sendKeys}' `literal` option in the same commit. The Issue that is
+ * allowed to touch that gateway test owns the rest of the move;
+ * `tests/unit/cli-tools/graceful-exit-conformance-1933.test.ts` holds the
+ * declarations equal to the implementations until then.
+ *
+ * @param sessionName - Target session name
+ * @param steps - The sequence, in order
+ * @throws {Error} If a key name is not allowed, or a tmux command fails
+ */
+async function sendKeySequence(sessionName, steps) {
+    const transport = {
+        async run(args) {
+            await execFileAsync('tmux', args, { timeout: DEFAULT_TIMEOUT });
+        },
+    };
+    try {
+        await (0, key_sequence_1.runKeySequence)(exactTarget(sessionName), steps, transport);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to send key sequence to tmux session: ${errorMessage}`);
+    }
+}
 /**
  * Allowed tmux special key names for sendSpecialKeys() (multi-key TUI navigation).
  * Used for cursor-based navigation sequences (e.g., ['Down', 'Down', 'Enter']).
@@ -603,22 +660,37 @@ async function clearInputLine(sessionName) {
     }
 }
 /**
- * Allowed navigation key names for special-keys API validation.
- * Used for TUI navigation sequences (e.g., Up/Down cursor, Enter/Escape selection).
+ * Send one `C-e` + `C-u` pass over the TUI input line (Issue #1879).
  *
- * Separate from SPECIAL_KEY_VALUES (sendSpecialKey() control keys) and
- * ALLOWED_SPECIAL_KEYS (sendSpecialKeys() broader TUI key set).
- * This as const array is exported for route-level validation (immutable, DRY).
+ * `C-u` alone is kill-line-*before-cursor*, so it deletes nothing at all when the
+ * cursor sits at column 0 — the state a human leaves behind after pressing Home
+ * and walking away, measured live in #1878 §5-1. Moving to end-of-line first is
+ * what makes the kill unconditional. Both keys go in one `send-keys` so they
+ * cannot be interleaved with anything else the session receives.
  *
- * [DR3-001] Named NAVIGATION_KEY_VALUES to avoid collision with existing SPECIAL_KEY_VALUES.
- * [DR2-004] Exported as as const array + type guard (not Set) for immutability guarantee.
+ * One pass clears one row. A multi-row composer needs several (also measured in
+ * #1878 §5-1: up to `2N-1` for N rows), which is why callers drive this from
+ * {@link module:lib/session/composer-clear}'s read-back loop rather than firing
+ * it once and declaring victory.
+ *
+ * Like {@link clearInputLine}, the keys are fixed literals passed through
+ * execFile (no shell, no injection) and are deliberately NOT added to
+ * `ALLOWED_SPECIAL_KEYS` / `NAVIGATION_KEY_VALUES`: the special-keys API stays a
+ * navigation surface, and clearing the composer is its own endpoint with its own
+ * verification.
+ *
+ * @param sessionName - Target session name
+ * @throws {Error} If the tmux command fails
  */
-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',
-];
+async function clearComposerLine(sessionName) {
+    try {
+        await execFileAsync('tmux', ['send-keys', '-t', exactTarget(sessionName), 'C-e', 'C-u'], { timeout: DEFAULT_TIMEOUT });
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to clear tmux composer line: ${errorMessage}`);
+    }
+}
 /**
  * Type guard for navigation key validation (special-keys API).
  * Returns true if the key is in the NAVIGATION_KEY_VALUES set.
@@ -629,7 +701,7 @@ exports.NAVIGATION_KEY_VALUES = [
  * @returns True if key is a valid NavigationKey
  */
 function isAllowedSpecialKey(key) {
-    return exports.NAVIGATION_KEY_VALUES.includes(key);
+    return terminal_keys_1.NAVIGATION_KEY_VALUES.includes(key);
 }
 /**
  * Send special keys to a tmux session and invalidate the capture cache.