polygram 0.17.10 → 0.17.12

package/lib/tmux/startup-gate.js

@@ -1,250 +0,0 @@
-/**
- * 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

@@ -1,412 +0,0 @@
-/**
- * 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: `polygram-<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) {
-  const tail = threadId ? `${chatId}-${threadId}` : `${chatId}-main`;
-  return `polygram-${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 ~/.polygram/<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, '.polygram', 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({
-  logger = console,
-  runFn = run,
-} = {}) {
-  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 = `polygram-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 `polygram-*` 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 ? `polygram-${String(botName).replace(/[^\w-]/g, '_')}-` : 'polygram-';
-      return all.filter((n) => n.startsWith(prefix));
-    } catch {
-      return [];
-    }
-  }
-
-  return {
-    spawn,
-    sendControl,
-    pasteText,
-    pasteAndEnter,
-    capturePane,
-    captureWide,
-    sessionExists,
-    killSession,
-    listPolygramSessions,
-    sessionName,
-    debugLogPath,
-    ensureLogDir,
-    sanitize,
-    // Test hook
-    _run: runFn,
-  };
-}
-
-module.exports = {
-  createTmuxRunner,
-  sessionName,
-  debugLogPath,
-  sanitize,
-  MULTILINE_SEPARATOR,
-  CONTROL_CHAR_RE,
-};