@shumkov/orchestra 0.2.0

package/lib/tmux/startup-gate.js

@@ -0,0 +1,251 @@
+// provenance: polygram@0.17.11 lib/tmux/startup-gate.js (git 746bca6) — verbatim*: env prefix WATER_, bridge name water-bridge, vendor path (SHARED-LIB.md).
+/**
+ * runStartupGate — generic helper for "spawn a tmux'd TUI and wait until
+ * it's accepting input, sending Enter for known transient dialogs along
+ * the way".
+ *
+ * Extracted from CliProcess._handleStartupDialogs (M1 follow-on
+ * refactor). Made caller-agnostic so future TmuxProcess flows that need
+ * to navigate trust / dev-channels / approval-mode prompts can reuse
+ * it without duplicating the poll loop.
+ *
+ * Loop semantics:
+ *   - capture-pane every `pollMs` (default 300ms)
+ *   - if any trigger regex matches AND its `name` hasn't been seen, send
+ *     the trigger's `key` (typically 'Enter') via runner.sendControl
+ *   - after each send, wait `settleMs` (default 500ms) for the TUI to
+ *     transition out of the dialog before the next poll
+ *   - if `readySignal` regex matches the captured pane content, resolve
+ *   - if `Date.now()` exceeds the deadline, throw with `err.code = timeoutCode`
+ *
+ * Progress-aware (stall) deadline — `stallMs`:
+ *   The blind wall-clock `deadlineMs` can't tell "claude is mid-download
+ *   (24% progress bar, genuinely working)" from "claude is wedged". The
+ *   shumorobot General incident (2026-05-30) killed a cold-spawn that was
+ *   actively downloading the runtime. When `stallMs` is set, the gate
+ *   tracks pane ACTIVITY: any change in captured pane content — or a
+ *   trigger key being sent — resets a stall clock. The gate fails early
+ *   (with `timeoutCode`) only after `stallMs` elapses with NO activity,
+ *   i.e. the pane is frozen. `deadlineMs` remains an absolute backstop so
+ *   a pane that animates forever but never reaches `readySignal` still
+ *   terminates. When `stallMs` is omitted (default), behavior is the pure
+ *   `deadlineMs` wall-clock exactly as before.
+ *
+ * Each trigger is one-shot per gate run (tracked by `name` in a Set).
+ *
+ * Caller supplies:
+ *   - runner: object with `captureWide(tmuxName)` and `sendControl(tmuxName, key)`
+ *   - triggers: [{name, regex, key}] — order matters; first match wins
+ *   - readySignal: RegExp matching the "TUI is ready, no more dialogs" pane text
+ *   - deadlineMs, pollMs, settleMs — timeouts
+ *   - timeoutCode: err.code on deadline expiry (default 'TUI_STARTUP_TIMEOUT')
+ *   - logger, label — for diagnostic prose
+ */
+
+'use strict';
+
+const DEFAULT_DEADLINE_MS = 30_000;
+const DEFAULT_POLL_MS = 300;
+const DEFAULT_SETTLE_MS = 500;
+
+/**
+ * @param {object} opts
+ * @param {object} opts.runner                — tmux runner with captureWide + sendControl
+ * @param {string} opts.tmuxName              — tmux session name to poll
+ * @param {Array<{name:string, regex:RegExp, key:string}>} opts.triggers
+ * @param {RegExp} opts.readySignal           — match → resolve
+ * @param {number} [opts.deadlineMs=30000]    — absolute backstop
+ * @param {number} [opts.stallMs]             — if set, fail after this much
+ *   wall-clock with NO pane activity (progress-aware). Omit for pure
+ *   wall-clock behavior.
+ * @param {number} [opts.pollMs=300]
+ * @param {number} [opts.settleMs=500]
+ * @param {string} [opts.timeoutCode='TUI_STARTUP_TIMEOUT']
+ * @param {Function} [opts.onTrigger]          — (name) => void, called AT FIRE
+ *   TIME (not gate resolution). Telemetry hung off the success-path return
+ *   misses the matched-then-died sequence (2026-06-10 prod: gate matched
+ *   session-age, then TMUX_SESSION_GONE). Errors are swallowed.
+ * @param {object} [opts.logger=console]
+ * @param {string} [opts.label='startup-gate']
+ * @returns {Promise<{matchedTriggers: string[], elapsedMs: number}>}
+ */
+async function runStartupGate({
+  runner,
+  tmuxName,
+  triggers = [],
+  readySignal,
+  deadlineMs = DEFAULT_DEADLINE_MS,
+  stallMs,
+  pollMs = DEFAULT_POLL_MS,
+  settleMs = DEFAULT_SETTLE_MS,
+  timeoutCode = 'TUI_STARTUP_TIMEOUT',
+  onTrigger = null,
+  logger = console,
+  label = 'startup-gate',
+} = {}) {
+  if (!runner || typeof runner.captureWide !== 'function' || typeof runner.sendControl !== 'function') {
+    throw new TypeError('runStartupGate: runner must have captureWide + sendControl');
+  }
+  if (!tmuxName) throw new TypeError('runStartupGate: tmuxName required');
+  if (!(readySignal instanceof RegExp)) {
+    throw new TypeError('runStartupGate: readySignal must be a RegExp');
+  }
+
+  const startedAt = Date.now();
+  const deadline = startedAt + deadlineMs;
+  const stallEnabled = Number.isFinite(stallMs) && stallMs > 0;
+  const seen = new Set();
+  const matchedTriggers = [];
+  // rc.4: remember the most recent successful pane snapshot. If the gate
+  // fails (deadline OR session-gone), include the snapshot in the error
+  // so we can see what the TUI last printed before claude exited. Without
+  // this, "claude exits code 0 after dev-channels Enter" surfaces as a
+  // 30-second `can't find pane` spam with no diagnostic about WHY.
+  let lastPane = null;
+  // Progress-aware gate: timestamp of the last observed pane CHANGE (or
+  // trigger send). Only consulted when stallEnabled.
+  let lastActivityAt = startedAt;
+  // Music incident (2026-06-01): the stall timer must NOT arm while the pane
+  // is still BLANK. A blank-and-unchanging pane means claude hasn't started
+  // rendering yet (slow cold-start), NOT that it wedged — the TUI for some
+  // topics takes 30-45s to first-render. Arming the stall timer on a blank
+  // pane killed a legitimate slow spawn at stallMs with a false "wedged".
+  // So the stall clock only runs once the pane has shown non-whitespace
+  // content; before that, only the absolute `deadlineMs` governs.
+  let sawContent = false;
+
+  while (Date.now() < deadline) {
+    // Stall check (progress-aware): the pane RENDERED something and has then
+    // been static for stallMs → genuinely wedged. Gated on sawContent so a
+    // blank cold-start isn't mistaken for a wedge. Fires early so a truly
+    // hung TUI fails fast, while an actively-progressing one (download bar,
+    // dialog navigation) keeps resetting lastActivityAt below.
+    if (stallEnabled && sawContent && Date.now() - lastActivityAt >= stallMs) {
+      const err = new Error(
+        `[${label}] startup gate: pane rendered then went static for ${stallMs}ms for ${tmuxName} ` +
+        `(matched: ${matchedTriggers.length ? matchedTriggers.join(', ') : 'none'}). ` +
+        `Appears wedged. Last pane content:\n` +
+        _formatPaneTail(lastPane),
+      );
+      err.code = timeoutCode;
+      err.lastPane = lastPane;
+      err.matchedTriggers = matchedTriggers;
+      err.reason = 'stall';
+      throw err;
+    }
+    let pane;
+    try {
+      pane = await runner.captureWide(tmuxName);
+    } catch (err) {
+      // rc.4: detect "can't find pane" / "no server" — tmux session died
+      // (claude exited, killed the bash that hosted it, tmux tore down the
+      // pane). Fast-fail with a distinct code instead of spinning for the
+      // full deadline. Pattern matches the actual tmux capture-pane errors:
+      //   - "can't find pane: <name>"     (session/pane gone after spawn)
+      //   - "no server running"           (entire tmux server gone)
+      const msg = err?.message || '';
+      if (/can't find (pane|session)|no server running|session not found/i.test(msg)) {
+        const goneErr = new Error(
+          `[${label}] tmux session disappeared for ${tmuxName} after ${Date.now() - startedAt}ms ` +
+          `(matched: ${matchedTriggers.length ? matchedTriggers.join(', ') : 'none'}). ` +
+          `claude likely exited; last pane content:\n` +
+          _formatPaneTail(lastPane),
+        );
+        goneErr.code = 'TMUX_SESSION_GONE';
+        goneErr.lastPane = lastPane;
+        goneErr.matchedTriggers = matchedTriggers;
+        throw goneErr;
+      }
+      logger.warn?.(`[${label}] captureWide failed: ${msg}`);
+      await new Promise(r => setTimeout(r, settleMs));
+      continue;
+    }
+    // First non-whitespace content = the TUI has started rendering. Only
+    // from here does the stall timer become meaningful (before this, a blank
+    // pane is cold-start, governed by the absolute deadline). Seed
+    // lastActivityAt at the moment content first appears so the stall window
+    // is measured from "rendered", not from spawn.
+    if (!sawContent && pane && pane.trim().length > 0) {
+      sawContent = true;
+      lastActivityAt = Date.now();
+    }
+    // Progress signal: any change in pane content is activity → reset the
+    // stall clock. A captureWide that returns the SAME bytes is NOT
+    // activity (a frozen download bar at 24% reads identically each poll).
+    if (pane !== lastPane) lastActivityAt = Date.now();
+    lastPane = pane;
+
+    // Walk triggers in declaration order — first match (and not yet seen) wins
+    let matched = false;
+    for (const trigger of triggers) {
+      if (seen.has(trigger.name)) continue;
+      if (!trigger.regex.test(pane)) continue;
+      // `keys: [...]` sends a sequence (dialog navigation — e.g. Down,Enter
+      // to pick a non-default option); `key:` remains the single-key form.
+      // Sequence keys go as separate send-keys calls with a short delay —
+      // Ink dialogs can swallow the second key of a same-batch sequence.
+      const keySeq = Array.isArray(trigger.keys) ? trigger.keys : [trigger.key];
+      for (let ki = 0; ki < keySeq.length; ki++) {
+        if (ki > 0) await new Promise(r => setTimeout(r, Math.min(settleMs, 120)));
+        try {
+          await runner.sendControl(tmuxName, keySeq[ki]);
+        } catch (err) {
+          logger.warn?.(`[${label}] sendControl(${keySeq[ki]}) failed for trigger=${trigger.name}: ${err.message}`);
+        }
+      }
+      seen.add(trigger.name);
+      matchedTriggers.push(trigger.name);
+      try { onTrigger?.(trigger.name); } catch { /* telemetry must not break the gate */ }
+      matched = true;
+      // Sending a key is activity — navigating the TUI counts as progress
+      // even if the pre-transition pane text was static (e.g. a dialog we
+      // just answered). Reset the stall clock so we don't fail mid-nav.
+      lastActivityAt = Date.now();
+      // Settle window so the TUI transitions out of the dialog before next poll
+      await new Promise(r => setTimeout(r, settleMs));
+      break;
+    }
+    if (matched) continue;
+
+    if (readySignal.test(pane)) {
+      return { matchedTriggers, elapsedMs: Date.now() - startedAt };
+    }
+
+    await new Promise(r => setTimeout(r, pollMs));
+  }
+
+  const err = new Error(
+    `[${label}] startup gate did not resolve within ${deadlineMs}ms for ${tmuxName} ` +
+    `(matched: ${matchedTriggers.length ? matchedTriggers.join(', ') : 'none'}). ` +
+    `Last pane content:\n` +
+    _formatPaneTail(lastPane),
+  );
+  err.code = timeoutCode;
+  err.lastPane = lastPane;
+  err.matchedTriggers = matchedTriggers;
+  throw err;
+}
+
+/**
+ * Render the last ~800 chars of pane content for inclusion in error messages.
+ * Truncate at line boundaries when possible so the diagnostic isn't visually
+ * mangled. Returns "(no pane content ever captured)" for null/undefined.
+ */
+function _formatPaneTail(pane) {
+  if (!pane) return '  (no pane content ever captured — claude exited before first captureWide)';
+  const MAX = 800;
+  const text = String(pane);
+  if (text.length <= MAX) return text.split('\n').map(l => '  ' + l).join('\n');
+  // Take last MAX chars, then trim to a line boundary if one exists nearby
+  let tail = text.slice(-MAX);
+  const nl = tail.indexOf('\n');
+  if (nl > 0 && nl < 80) tail = tail.slice(nl + 1);
+  return '  …(truncated)…\n' + tail.split('\n').map(l => '  ' + l).join('\n');
+}
+
+module.exports = {
+  runStartupGate,
+  DEFAULT_DEADLINE_MS,
+  DEFAULT_POLL_MS,
+  DEFAULT_SETTLE_MS,
+};

package/lib/tmux/tmux-runner.js

@@ -0,0 +1,415 @@
+// provenance: polygram@0.17.11 lib/tmux/tmux-runner.js (git 746bca6) — verbatim*: env prefix WATER_, bridge name water-bridge, vendor path (SHARED-LIB.md).
+/**
+ * Low-level tmux wrapper used by TmuxProcess (`lib/process/tmux-process.js`).
+ *
+ * Pure mechanics — spawn / send / capture / kill / list. No semantics
+ * about claude or polygram. TmuxProcess composes these into the
+ * higher-level send-prompt / observe-turn / interrupt flow.
+ *
+ * Conventions:
+ *   - Session names are bot-prefixed to avoid cross-bot collision
+ *     on the same host: `water-<bot>-<chat>-<thread>`.
+ *   - Prompt bodies go through pasteText() (sanitize + multiline
+ *     separator + set-buffer/paste-buffer).
+ *   - Control keys (Enter, Escape, C-c) go through sendControl()
+ *     using `tmux send-keys` (no -l flag).
+ *
+ * Phase 0 spike findings encoded here:
+ *   F-spike-1  --permission-mode acceptEdits handled by callers
+ *   F-spike-3  `\n` in paste-buffer SPLITS into separate Enter
+ *              presses → encode as MULTILINE_SEPARATOR before paste
+ *   F-spike-4  bypassPermissions needs --dangerously-skip-permissions
+ *              companion (callers add this flag pair when needed)
+ *   G5b        sanitize() strips C0/DEL control bytes so a Telegram
+ *              user can't inject Ctrl-C / Ctrl-D into the pty
+ *
+ * @see docs/0.10.0-phase0-spike-findings.md F-spike-1..4
+ * @see docs/0.10.0-process-manager-abstraction-plan.md §12.4
+ */
+
+'use strict';
+
+const childProcess = require('child_process');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { createAsyncLock } = require('../async-lock');
+
+// ─── Constants ───────────────────────────────────────────────────────
+
+// Phase 0 F-spike-3: `\n` in paste-buffer triggers separate Enter
+// presses in claude TUI; only the LAST line stays. Encode as a visible
+// separator before paste so the full multi-line prompt arrives.
+const MULTILINE_SEPARATOR = ' / ';
+
+// G5b: strip C0/DEL bytes (0x00-0x08, 0x0b-0x1f, 0x7f) from prompt
+// before send. Allows \t (0x09) and \n (0x0a) through; we handle \n
+// via MULTILINE_SEPARATOR.
+const CONTROL_CHAR_RE = /[\x00-\x08\x0b-\x1f\x7f]/g;
+
+// 2026-05-18 incident — submit confirmation now lives in TmuxProcess.
+// A ~1-2KB polygram prompt is collapsed by the claude TUI into a
+// "[Pasted text #N]" placeholder; the single post-paste Enter can be
+// absorbed mid-ingest, leaving the prompt unsubmitted.
+//
+// B5 confirmed the submit HERE by capture-pane (does the input box
+// still hold the paste?). That FALSE-POSITIVED: the TUI renders the
+// collapsed-paste placeholder asynchronously, so a capture-pane poll
+// catches a transient frame where the placeholder is not yet visible
+// and B5 wrongly concluded "submitted ✓", leaving the prompt stuck
+// (3rd recurrence: shumorobot msg 803, 2026-05-19). B7 REMOVED the
+// capture-pane confirm — capture-pane is an unreliable signal for a
+// collapsed paste. Submission is now confirmed in `TmuxProcess` by the
+// paste's correlation token surfacing in a JSONL `user-message` (the
+// only reliable "the prompt reached claude" signal). The runner just
+// pastes + Enter; it no longer judges whether the submit landed.
+
+// ─── execFile wrapper ────────────────────────────────────────────────
+
+// Every tmux invocation polygram makes — capture-pane, send-keys,
+// set-buffer, paste-buffer, has-session, list-sessions, kill-session,
+// and even `new-session -d` (which detaches immediately) — is a
+// sub-second operation. A tmux call that runs longer than this is
+// WEDGED (tmux server hung, host pathologically loaded).
+//
+// Without a bound, a wedged subprocess hangs the `await` forever:
+// `_awaitTurnComplete`'s poll loop re-checks its deadline only
+// BETWEEN `captureWide` calls, so a single hung `capture-pane` stalls
+// the turn with no timeout (leftover R7). The 2026-05-18 submit-
+// confirm loop has the same exposure — it capture-panes too.
+//
+// A per-exec timeout bounds ALL of it: a timed-out tmux call rejects
+// → the caller throws → the turn fails LOUD with an error instead of
+// hanging. killSignal is SIGKILL because a wedged process may ignore
+// SIGTERM. 10s is generous headroom over the sub-second norm.
+const TMUX_RUN_TIMEOUT_MS = 10_000;
+
+/**
+ * Promise-wrapped childProcess.execFile. Returns { stdout, stderr }.
+ * Rejects on non-zero exit (or timeout) with err.stdout + err.stderr
+ * attached. A default timeout + SIGKILL bound every tmux call so a
+ * wedged subprocess cannot hang a turn (leftover R7); an explicit
+ * `opts.timeout` still overrides.
+ */
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    childProcess.execFile(
+      cmd,
+      args,
+      { timeout: TMUX_RUN_TIMEOUT_MS, killSignal: 'SIGKILL', ...opts, encoding: 'utf8' },
+      (err, stdout, stderr) => {
+        if (err) {
+          err.stdout = stdout;
+          err.stderr = stderr;
+          return reject(err);
+        }
+        resolve({ stdout, stderr });
+      },
+    );
+  });
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Strip C0/DEL control characters. Allow \t and \n (\n is then
+ * encoded to MULTILINE_SEPARATOR by pasteText below).
+ */
+function sanitize(text) {
+  return String(text).replace(CONTROL_CHAR_RE, '');
+}
+
+/**
+ * Bot-prefixed tmux session name. Replaces unsafe chars with _ so
+ * the name is always a valid tmux session identifier.
+ *
+ * @param {string} botName
+ * @param {string|number} chatId
+ * @param {string|number|null} threadId
+ */
+function sessionName(botName, chatId, threadId, prefix = 'orchestra') {
+  const tail = threadId ? `${chatId}-${threadId}` : `${chatId}-main`;
+  return `${prefix}-${botName}-${tail}`.replace(/[^\w-]/g, '_');
+}
+
+/**
+ * Per-session debug-log path. Same sanitization as session name so
+ * an admin typo in a topic key can't path-traverse.
+ *
+ * Per R2-F5 the path lives under polygram's own data dir, not /tmp.
+ *
+ * @param {string} botName
+ * @param {string|number} chatId
+ * @param {string|number|null} threadId
+ * @param {string} [logsDir]  base dir; default ~/.water/<bot>/logs
+ */
+function debugLogPath(botName, chatId, threadId, logsDir) {
+  const safeBot = String(botName).replace(/[^\w-]/g, '_');
+  const tail = threadId ? `${chatId}-${threadId}` : `${chatId}-main`;
+  const safeTail = String(tail).replace(/[^\w-]/g, '_');
+  // SECURITY (audit M4): refuse to fall back to /tmp when HOME is
+  // unset. /tmp is world-writable; a co-tenant could pre-create the
+  // path as a symlink pointing at an arbitrary file, and claude's
+  // --debug-file flag would follow it on open-for-append. Operators
+  // running polygram must have HOME set; if not, this is a misconfig
+  // that should fail loud.
+  if (!logsDir && !process.env.HOME) {
+    throw Object.assign(
+      new Error('HOME env var unset; refusing /tmp fallback for debugLogPath'),
+      { code: 'HOME_UNSET' },
+    );
+  }
+  const base = logsDir || path.join(process.env.HOME, '.orchestra', safeBot, 'logs');
+  return path.join(base, `tmux-claude-${safeTail}.log`);
+}
+
+/**
+ * Ensure the directory exists for a debug log path. Idempotent.
+ */
+function ensureLogDir(logPath) {
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+}
+
+// ─── TmuxRunner ──────────────────────────────────────────────────────
+
+/**
+ * Construct a tmux runner. Returns an object of methods. Stateless —
+ * each call is an independent tmux invocation. The shared `logger` is
+ * the only injected dependency.
+ *
+ * Test seam: tests can stub `runner._run` to mock execFile.
+ *
+ * @param {object} [opts]
+ * @param {object} [opts.logger=console]
+ * @param {Function} [opts.runFn] — override the underlying execFile
+ *   wrapper (for tests). Same signature: (cmd, args, opts?) → Promise.
+ */
+function createTmuxRunner({
+  sessionPrefix = 'orchestra',
+  logger = console,
+  runFn = run,
+} = {}) {
+  const runnerPrefix = sessionPrefix;
+  async function spawn({
+    name,
+    cwd,
+    command,
+    args = [],
+    envExtras = {},
+    paneWidth = 200,
+  }) {
+    // SECURITY (audit M5): paneWidth ends up as a CLI arg to `tmux
+    // set-option`. We use execFile (no shell), so this is not a
+    // shell-injection vector — but a hostile value like '-Force' or
+    // a number-string with embedded options could be mis-parsed by
+    // tmux. Validate it's a small positive integer.
+    if (!Number.isInteger(paneWidth) || paneWidth < 20 || paneWidth > 10_000) {
+      throw new TypeError(`paneWidth must be an integer in [20, 10000], got ${paneWidth}`);
+    }
+    const sessArgs = ['new-session', '-d', '-s', name];
+    if (cwd) sessArgs.push('-c', cwd);
+    for (const [k, v] of Object.entries(envExtras)) {
+      sessArgs.push('-e', `${k}=${v}`);
+    }
+    sessArgs.push(command, ...args);
+    try {
+      await runFn('tmux', sessArgs);
+    } catch (err) {
+      throw Object.assign(new Error(`tmux spawn failed: ${err.message}`), {
+        code: 'TMUX_SPAWN_FAILED',
+        name,
+        cause: err,
+        stderr: err.stderr,
+      });
+    }
+    // Try to widen the detached pane so claude TUI has room to render
+    // long lines. `resize-window` is the supported way; older
+    // attempts used a non-existent `pane-width` option that always
+    // errored (tmux 3.x: pane-width is a format variable, not a
+    // settable option). capture-pane -J in captureWide() handles
+    // any remaining wrap artifacts.
+    try {
+      await runFn('tmux', ['resize-window', '-t', name, '-x', String(paneWidth)]);
+    } catch (err) {
+      logger.debug?.(`[tmux-runner] resize-window failed for ${name}: ${err.message} (capture-pane -J handles wrap)`);
+    }
+    return name;
+  }
+
+  /**
+   * Send raw key sequence (Enter, Escape, C-c, etc.). NOT for prompt
+   * body — use pasteText for that. send-keys without -l interprets
+   * key names like "Enter" and "C-c".
+   */
+  async function sendControl(name, key) {
+    await runFn('tmux', ['send-keys', '-t', name, key]);
+  }
+
+  // rc.13.1: paste+Enter must be ATOMIC per session. Pre-rc.13.1 two
+  // concurrent pasteText+sendControl pairs could interleave in the
+  // TUI's bracketed-paste buffer — Ivan caught this on shumorobot
+  // 2026-05-15 (the 2233-char user JSONL entry contained one
+  // truncated polygram channel + a full nested polygram prompt for
+  // a different msg_id). Symptom: msg 696's paste was at byte
+  // `chat_id="-1003` when msg 698's autosteer paste cut in,
+  // concatenating two pastes into one TUI user message → the agent
+  // saw a malformed input → the reply attribution went sideways
+  // (msg 697 got msg 698's answer, msg 696 got served last).
+  //
+  // The async-lock is keyed by tmux session name, so different
+  // sessions don't block each other. Within one session, pasteText
+  // + sendControl(Enter) hold the lock atomically.
+  const inputLock = createAsyncLock();
+  /**
+   * Paste a prompt body + press Enter, atomically per session.
+   *
+   * Pure mechanics: paste, Enter, a small post-Enter drain. The runner
+   * does NOT judge whether the submit landed — B7 moved submit
+   * confirmation to `TmuxProcess`, which confirms it via the paste's
+   * correlation token surfacing in a JSONL `user-message` (the only
+   * reliable signal; capture-pane false-positives on a collapsed
+   * `[Pasted text #N]` placeholder).
+   *
+   * @param {string} name  tmux session
+   * @param {string} text  prompt body
+   */
+  async function pasteAndEnter(name, text) {
+    const release = await inputLock.acquire(name);
+    try {
+      const res = await pasteText(name, text);
+      await sendControl(name, 'Enter');
+      // L3 fix: small post-Enter drain so back-to-back
+      // pasteAndEnter calls don't race in the claude TUI's input
+      // handler. Pre-fix, when two injectUserMessage calls fired in
+      // quick succession (spike multi-2-rapid, ~2/5 failure rate),
+      // the TUI sometimes only enqueued ONE of the two pastes —
+      // the second's bracketed-paste-start collided with the first
+      // Enter's processing. 50ms is enough on the TUI we tested
+      // against (claude v2.1.142); see AGENTS.md pinned version.
+      await new Promise((r) => setTimeout(r, 50));
+      return res;
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Push a multi-line text prompt into the pane.
+   *
+   *   1. sanitize()  strips C0/DEL bytes (G5b)
+   *   2. \n → MULTILINE_SEPARATOR  (F-spike-3)
+   *   3. set-buffer + paste-buffer  (atomic; bracketed-paste-aware
+   *      in modern claude TUI versions)
+   *   4. brief drain delay so a subsequent send-keys (e.g. Enter) is
+   *      processed as a key event by the TUI, NOT consumed as part of
+   *      the paste's bracketed-paste content.
+   *
+   * INCIDENT (0.10.0-rc.2): without the drain delay, send-keys Enter
+   * fired immediately after paste-buffer was being swallowed by
+   * claude TUI's bracketed-paste handler — the paste sat in the input
+   * area unsubmitted. Manual `tmux send-keys ... Enter` unstuck it.
+   * 80ms is enough on macOS tmux 3.6a for the close-bracket ESC[201~
+   * to land before any subsequent key arrives.
+   *
+   * NO Enter is sent here. Caller follows up with
+   * `sendControl(name, 'Enter')` when they want to submit.
+   */
+  async function pasteText(name, text) {
+    const sanitized = sanitize(text);
+    const oneLine = sanitized.replace(/\r?\n/g, MULTILINE_SEPARATOR);
+    const bufName = `${runnerPrefix}-buf-${crypto.randomBytes(3).toString('hex')}`;
+    await runFn('tmux', ['set-buffer', '-b', bufName, oneLine]);
+    try {
+      // -d (delete after) so the buffer doesn't accumulate.
+      await runFn('tmux', ['paste-buffer', '-t', name, '-b', bufName, '-d']);
+    } catch (err) {
+      // Best-effort buffer cleanup if paste fails.
+      await runFn('tmux', ['delete-buffer', '-b', bufName]).catch(() => {});
+      throw err;
+    }
+    // Drain delay — see incident note above.
+    await new Promise((r) => setTimeout(r, 80));
+    return { sanitized, oneLine, stripped: text.length - sanitized.length };
+  }
+
+  /**
+   * Capture pane content. By default returns the last 1000 lines with
+   * line-wrapped lines joined (`-J`) — handles wrapping artifacts
+   * regardless of pane-width setting.
+   *
+   * For frequent polling (ready/streaming/approval-prompt detection),
+   * pass a smaller `lines` value — the indicators all live in the
+   * bottom ~50 lines of the pane. Polling 1000 lines each poll spawns
+   * a heavier tmux capture subprocess unnecessarily.
+   */
+  async function capturePane(name, { lines = 1000, joinWrapped = true } = {}) {
+    const args = ['capture-pane', '-t', name, '-p'];
+    if (joinWrapped) args.push('-J');
+    args.push('-S', `-${lines}`);
+    const { stdout } = await runFn('tmux', args);
+    return stdout;
+  }
+
+  /**
+   * Wide capture — alias for capturePane with -J always on. Use when
+   * regex parsing is sensitive to line wrapping.
+   */
+  async function captureWide(name, opts = {}) {
+    return capturePane(name, { ...opts, joinWrapped: true });
+  }
+
+  async function sessionExists(name) {
+    try {
+      await runFn('tmux', ['has-session', '-t', name]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async function killSession(name) {
+    await runFn('tmux', ['kill-session', '-t', name]).catch(() => {});
+  }
+
+  /**
+   * List polygram-managed tmux sessions on the host. Optional `botName`
+   * narrows the prefix; without it returns all `water-*` sessions.
+   */
+  async function listPolygramSessions(botName = null) {
+    try {
+      const { stdout } = await runFn('tmux', ['list-sessions', '-F', '#{session_name}']);
+      const all = stdout.trim().split('\n').filter(Boolean);
+      const prefix = botName ? `${runnerPrefix}-${String(botName).replace(/[^\w-]/g, '_')}-` : `${runnerPrefix}-`;
+      return all.filter((n) => n.startsWith(prefix));
+    } catch {
+      return [];
+    }
+  }
+
+  return {
+    spawn,
+    sendControl,
+    pasteText,
+    pasteAndEnter,
+    capturePane,
+    captureWide,
+    sessionExists,
+    killSession,
+    listPolygramSessions,
+    sessionName: (b, c, t) => sessionName(b, c, t, sessionPrefix),
+    debugLogPath,
+    ensureLogDir,
+    sanitize,
+    // Test hook
+    _run: runFn,
+  };
+}
+
+module.exports = {
+  createTmuxRunner,
+  sessionName,
+  debugLogPath,
+  sanitize,
+  MULTILINE_SEPARATOR,
+  CONTROL_CHAR_RE,
+};