botmux 2.86.0 → 2.88.0

package/dist/utils/install-info.js

@@ -40,6 +40,12 @@ export function botmuxVersion() {
 export function botmuxCliEntry() {
     return join(packageRoot(), 'dist', 'cli.js');
 }
+/** Absolute path to this install's root (the dir holding package.json). For a
+ *  source checkout this is the git working tree — used to derive a real version
+ *  via `git describe` when package.json is the unbuilt 0.0.0. */
+export function botmuxInstallRoot() {
+    return packageRoot();
+}
 /** Walk up from this module to the nearest dir containing package.json. */
 function packageRoot() {
     let dir = dirname(fileURLToPath(import.meta.url));

package/dist/utils/install-info.js.map

@@ -1 +1 @@
-{"version":3,"file":"install-info.js","sourceRoot":"","sources":["../../src/utils/install-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED,IAAI,MAA2B,CAAC;AAEhC,2EAA2E;AAC3E,MAAM,UAAU,iBAAiB;IAC/B,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,GAAG,mBAAmB,CAAC,WAAW,EAAE,CAAC,CAAC;IACtE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;yEAEyE;AACzE,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACnF,OAAO,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;+CAE+C;AAC/C,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED,2EAA2E;AAC3E,SAAS,WAAW;IAClB,IAAI,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAClD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QACtD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"install-info.js","sourceRoot":"","sources":["../../src/utils/install-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED,IAAI,MAA2B,CAAC;AAEhC,2EAA2E;AAC3E,MAAM,UAAU,iBAAiB;IAC/B,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,GAAG,mBAAmB,CAAC,WAAW,EAAE,CAAC,CAAC;IACtE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;yEAEyE;AACzE,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACnF,OAAO,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;+CAE+C;AAC/C,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED;;iEAEiE;AACjE,MAAM,UAAU,iBAAiB;IAC/B,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AAED,2EAA2E;AAC3E,SAAS,WAAW;IAClB,IAAI,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAClD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QACtD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/utils/stdio-epipe-guard.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Suppress EPIPE-class crashes on process.stdout / process.stderr.
+ *
+ * When botmux runs under pm2, the daemon's and each worker's stdout/stderr are
+ * pipes to the pm2 God daemon (→ out_file / error_file). If the reader end
+ * detaches — pm2 log streaming stops, the God daemon restarts, `botmux logs`
+ * is piped to a command that exits early (e.g. `| head`), or the terminal
+ * closes mid-stream — the next write fails with EPIPE. Because a piped
+ * stdout/stderr is a Socket, the failed write surfaces as an 'error' event;
+ * with no listener Node escalates it to an uncaughtException.
+ *
+ * That is fatal for botmux: the daemon registers no global uncaughtException
+ * handler (so a broken pipe would kill the whole daemon), and the worker's
+ * handler calls process.exit(1) on any uncaught error (so a broken pipe would
+ * take down a live CLI session). The real logs are captured by pm2's out/err
+ * files regardless, so the correct behavior is to drop the failed write
+ * silently and keep running rather than crash.
+ *
+ * Attaching an 'error' listener that ignores the broken-pipe family achieves
+ * exactly that. Genuinely unexpected stream errors are re-thrown so they still
+ * surface (i.e. behavior for non-broken-pipe errors is unchanged).
+ */
+/** True if `err` is a broken-pipe-class stream error that is safe to swallow. */
+export declare function isIgnorableStreamError(err: NodeJS.ErrnoException | null | undefined): boolean;
+/**
+ * Attach a broken-pipe-tolerant 'error' listener to a single stream. Exported
+ * for unit testing with an injected EventEmitter.
+ */
+export declare function attachStreamErrorGuard(stream: NodeJS.EventEmitter): void;
+/**
+ * Install the guard on process.stdout/stderr. Idempotent — safe to call from
+ * multiple entry points (daemon, worker). Returns true if it installed this
+ * call, false if it was already installed.
+ *
+ * `streams` defaults to the real process streams; it is parameterized only so
+ * unit tests can inject fakes without touching the test runner's own stdio.
+ */
+export declare function installStdioEpipeGuard(streams?: NodeJS.EventEmitter[]): boolean;
+//# sourceMappingURL=stdio-epipe-guard.d.ts.map

package/dist/utils/stdio-epipe-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-epipe-guard.d.ts","sourceRoot":"","sources":["../../src/utils/stdio-epipe-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAeH,iFAAiF;AACjF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,CAAC,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE7F;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,YAAY,GAAG,IAAI,CAOxE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,MAAM,CAAC,YAAY,EAAqC,GAChE,OAAO,CAKT"}

package/dist/utils/stdio-epipe-guard.js

@@ -0,0 +1,67 @@
+/**
+ * Suppress EPIPE-class crashes on process.stdout / process.stderr.
+ *
+ * When botmux runs under pm2, the daemon's and each worker's stdout/stderr are
+ * pipes to the pm2 God daemon (→ out_file / error_file). If the reader end
+ * detaches — pm2 log streaming stops, the God daemon restarts, `botmux logs`
+ * is piped to a command that exits early (e.g. `| head`), or the terminal
+ * closes mid-stream — the next write fails with EPIPE. Because a piped
+ * stdout/stderr is a Socket, the failed write surfaces as an 'error' event;
+ * with no listener Node escalates it to an uncaughtException.
+ *
+ * That is fatal for botmux: the daemon registers no global uncaughtException
+ * handler (so a broken pipe would kill the whole daemon), and the worker's
+ * handler calls process.exit(1) on any uncaught error (so a broken pipe would
+ * take down a live CLI session). The real logs are captured by pm2's out/err
+ * files regardless, so the correct behavior is to drop the failed write
+ * silently and keep running rather than crash.
+ *
+ * Attaching an 'error' listener that ignores the broken-pipe family achieves
+ * exactly that. Genuinely unexpected stream errors are re-thrown so they still
+ * surface (i.e. behavior for non-broken-pipe errors is unchanged).
+ */
+/**
+ * Error codes that mean "the other end of stdout/stderr went away". These are
+ * benign for a long-lived process whose real logs live in pm2's files.
+ */
+const IGNORED_STREAM_ERROR_CODES = new Set([
+    'EPIPE',
+    'ERR_STREAM_DESTROYED',
+    'ECONNRESET',
+    'EOF',
+]);
+let installed = false;
+/** True if `err` is a broken-pipe-class stream error that is safe to swallow. */
+export function isIgnorableStreamError(err) {
+    return !!err && IGNORED_STREAM_ERROR_CODES.has(err.code ?? '');
+}
+/**
+ * Attach a broken-pipe-tolerant 'error' listener to a single stream. Exported
+ * for unit testing with an injected EventEmitter.
+ */
+export function attachStreamErrorGuard(stream) {
+    stream.on('error', (err) => {
+        if (isIgnorableStreamError(err))
+            return;
+        // Not a broken pipe — re-throw so genuinely unexpected stream errors still
+        // surface (same outcome as having no listener at all for these codes).
+        throw err;
+    });
+}
+/**
+ * Install the guard on process.stdout/stderr. Idempotent — safe to call from
+ * multiple entry points (daemon, worker). Returns true if it installed this
+ * call, false if it was already installed.
+ *
+ * `streams` defaults to the real process streams; it is parameterized only so
+ * unit tests can inject fakes without touching the test runner's own stdio.
+ */
+export function installStdioEpipeGuard(streams = [process.stdout, process.stderr]) {
+    if (installed)
+        return false;
+    installed = true;
+    for (const stream of streams)
+        attachStreamErrorGuard(stream);
+    return true;
+}
+//# sourceMappingURL=stdio-epipe-guard.js.map

package/dist/utils/stdio-epipe-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-epipe-guard.js","sourceRoot":"","sources":["../../src/utils/stdio-epipe-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;GAGG;AACH,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAC;IACzC,OAAO;IACP,sBAAsB;IACtB,YAAY;IACZ,KAAK;CACN,CAAC,CAAC;AAEH,IAAI,SAAS,GAAG,KAAK,CAAC;AAEtB,iFAAiF;AACjF,MAAM,UAAU,sBAAsB,CAAC,GAA6C;IAClF,OAAO,CAAC,CAAC,GAAG,IAAI,0BAA0B,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA2B;IAChE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAA0B,EAAE,EAAE;QAChD,IAAI,sBAAsB,CAAC,GAAG,CAAC;YAAE,OAAO;QACxC,2EAA2E;QAC3E,uEAAuE;QACvE,MAAM,GAAG,CAAC;IACZ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAiC,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC;IAEjE,IAAI,SAAS;QAAE,OAAO,KAAK,CAAC;IAC5B,SAAS,GAAG,IAAI,CAAC;IACjB,KAAK,MAAM,MAAM,IAAI,OAAO;QAAE,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/worker.js

@@ -13,16 +13,19 @@
  *   7. On 'restart', kills CLI and re-spawns with --resume
  */
 import { randomBytes } from 'node:crypto';
-import { mkdirSync, unlinkSync, existsSync, statSync, readdirSync, readlinkSync, readFileSync, watch as fsWatch, createWriteStream } from 'node:fs';
+import { mkdirSync, writeFileSync, unlinkSync, existsSync, statSync, readdirSync, readlinkSync, readFileSync, watch as fsWatch, createWriteStream } from 'node:fs';
 import { atomicWriteFileSync } from './utils/atomic-write.js';
 import { isAbsolute, join } from 'node:path';
 import { drainTranscript, joinAssistantText, trailingAssistantText, findJsonlContainingFingerprint, findJsonlsContainingExactContent, findLatestJsonl, extractLastAssistantTurn, extractTurnStartText, splitTranscriptEventsByCutoff } from './services/claude-transcript.js';
 import { BridgeTurnQueue, makeFingerprint, normaliseForFingerprint } from './services/bridge-turn-queue.js';
 import { shouldSuppressBridgeEmit } from './services/bridge-fallback-gate.js';
-import { shouldWriteNow } from './utils/input-gate.js';
+import { shouldReleaseFirstPromptTimeout, shouldWriteNow } from './utils/input-gate.js';
+import { stripAnsiForLog, tailChars } from './utils/crash-log.js';
+import { installStdioEpipeGuard, isIgnorableStreamError } from './utils/stdio-epipe-guard.js';
 import { mergeQueuedCliInput } from './utils/pending-input-queue.js';
 import { ReadyGate, shouldArmReadyGate } from './utils/ready-gate.js';
 import { shouldRunStartupCommandsOnSpawn, shouldDeferInitialPromptForStartup } from './core/startup-commands.js';
+import { sanitizePerBotEnv } from './core/per-bot-env.js';
 import { InflightInputTracker } from './core/inflight-input-tracker.js';
 import { shouldRunQuietRotation, evaluatePidResolverPullback, decideFingerprintSwitch, shouldHealAbsentBaseline, sessionIdFromJsonlPath, SESSION_ID_FILENAME_RE, } from './services/bridge-rotation-policy.js';
 import { CodexBridgeQueue } from './services/codex-bridge-queue.js';
@@ -104,6 +107,17 @@ let lastSpawnEffectiveResume = false;
 let lastSpawnEffectiveCliSessionId;
 let idleDetector = null;
 let isTmuxMode = false;
+/** True once a crash diagnostic tmux shell (bmx-diag-<sid>) is live. */
+let crashDiagnosticTmuxParked = false;
+/** True once the daemon told us to stop & park a crash diagnostic (crash loop):
+ *  the next user message retries the CLI. Distinct from the flag above because
+ *  retry must still fire even if the tmux park itself failed (no hang). */
+let crashDiagnosticStopped = false;
+/** Exit code/signal of the just-exited CLI, stashed so a deferred park
+ *  (park_diagnostic IPC) can stamp the captured log even though the park no
+ *  longer happens inline in onExit. */
+let lastCliExitCode = null;
+let lastCliExitSignal = null;
 /** Adopt-bridge mode using TmuxPipeBackend: not a tmux attach client, all
  *  web-terminal updates flow through the shared scrollback fan-out instead
  *  of per-WS attach-session PTYs. Set in spawnCli's adopt branch. */
@@ -163,6 +177,14 @@ let readySignalTimer = null;
  *  back. The real signal lands within ~ms of the input box rendering, so this is
  *  pure insurance against a missing/failed hook — generous but bounded. */
 const READY_SIGNAL_TIMEOUT_MS = 45_000;
+/** Soft fallback for CLIs that never emit an idle/ready signal during startup.
+ *  Legacy adapters release queued first input here. Adapters that opt into
+ *  deferFirstPromptTimeoutUntilReady wait for the real readyPattern until the
+ *  hard cap below. */
+const FIRST_PROMPT_TIMEOUT_MS = 15_000;
+/** Hard cap for startup screens that outlive the soft fallback. Prevents a
+ *  changed/missing readyPattern from trapping the first queued input forever. */
+const FIRST_PROMPT_HARD_TIMEOUT_MS = 90_000;
 /** Epoch ms of the most recent PTY output — used to settle for quiescence
  *  before the first flush (see settleThenFlush). */
 let lastPtyOutputAtMs = 0;
@@ -2275,6 +2297,8 @@ const MAX_SCROLLBACK = 1_000_000; // chars (~1MB)
 let scrollback = '';
 const WORKFLOW_TRANSCRIPT_MAX = 2_000_000; // chars (~2MB)
 const WORKFLOW_OUTPUT_END_MARKER = '</WORKFLOW_OUTPUT>';
+const CRASH_DIAGNOSTIC_RAW_MAX = 200_000; // enough scrollback for the web terminal without huge temp files
+const CRASH_LOG_TAIL_MAX = 2_500; // bounded Feishu text payload
 let workflowTranscript = '';
 let workflowFinalOutputSent = false;
 /** Tracks whether the CLI is currently in the alt screen buffer. Updated by
@@ -2286,6 +2310,97 @@ let workflowFinalOutputSent = false;
 let altBufferActive = false;
 const ALT_ENTER_RE = /\x1b\[\?(1049|1047|47)h/g;
 const ALT_EXIT_RE = /\x1b\[\?(1049|1047|47)l/g;
+function recentTerminalLogTail() {
+    const plain = stripAnsiForLog(tailChars(scrollback, CRASH_DIAGNOSTIC_RAW_MAX));
+    if (!plain)
+        return undefined;
+    return tailChars(plain, CRASH_LOG_TAIL_MAX);
+}
+function crashDiagnosticPath() {
+    const dataDir = process.env.SESSION_DATA_DIR;
+    if (!dataDir || !sessionId)
+        return undefined;
+    return join(dataDir, 'crash-diagnostics', `${sessionId}.ansi`);
+}
+function destroyCrashDiagnosticTerminal(reason) {
+    // Leaving the stopped-awaiting-retry state regardless of whether a tmux shell
+    // was actually parked (park may have failed); the next retry/close/suspend
+    // funnels through here.
+    crashDiagnosticStopped = false;
+    if (!crashDiagnosticTmuxParked || !sessionId)
+        return;
+    try {
+        TmuxBackend.killSession(TmuxBackend.diagnosticSessionName(sessionId));
+        log(`Crash diagnostic tmux session destroyed (${reason})`);
+    }
+    catch (err) {
+        log(`Crash diagnostic tmux cleanup failed (${reason}): ${err?.message ?? err}`);
+    }
+    // Best-effort: drop the captured .ansi file too so a long-lived daemon does
+    // not accumulate one ~200 KB file per crashed session forever.
+    const path = crashDiagnosticPath();
+    if (path) {
+        try {
+            unlinkSync(path);
+        }
+        catch { /* already gone — benign */ }
+    }
+    crashDiagnosticTmuxParked = false;
+}
+function parkCrashDiagnosticTerminal(code, signal) {
+    if (lastInitConfig?.adoptMode || effectiveBackendType !== 'tmux' || !sessionId)
+        return false;
+    const path = crashDiagnosticPath();
+    if (!path)
+        return false;
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        const rawTail = tailChars(scrollback, CRASH_DIAGNOSTIC_RAW_MAX);
+        const header = `[botmux] ${cliName()} exited (code: ${code ?? 'null'}, signal: ${signal ?? 'null'}).\n` +
+            `[botmux] Captured at ${new Date().toISOString()}.\n\n`;
+        writeFileSync(path, header + rawTail);
+    }
+    catch (err) {
+        log(`Crash diagnostic log write failed: ${err?.message ?? err}`);
+        return false;
+    }
+    // Park under a DISTINCT name (`bmx-diag-<sid>`), never the live CLI's
+    // `bmx-<sid>` backing-session name. The whole persistent-backend machinery
+    // (restore probe, hasSession reattach, idle-sweep cold-resume, `botmux
+    // resume`) keys off `bmx-<sid>` to mean "the live CLI". Reusing that name for
+    // a bare diagnostic shell makes restore/cold-resume reattach the shell as if
+    // it were the CLI and type the user's next message into raw bash. With a
+    // distinct name, `bmx-<sid>` is correctly absent after the crash, so every
+    // one of those paths sees "no live CLI" and does the right thing; the web
+    // terminal is pointed at the diagnostic name explicitly (see the WS attach).
+    const ok = TmuxBackend.parkDiagnosticSession(TmuxBackend.diagnosticSessionName(sessionId), {
+        cwd: lastInitConfig?.workingDir ?? process.cwd(),
+        cols: renderCols || PTY_COLS,
+        rows: renderRows || PTY_ROWS,
+        contentPath: path,
+    });
+    if (!ok) {
+        // tmux spawn failed after the .ansi was written — drop the orphan file.
+        try {
+            unlinkSync(path);
+        }
+        catch { /* benign */ }
+        return false;
+    }
+    crashDiagnosticTmuxParked = true;
+    isTmuxMode = true;
+    isPipeMode = false;
+    isZellijMode = false;
+    // The CLI is gone; stop the screen-update + analyzer loops so a stale
+    // `status='working'` tick can't un-freeze the daemon's frozen crash card.
+    // The web terminal is served by per-client tmux-attach PTYs, not these loops,
+    // so the diagnostic shell stays visible. flushPending's retry path restarts
+    // both when the next message respawns the CLI.
+    stopScreenUpdates();
+    stopScreenAnalyzer();
+    log(`Crash diagnostic tmux session parked at ${TmuxBackend.diagnosticSessionName(sessionId)}`);
+    return true;
+}
 // ─── Screen Analyzer (AI-based TUI prompt detection) ────────────────────────
 let screenAnalyzer = null;
 /** When true, user messages are queued because a TUI prompt is active */
@@ -4063,6 +4178,16 @@ function spawnCli(cfg) {
     // them past the server's global env.
     if (cliAdapter.spawnEnv)
         Object.assign(childEnv, cliAdapter.spawnEnv);
+    // Per-bot env (bots.json `env`): extra vars for THIS bot's CLI only — e.g.
+    // ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN to run a bot on GLM/a 3rd-party
+    // provider, an HTTPS_PROXY, or a CLI feature flag. Passed as injectEnv (NOT
+    // merged into childEnv) so the tmux/zellij backends inject it via the per-pane
+    // `/usr/bin/env` prefix and never into the shared backing-server global env,
+    // keeping it from leaking across bots. Re-sanitized here (crossed IPC).
+    const perBotInjectEnv = sanitizePerBotEnv(cfg.env);
+    const perBotInjectKeys = Object.keys(perBotInjectEnv);
+    if (perBotInjectKeys.length)
+        log(`Injecting ${perBotInjectKeys.length} per-bot env var(s): ${perBotInjectKeys.join(', ')}`);
     // ── File sandbox (oncall): wrap the CLI in bwrap so it can only touch a
     // per-session project copy + de-identified config. The agent's `botmux send`
     // routes through a daemon-side outbox watcher (creds never enter the sandbox).
@@ -4230,6 +4355,7 @@ function spawnCli(cfg) {
         cols: PTY_COLS,
         rows: PTY_ROWS,
         env: childEnv,
+        injectEnv: perBotInjectKeys.length ? perBotInjectEnv : undefined,
     });
     // Write CLI PID marker so agent-facing subcommands (`botmux send`, etc.)
     // can verify they were spawned inside a botmux session by walking the
@@ -4493,6 +4619,16 @@ function spawnCli(cfg) {
     backend.onData(onPtyData);
     backend.onExit((code, signal) => {
         log(`${cliName()} exited (code: ${code}, signal: ${signal})`);
+        const logTail = recentTerminalLogTail();
+        // Don't park a diagnostic shell here: most exits are immediately
+        // auto-restarted by the daemon, so an inline park would just be torn down
+        // again (a wasted tmux session + .ansi write on every restart). Instead
+        // report whether we COULD park; the daemon asks us to (park_diagnostic) only
+        // when it actually gives up restarting (crash loop). Stash the exit reason
+        // for that deferred park.
+        lastCliExitCode = code;
+        lastCliExitSignal = signal;
+        const canParkDiagnostic = !lastInitConfig?.adoptMode && effectiveBackendType === 'tmux' && !!sessionId;
         // Inputs written but not yet consumed (no idle since the write) die with
         // the CLI — codex crashing mid-submit never records them, and the fresh
         // respawn comes up empty. Stash them so the next spawnCli re-queues and
@@ -4503,38 +4639,56 @@ function spawnCli(cfg) {
         }
         backend = null;
         isPromptReady = false;
-        send({ type: 'claude_exit', code, signal });
+        send({ type: 'claude_exit', code, signal, logTail, canParkDiagnostic });
     });
     if (isPipeMode && backend && 'isReattach' in backend && backend.isReattach) {
         log(`Re-attached to existing ${effectiveBackendType} session via pipe backend: ${persistentSessionName}`);
         seedBackendScreen(`${effectiveBackendType} reattach`, backend);
         scheduleReattachIdleProbe(`${effectiveBackendType} reattach`, backend);
     }
-    // Fallback: if the CLI takes too long to show its prompt (e.g. slow
-    // plugin init, or a spinner blocks the idle detector), unblock screen
-    // updates AND deliver any queued prompts so the first user message
-    // isn't stranded until the second message arrives. markNewTurn() sets a
-    // clean baseline at the current cursor position so only content written
-    // *after* this point appears in the card.
-    setTimeout(() => {
-        if (awaitingFirstPrompt) {
-            awaitingFirstPrompt = false;
-            renderer?.markNewTurn();
-            log('First prompt timeout — enabling screen updates and flushing queued messages');
-            if (backend && cliAdapter?.busyPattern && probeBusyPatternIdle(`${cliName()} first-prompt-timeout`, backend)) {
-                return;
-            }
-            // For type-ahead adapters (Codex/CoCo/TRAE/Claude) the TUI is booted
-            // enough to park input even if the idle detector hasn't fired yet.
-            // Directly invoking markPromptReady() would claim the CLI is idle
-            // while it's still mid-boot, so flushPending() alone is safer — it
-            // respects typeAheadAllowed and drains pendingMessages now.
-            if (cliAdapter?.supportsTypeAhead)
-                flushPending();
+    // Fallback: if the CLI takes too long to show its prompt (e.g. slow plugin
+    // init, or a spinner blocks the idle detector), unblock screen updates AND
+    // deliver any queued prompts so the first user message isn't stranded until
+    // the second message arrives. Some adapters opt into deferring the soft
+    // fallback until readyPattern, but still get a hard cap below.
+    // markNewTurn() sets a clean baseline at the current cursor position so only
+    // content written *after* this point appears in the card.
+    const firstPromptBackend = backend;
+    const releaseFirstPromptTimeout = (elapsedMs, forced) => {
+        if (!awaitingFirstPrompt || backend !== firstPromptBackend)
+            return;
+        if (!shouldReleaseFirstPromptTimeout({
+            deferFirstPromptTimeoutUntilReady: cliAdapter?.deferFirstPromptTimeoutUntilReady === true,
+            hasReadyPattern: !!cliAdapter?.readyPattern,
+            elapsedMs,
+            hardTimeoutMs: FIRST_PROMPT_HARD_TIMEOUT_MS,
+        })) {
+            const hardWaitMs = Math.max(0, FIRST_PROMPT_HARD_TIMEOUT_MS - elapsedMs);
+            log(`First prompt timeout — ${cliName()} still waiting for readyPattern before flushing queued messages`);
+            const hardTimer = setTimeout(() => releaseFirstPromptTimeout(FIRST_PROMPT_HARD_TIMEOUT_MS, true), hardWaitMs);
+            hardTimer.unref?.();
+            return;
+        }
+        awaitingFirstPrompt = false;
+        renderer?.markNewTurn();
+        log(forced
+            ? `WARN First prompt hard timeout — ${cliName()} readyPattern did not arrive; forcing queued message flush`
+            : 'First prompt timeout — enabling screen updates and flushing queued messages');
+        if (backend && cliAdapter?.busyPattern && probeBusyPatternIdle(`${cliName()} first-prompt-timeout`, backend)) {
+            return;
         }
-    }, 15_000);
+        // For type-ahead adapters (Codex/CoCo/Claude/TraeX) the TUI is usually booted
+        // enough to park input even if the idle detector hasn't fired yet. Directly
+        // invoking markPromptReady() would claim the CLI is idle while it's still
+        // mid-boot, so flushPending() alone is safer — it respects typeAheadAllowed
+        // and drains pendingMessages now.
+        if (cliAdapter?.supportsTypeAhead)
+            flushPending();
+    };
+    setTimeout(() => releaseFirstPromptTimeout(FIRST_PROMPT_TIMEOUT_MS, false), FIRST_PROMPT_TIMEOUT_MS);
 }
 function killCli() {
+    destroyCrashDiagnosticTerminal('killCli');
     idleDetector?.dispose();
     idleDetector = null;
     stopReattachIdleProbe();
@@ -4634,7 +4788,13 @@ function startWebServer(host, preferredPort) {
                 // byte-for-byte (empty, separators, etc.) are not retransmitted, so
                 // the earlier frame "bleeds through" — visible as a second
                 // banner/prompt stacked above the new layout when scrolling up.
-                const tmuxTarget = lastInitConfig?.adoptTmuxTarget ?? TmuxBackend.sessionName(sessionId);
+                // While a crash diagnostic shell is parked it lives under bmx-diag-<sid>
+                // (not the live CLI's bmx-<sid>), so attach there to surface the startup
+                // error; otherwise attach the normal backing session.
+                const tmuxTarget = lastInitConfig?.adoptTmuxTarget
+                    ?? (crashDiagnosticTmuxParked
+                        ? TmuxBackend.diagnosticSessionName(sessionId)
+                        : TmuxBackend.sessionName(sessionId));
                 let cp = null;
                 const pendingInput = [];
                 const startAttach = (cols, rows) => {
@@ -5190,6 +5350,16 @@ process.on('message', async (raw) => {
             const content = msg.content;
             currentBotmuxTurnId = msg.turnId;
             writeCliPidMarker();
+            if (!backend && crashDiagnosticStopped && lastInitConfig && !lastInitConfig.adoptMode) {
+                log('Message received after crash-loop stop; retrying CLI start');
+                destroyCrashDiagnosticTerminal('retry after message');
+                stopScreenAnalyzer();
+                stopScreenUpdates();
+                awaitingFirstPrompt = true;
+                startScreenUpdates();
+                startScreenAnalyzer();
+                spawnCli({ ...lastInitConfig, resume: true, prompt: '' });
+            }
             if (lastInitConfig?.adoptMode) {
                 // Bridge mode: capture transcript baseline BEFORE writing to the pane,
                 // so any assistant uuids appended after this point are attributed to
@@ -5320,6 +5490,16 @@ process.on('message', async (raw) => {
             }
             break;
         }
+        case 'park_diagnostic': {
+            // The daemon gave up auto-restarting (crash loop) and wants the last
+            // terminal output preserved. Park the diagnostic shell now — deferred from
+            // onExit so transient (auto-restarted) exits never pay for it. Mark the
+            // stopped state even if the tmux park fails, so the next message still
+            // retries the CLI (no hang) rather than writing into a dead pane.
+            parkCrashDiagnosticTerminal(lastCliExitCode, lastCliExitSignal);
+            crashDiagnosticStopped = true;
+            break;
+        }
         case 'restart': {
             if (lastInitConfig?.adoptMode) {
                 log('Restart ignored in adopt mode');
@@ -5424,6 +5604,11 @@ process.on('message', async (raw) => {
             log('Suspend requested');
             stopScreenshotLoop();
             stopBridgeWatcher();
+            // A parked crash diagnostic shell has backend===null, so the
+            // destroySession/kill below is a no-op and would otherwise leak the
+            // bmx-diag-<sid> session. Tear it down explicitly. (The session then
+            // cold-resumes a FRESH CLI on the next message — bmx-<sid> is absent.)
+            destroyCrashDiagnosticTerminal('suspend');
             // Free the CLI's memory, not just the worker's: destroySession kills the
             // backing tmux/herdr/zellij session AND the CLI process inside it (kill()
             // would only detach the pty viewer and leave the CLI running in the
@@ -5544,8 +5729,17 @@ function teardownSandboxBestEffort() {
     catch { /* */ }
     sandboxCleanup = null;
 }
+// Under pm2 the worker's stdout/stderr are pipes; a broken pipe (e.g. log
+// streaming detaches) would otherwise reach the uncaughtException handler below
+// and process.exit(1), killing a live session over a dropped log write. Install
+// the guard before any further stdout writes (log() writes to process.stdout).
+installStdioEpipeGuard();
 process.on('exit', () => { teardownSandboxBestEffort(); });
 process.on('uncaughtException', (err) => {
+    // A broken pipe on stdout/stderr (or any socket) must not tear down a live
+    // session — the stdio guard handles those it can; this is the backstop.
+    if (isIgnorableStreamError(err))
+        return;
     try {
         log(`Uncaught exception — tearing down sandbox before exit: ${err?.stack ?? err}`);
     }
@@ -5558,6 +5752,8 @@ process.on('uncaughtException', (err) => {
     process.exit(1);
 });
 process.on('unhandledRejection', (reason) => {
+    if (isIgnorableStreamError(reason))
+        return;
     try {
         log(`Unhandled rejection — tearing down sandbox before exit: ${reason?.stack ?? reason}`);
     }