botmux 2.63.1 → 2.65.0

package/dist/utils/listen-with-probe.js

@@ -0,0 +1,64 @@
+/**
+ * Bind `server` to `port`, walking port+1, port+2 … up to `maxProbe` times when
+ * the port is already in use, and resolve with the actually-bound port.
+ *
+ * Why this exists: several daemon/dashboard listeners (dashboard-ipc-server.ts,
+ * dashboard.ts) historically did a single `server.listen(fixedPort)` with no
+ * 'error' listener / no probe, so on a shared machine a second botmux instance
+ * binding the same default port emitted an UNHANDLED 'error' that crashed the
+ * whole process (the IPC bind even took the daemon down at startup). This
+ * mirrors the already-proven probe in core/terminal-proxy.ts so those binds
+ * self-heal to a free port; callers MUST advertise the returned (bound) port to
+ * their consumers (the IPC port via the daemon descriptor, the dashboard port
+ * via ~/.botmux/.dashboard-port) since it may differ from the requested one.
+ */
+export function listenWithProbe(opts) {
+    const { server, host } = opts;
+    const maxProbe = opts.maxProbe ?? 20;
+    const log = opts.log ?? (() => { });
+    return new Promise((resolve, reject) => {
+        let port = opts.port;
+        let attempts = 0;
+        let settled = false;
+        // Single persistent handlers reused across every probe attempt. Passing a
+        // callback to server.listen() would instead add a fresh one-time
+        // 'listening' listener on each retry that is never removed on a failed
+        // bind, leaking listeners (MaxListenersExceededWarning past 10 probes) and
+        // firing every stale callback once a bind finally succeeds.
+        const cleanup = () => {
+            server.removeListener('listening', onListening);
+            server.removeListener('error', onError);
+        };
+        const onListening = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            const addr = server.address();
+            const bound = typeof addr === 'object' && addr ? addr.port : port;
+            // Keep a permanent handler so a post-bind runtime error can't become an
+            // unhandled 'error' event (which would crash the process).
+            server.on('error', (e) => log(`server error: ${e.message}`));
+            resolve(bound);
+        };
+        const onError = (err) => {
+            if (settled)
+                return;
+            if (err.code === 'EADDRINUSE' && attempts < maxProbe) {
+                attempts++;
+                log(`port ${port} in use, trying ${port + 1}`);
+                port++;
+                setImmediate(() => { if (!settled)
+                    server.listen(port, host); });
+                return;
+            }
+            settled = true;
+            cleanup();
+            reject(err);
+        };
+        server.on('listening', onListening);
+        server.on('error', onError);
+        server.listen(port, host);
+    });
+}
+//# sourceMappingURL=listen-with-probe.js.map

package/dist/utils/listen-with-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen-with-probe.js","sourceRoot":"","sources":["../../src/utils/listen-with-probe.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,IAAyB;IACvD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAc,CAAC,CAAC,CAAC;IAE/C,OAAO,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC7C,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACrB,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,0EAA0E;QAC1E,iEAAiE;QACjE,uEAAuE;QACvE,2EAA2E;QAC3E,4DAA4D;QAC5D,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YAChD,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1C,CAAC,CAAC;QACF,MAAM,WAAW,GAAG,GAAG,EAAE;YACvB,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,EAAE,CAAC;YACV,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YAClE,wEAAwE;YACxE,2DAA2D;YAC3D,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,iBAAkB,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACxE,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,CAAC,GAA0B,EAAE,EAAE;YAC7C,IAAI,OAAO;gBAAE,OAAO;YACpB,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,IAAI,QAAQ,GAAG,QAAQ,EAAE,CAAC;gBACrD,QAAQ,EAAE,CAAC;gBACX,GAAG,CAAC,QAAQ,IAAI,mBAAmB,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC/C,IAAI,EAAE,CAAC;gBACP,YAAY,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO;oBAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBACjE,OAAO;YACT,CAAC;YACD,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,EAAE,CAAC;YACV,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,CAAC;QAEF,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QACpC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC5B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/web-terminal-listen.d.ts

@@ -0,0 +1,30 @@
+import type { Server as HttpServer } from 'node:http';
+import type { WebSocketServer } from 'ws';
+export interface ListenWebTerminalOpts {
+    httpServer: HttpServer;
+    wss: WebSocketServer;
+    host: string;
+    /** Try this port first; fall back to an OS-assigned random port if busy. */
+    preferredPort?: number;
+    log?: (msg: string) => void;
+}
+/**
+ * Bind the per-session web-terminal HTTP server, recovering from a busy
+ * `preferredPort` (e.g. a persisted webPort reused on worker re-fork that some
+ * other process now holds) by retrying on an OS-assigned random port.
+ *
+ * CRITICAL — why the `wss.on('error')` below is load-bearing, not cosmetic:
+ * `new WebSocketServer({ server })` makes the ws library proxy the HTTP server's
+ * `'error'` event onto the WSS instance (ws ≥8: `addListeners` runs
+ * `server.on('error', wss.emit.bind(wss, 'error'))` at construction time). That
+ * proxy listener is registered BEFORE the HTTP server's own `'error'` handler
+ * here. So on EADDRINUSE the proxy fires first and re-emits `'error'` on the
+ * WSS; with no `'error'` listener on the WSS, Node throws an unhandled `'error'`
+ * event and CRASHES the whole worker process — before the HTTP fallback below
+ * ever runs, making the random-port recovery dead code. Note: ordering the HTTP
+ * handler first does NOT help (verified) — the unhandled WSS error still fires.
+ * The only fix is to give the WSS an `'error'` listener. Regression-tested in
+ * test/web-terminal-listen.test.ts.
+ */
+export declare function listenWebTerminalWithFallback(opts: ListenWebTerminalOpts): Promise<number>;
+//# sourceMappingURL=web-terminal-listen.d.ts.map

package/dist/utils/web-terminal-listen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-terminal-listen.d.ts","sourceRoot":"","sources":["../../src/utils/web-terminal-listen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAE1C,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,UAAU,CAAC;IACvB,GAAG,EAAE,eAAe,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+D1F"}

package/dist/utils/web-terminal-listen.js

@@ -0,0 +1,81 @@
+/**
+ * Bind the per-session web-terminal HTTP server, recovering from a busy
+ * `preferredPort` (e.g. a persisted webPort reused on worker re-fork that some
+ * other process now holds) by retrying on an OS-assigned random port.
+ *
+ * CRITICAL — why the `wss.on('error')` below is load-bearing, not cosmetic:
+ * `new WebSocketServer({ server })` makes the ws library proxy the HTTP server's
+ * `'error'` event onto the WSS instance (ws ≥8: `addListeners` runs
+ * `server.on('error', wss.emit.bind(wss, 'error'))` at construction time). That
+ * proxy listener is registered BEFORE the HTTP server's own `'error'` handler
+ * here. So on EADDRINUSE the proxy fires first and re-emits `'error'` on the
+ * WSS; with no `'error'` listener on the WSS, Node throws an unhandled `'error'`
+ * event and CRASHES the whole worker process — before the HTTP fallback below
+ * ever runs, making the random-port recovery dead code. Note: ordering the HTTP
+ * handler first does NOT help (verified) — the unhandled WSS error still fires.
+ * The only fix is to give the WSS an `'error'` listener. Regression-tested in
+ * test/web-terminal-listen.test.ts.
+ */
+export function listenWebTerminalWithFallback(opts) {
+    const { httpServer, wss, host, preferredPort } = opts;
+    const log = opts.log ?? (() => { });
+    return new Promise((resolve, reject) => {
+        // Defuse the ws→wss error proxy so a bind failure can't crash the process;
+        // the httpServer 'error' handler below owns recovery / rejection.
+        wss.on('error', (err) => {
+            log(`WSS server error: ${[err.code, err.message].filter(Boolean).join(' ')}`);
+        });
+        const currentPort = () => {
+            const addr = httpServer.address();
+            return typeof addr === 'object' && addr ? addr.port : 0;
+        };
+        const listenPort = preferredPort ?? 0;
+        let fallbackAttempted = false;
+        let settled = false;
+        const settleResolve = (port) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(port);
+        };
+        const settleReject = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(err);
+        };
+        const listen = (port, suffix = '') => {
+            httpServer.listen(port, host, () => {
+                const boundPort = currentPort();
+                log(`HTTP listening on ${host}:${boundPort}${suffix}`);
+                settleResolve(boundPort);
+            });
+        };
+        // Register before listen(): bind failures are asynchronous 'error' events,
+        // and the recovery handler must be present before the first listen attempt.
+        httpServer.on('error', (err) => {
+            // This handler outlives the Promise (we never detach it). Once we've
+            // resolved/rejected, a late 'error' must be inert — otherwise an
+            // EADDRINUSE arriving after a no-fallback resolve would re-enter listen()
+            // on an already-listening server (ERR_SERVER_ALREADY_LISTEN, thrown
+            // synchronously from the emit → unhandled → crash). Defense in depth.
+            if (settled)
+                return;
+            if (err.code === 'EADDRINUSE' && !fallbackAttempted) {
+                fallbackAttempted = true;
+                if (preferredPort) {
+                    log(`Preferred port ${preferredPort} in use (${err.code}), falling back to random`);
+                }
+                else {
+                    log(`Port ${listenPort} bind failed (${err.code}), retrying with random port`);
+                }
+                listen(0, ' (fallback)');
+            }
+            else {
+                settleReject(err);
+            }
+        });
+        listen(listenPort);
+    });
+}
+//# sourceMappingURL=web-terminal-listen.js.map

package/dist/utils/web-terminal-listen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-terminal-listen.js","sourceRoot":"","sources":["../../src/utils/web-terminal-listen.ts"],"names":[],"mappings":"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"}

package/dist/worker.js

@@ -31,6 +31,7 @@ import { baselineJsonlCursor } from './services/jsonl-cursor.js';
 import { dirname } from 'node:path';
 import { createServer as createHttpServer } from 'node:http';
 import { WebSocketServer, WebSocket } from 'ws';
+import { listenWebTerminalWithFallback } from './utils/web-terminal-listen.js';
 import { TerminalRenderer } from './utils/terminal-renderer.js';
 import { DEFAULT_RENDER_COLS, DEFAULT_RENDER_ROWS, MAX_RENDER_COLS, MAX_RENDER_ROWS, MIN_RENDER_COLS, MIN_RENDER_ROWS, clamp, resolveRenderDimensions, } from './utils/render-dimensions.js';
 import { createCliAdapterSync, locateOnPath } from './adapters/cli/registry.js';
@@ -107,6 +108,17 @@ const pendingMessages = [];
 /** Alternate submit-confirmation signals. Some CLIs can consume PTY input and
  *  start work before their history/transcript submit marker is observable. */
 let lastPtyActivityAtMs = 0;
+let currentBotmuxTurnId;
+function writeCliPidMarker() {
+    if (!cliPidMarker || !sessionId)
+        return;
+    try {
+        writeFileSync(cliPidMarker, JSON.stringify({ sessionId, turnId: currentBotmuxTurnId ?? null }));
+    }
+    catch (err) {
+        log(`Failed to update CLI PID marker: ${err?.message ?? err}`);
+    }
+}
 let lastStructuredBridgeActivityAtMs = 0;
 // Per-turn usage-limit state machine. Owns the turn counter plus the
 // "did this turn hit a limit" / "suppress a stale retry-ready banner" flags, so
@@ -389,6 +401,7 @@ function maybeEmitAdoptPreamble(events) {
     bridgePreambleSent = true;
     send({
         type: 'adopt_preamble',
+        turnId: currentBotmuxTurnId,
         userText: truncatePreambleText(turn.userText, PREAMBLE_USER_MAX),
         assistantText: truncatePreambleText(turn.assistantText, PREAMBLE_ASSISTANT_MAX),
     });
@@ -413,6 +426,7 @@ function maybeEmitCodexAdoptPreamble(history) {
     codexBridgePreambleSent = true;
     send({
         type: 'adopt_preamble',
+        turnId: currentBotmuxTurnId,
         userText: truncatePreambleText(turn.userText, PREAMBLE_USER_MAX),
         assistantText: truncatePreambleText(turn.assistantText, PREAMBLE_ASSISTANT_MAX),
     });
@@ -1298,7 +1312,7 @@ function stopBridgeWatcher() {
  * no jsonl line will ever match, and `maybeSwitchBridgeJsonl` burns 99%
  * CPU scanning all sibling jsonls for it on every poll tick.
  */
-function bridgeMarkPendingTurn(messageText) {
+function bridgeMarkPendingTurn(messageText, preferredTurnId) {
     if (!bridgeJsonlPath)
         return undefined;
     if (!bridgeBaselineDone) {
@@ -1314,7 +1328,7 @@ function bridgeMarkPendingTurn(messageText) {
     // pane to false-match than the 30-char substring fingerprint.
     const normalised = normaliseForFingerprint(messageText);
     const contentNormalized = normalised.length > 0 ? normalised : undefined;
-    const turnId = randomBytes(8).toString('hex');
+    const turnId = preferredTurnId ?? randomBytes(8).toString('hex');
     bridgeQueue.mark(turnId, fingerprint, Date.now(), contentNormalized);
     return turnId;
 }
@@ -1853,10 +1867,10 @@ function codexBridgeIngest() {
 /** Mark a pending Lark turn for Codex. Crucially this works even before a
  *  rollout path is known — the queue is path-agnostic, and ingest after
  *  late-attach picks up the user_message and matches the fingerprint. */
-function codexBridgeMarkPendingTurn(messageText) {
+function codexBridgeMarkPendingTurn(messageText, preferredTurnId) {
     if (!codexBridgeFallbackActive())
         return false;
-    const turnId = `codex-${randomBytes(8).toString('hex')}`;
+    const turnId = preferredTurnId ?? `codex-${randomBytes(8).toString('hex')}`;
     codexBridgeQueue.mark(turnId, messageText);
     return true;
 }
@@ -2115,7 +2129,7 @@ function maybeEmitWorkflowTranscriptOutput() {
         type: 'final_output',
         content: workflowTranscript,
         lastUuid: `workflow-pty-${Date.now()}`,
-        turnId: `workflow-pty-${sessionId || 'unknown'}`,
+        turnId: currentBotmuxTurnId ?? `workflow-pty-${sessionId || 'unknown'}`,
     });
     log('Workflow PTY transcript final_output emitted');
 }
@@ -2145,7 +2159,7 @@ function startScreenAnalyzer() {
         onAnalyzing: () => { },
         onTuiPrompt: (description, options, multiSelect) => {
             tuiPromptBlocking = true;
-            send({ type: 'tui_prompt', description, options, multiSelect });
+            send({ type: 'tui_prompt', description, options, multiSelect, turnId: currentBotmuxTurnId });
         },
         onTuiPromptResolved: (selectedText) => {
             tuiPromptBlocking = false;
@@ -2513,7 +2527,7 @@ function handleCodexAppMarker(body) {
                 return;
             }
         }
-        const turnId = typeof payload.turnId === 'string' ? payload.turnId : `${lastInitConfig?.cliId ?? 'app'}-${Date.now()}`;
+        const turnId = typeof payload.turnId === 'string' ? payload.turnId : (currentBotmuxTurnId ?? `${lastInitConfig?.cliId ?? 'app'}-${Date.now()}`);
         send({
             type: 'final_output',
             content: payload.content,
@@ -2637,7 +2651,7 @@ function markPromptReady() {
     // (where the initial prompt is queued before the CLI becomes idle).
     if (renderer && pendingMessages.length === 0 && !isFlushing) {
         const { content } = renderer.snapshot();
-        send({ type: 'screen_update', content, ...usageLimitTracker.classify(content, 'idle') });
+        send({ type: 'screen_update', content, ...usageLimitTracker.classify(content, 'idle'), turnId: currentBotmuxTurnId });
     }
     flushPending();
 }
@@ -2700,6 +2714,7 @@ function scheduleSubmitFailureNotify(msg, recheck, transcriptLabel, bridgeTurnId
         log(`writeInput: submit impossible — notifying user immediately. reason="${reason}" preview="${preview}"`);
         send({
             type: 'user_notify',
+            turnId: currentBotmuxTurnId,
             message: `⚠️ 刚才那条消息没有写入 ${cliName()}，因为当前按键配置无法从终端自动提交。\n原因：${reason}\n请调整 Claude Code Chat keybinding 后重发。\n开头：${preview}`,
         });
         return;
@@ -2754,6 +2769,7 @@ function scheduleSubmitFailureNotify(msg, recheck, transcriptLabel, bridgeTurnId
         log(`Deferred recheck still missing — notifying user. preview="${preview}"`);
         send({
             type: 'user_notify',
+            turnId: currentBotmuxTurnId,
             message: `⚠️ 刚才那条消息发给 ${cliName()} 后没能确认提交（重试 Enter 后等了 ${Math.round(SUBMIT_DEFERRED_RECHECK_MS / 1000)}s 仍未在${transcriptLabel}里看到新记录）。可能卡在输入框里——请去 Web 终端看一下，手动按 Enter 或重发。\n开头：${preview}`,
         });
     }, SUBMIT_DEFERRED_RECHECK_MS);
@@ -2807,7 +2823,10 @@ async function flushPending() {
     }
     try {
         while (pendingMessages.length > 0 && backend && cliAdapter) {
-            const msg = pendingMessages.shift();
+            const item = pendingMessages.shift();
+            const msg = item.content;
+            currentBotmuxTurnId = item.turnId;
+            writeCliPidMarker();
             const turnSeq = usageLimitTracker.beginTurn(currentUsageLimitSnapshot());
             // Bridge fallback: mark immediately before writeInput. Doing it here
             // (instead of at enqueue time) means markTimeMs anchors to the
@@ -2822,14 +2841,14 @@ async function flushPending() {
                     bridgeIngest();
                 }
                 catch { /* best-effort */ }
-                bridgeTurnId = bridgeMarkPendingTurn(msg);
+                bridgeTurnId = bridgeMarkPendingTurn(msg, item.turnId);
             }
             else if (codexBridgeActive) {
                 // Codex mark works even before the rollout path is known: the
                 // queue is path-agnostic, and the late-attach below will start
                 // ingest from offset 0 so the user_message that lands shortly
                 // after still fingerprint-matches this turn.
-                codexBridgeMarkPendingTurn(msg);
+                codexBridgeMarkPendingTurn(msg, item.turnId);
             }
             log(`Writing to PTY (flush): "${msg.substring(0, 80)}"`);
             // Defense in depth: TmuxPipeBackend's send methods no longer throw on a
@@ -2884,10 +2903,10 @@ async function flushPending() {
         isFlushing = false;
     }
 }
-function sendToPty(content) {
+function sendToPty(content, turnId) {
     if (!backend || !cliAdapter)
         return;
-    pendingMessages.push(content);
+    pendingMessages.push({ content, turnId });
     // User-override semantics: a fresh Lark message while a TUI prompt is "active"
     // takes precedence over the AI-detected prompt. The screen analyzer can be
     // wrong (false positive on a question that has no rendered options) and a
@@ -2966,7 +2985,7 @@ function startScreenUpdates() {
             const usageAware = usageLimitTracker.classify(content, status);
             if (changed || usageAware.status !== lastSentStatus) {
                 lastSentStatus = usageAware.status;
-                send({ type: 'screen_update', content, ...usageAware });
+                send({ type: 'screen_update', content, ...usageAware, turnId: currentBotmuxTurnId });
             }
         })();
     }, SCREEN_UPDATE_INTERVAL_MS);
@@ -3360,6 +3379,7 @@ function spawnCli(cfg) {
             const probe = isAbsolute(wantBin) ? `ls -l ${wantBin}` : `which ${wantBin}`;
             send({
                 type: 'user_notify',
+                turnId: currentBotmuxTurnId,
                 message: `无法启动 ${cliName()}：找不到可执行文件「${wantBin}」。\n` +
                     `请在运行 botmux daemon 的这台机器上确认它已安装并在 PATH 中（自查：${probe}），然后重发消息重试。\n` +
                     `当前 daemon PATH=${process.env.PATH ?? '(空)'}`,
@@ -3385,6 +3405,9 @@ function spawnCli(cfg) {
     childEnv.BOTMUX_CHAT_ID = cfg.chatId;
     childEnv.BOTMUX_LARK_APP_ID = cfg.larkAppId;
     childEnv.BOTMUX_ROOT_MESSAGE_ID = cfg.rootMessageId;
+    // Initial value only; long-lived panes get the latest turn via the JSON pid marker.
+    if (cfg.turnId)
+        childEnv.BOTMUX_TURN_ID = cfg.turnId;
     if (injectClaudeSandbox)
         childEnv.IS_SANDBOX = '1';
     if (claudeResumeTokenThreshold)
@@ -3410,7 +3433,7 @@ function spawnCli(cfg) {
         try {
             mkdirSync(markersDir, { recursive: true });
             cliPidMarker = join(markersDir, String(cliPid));
-            writeFileSync(cliPidMarker, cfg.sessionId);
+            writeCliPidMarker();
             log(`CLI PID marker written: ${cliPid}`);
         }
         catch (err) {
@@ -3448,7 +3471,7 @@ function spawnCli(cfg) {
                         const markersDir = join(process.env.SESSION_DATA_DIR, '.botmux-cli-pids');
                         mkdirSync(markersDir, { recursive: true });
                         cliPidMarker = join(markersDir, String(pid));
-                        writeFileSync(cliPidMarker, cfg.sessionId);
+                        writeCliPidMarker();
                         log(`CLI PID marker written (async): ${pid}`);
                     }
                     catch (err) {
@@ -3882,28 +3905,13 @@ function startWebServer(host, preferredPort) {
                 });
             }
         });
-        const listenPort = preferredPort ?? 0;
-        httpServer.listen(listenPort, host, () => {
-            const addr = httpServer.address();
-            const port = typeof addr === 'object' && addr ? addr.port : 0;
-            log(`HTTP listening on ${host}:${port}`);
-            resolve(port);
-        });
-        httpServer.on('error', (err) => {
-            if (preferredPort && err.code === 'EADDRINUSE') {
-                // Preferred port in use — fall back to random
-                log(`Preferred port ${preferredPort} in use, falling back to random`);
-                httpServer.listen(0, host, () => {
-                    const addr = httpServer.address();
-                    const port = typeof addr === 'object' && addr ? addr.port : 0;
-                    log(`HTTP listening on ${host}:${port} (fallback)`);
-                    resolve(port);
-                });
-            }
-            else {
-                reject(err);
-            }
-        });
+        // Bind + EADDRINUSE→random-port fallback live in a shared helper that also
+        // attaches the load-bearing wss 'error' listener: `new WebSocketServer({
+        // server })` makes ws proxy the http server's 'error' onto the wss, so a
+        // busy port would otherwise emit an UNHANDLED 'error' on the wss and crash
+        // the worker before this fallback can run. See web-terminal-listen.ts.
+        listenWebTerminalWithFallback({ httpServer: httpServer, wss: wss, host, preferredPort, log })
+            .then(resolve, reject);
     });
 }
 function getTerminalHtml(hasWrite) {
@@ -4194,6 +4202,10 @@ process.on('message', async (raw) => {
             renderRows = dims.rows;
             log(`Init: session=${sessionId}, cwd=${msg.workingDir}, render=${renderCols}x${renderRows}${msg.adoptMode ? ' (adopt-pane)' : ''}`);
             try {
+                if (msg.turnId) {
+                    currentBotmuxTurnId = msg.turnId;
+                    writeCliPidMarker();
+                }
                 let port = 0;
                 if (!isWorkflowWorker()) {
                     port = await startWebServer(config.web.workerHost, msg.webPort);
@@ -4215,9 +4227,9 @@ process.on('message', async (raw) => {
                 // Bridge mark is deferred to flushPending — see flushPending
                 // comment for why marking at enqueue is wrong.
                 if (msg.prompt && !cliAdapter?.passesInitialPromptViaArgs) {
-                    pendingMessages.push(msg.prompt);
+                    pendingMessages.push({ content: msg.prompt, turnId: msg.turnId });
                 }
-                send({ type: 'ready', port, token: writeToken });
+                send({ type: 'ready', port, token: writeToken, turnId: currentBotmuxTurnId });
             }
             catch (err) {
                 send({ type: 'error', message: `init failed: ${err.message}` });
@@ -4233,6 +4245,8 @@ process.on('message', async (raw) => {
             if (tmuxScrolledHalfPages > 0)
                 exitTmuxScrollMode();
             const content = msg.content;
+            currentBotmuxTurnId = msg.turnId;
+            writeCliPidMarker();
             if (lastInitConfig?.adoptMode) {
                 // Bridge mode: capture transcript baseline BEFORE writing to the pane,
                 // so any assistant uuids appended after this point are attributed to
@@ -4244,7 +4258,7 @@ process.on('message', async (raw) => {
                         bridgeIngest();
                     }
                     catch { /* best effort */ }
-                    bridgeMarkPendingTurn(content);
+                    bridgeMarkPendingTurn(content, msg.turnId);
                 }
                 else if (codexBridgeFallbackActive()) {
                     // Codex adopt: same idea, different bridge. ingest first so any
@@ -4256,7 +4270,7 @@ process.on('message', async (raw) => {
                         // before this IPC message is handled. Mark first so that preexisting
                         // current-line can still fingerprint-match instead of being marked
                         // seen as an unmatched event.
-                        codexBridgeMarkPendingTurn(content);
+                        codexBridgeMarkPendingTurn(content, msg.turnId);
                         try {
                             codexBridgeIngest();
                         }
@@ -4267,7 +4281,7 @@ process.on('message', async (raw) => {
                             codexBridgeIngest();
                         }
                         catch { /* best effort */ }
-                        codexBridgeMarkPendingTurn(content);
+                        codexBridgeMarkPendingTurn(content, msg.turnId);
                     }
                 }
                 // Adopt mode write:
@@ -4326,7 +4340,7 @@ process.on('message', async (raw) => {
                 // arrival. Marking now would race with a still-running previous
                 // turn whose `botmux send` could sneak its sentAtMs past this
                 // turn's markTimeMs and falsely suppress its fallback.
-                sendToPty(content);
+                sendToPty(content, msg.turnId);
             }
             break;
         }
@@ -4430,6 +4444,19 @@ process.on('message', async (raw) => {
             cleanup();
             process.exit(0);
         }
+        case 'suspend': {
+            log('Suspend requested');
+            stopScreenshotLoop();
+            stopBridgeWatcher();
+            try {
+                backend?.kill();
+            }
+            catch { /* detach best-effort */ }
+            backend = null;
+            isPromptReady = false;
+            cleanup();
+            process.exit(0);
+        }
     }
 });
 // ─── Cleanup ─────────────────────────────────────────────────────────────────