botmux 2.107.0 → 2.108.0

package/dist/worker.js

@@ -30,15 +30,22 @@ 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 { resolveTerminalWriteForRequest } from './core/terminal-write-auth.js';
+import { readPlatformBinding } from './platform/binding.js';
+import { loadPersistedToken } from './dashboard/auth.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';
 import { drainCodexRollout, findCodexRolloutBySessionId, findCodexRolloutByPid, splitCodexEventsByCutoff, extractLastCodexTurn } from './services/codex-transcript.js';
 import { findTraexRolloutBySessionId, findTraexRolloutByPid } from './services/traex-transcript.js';
 import { cocoEventsPathForSession, drainCocoEvents, findCocoSessionByPid } from './services/coco-transcript.js';
-import { currentHermesStateOffset, drainHermesStateDb } from './services/hermes-transcript.js';
+import { currentHermesStateOffset, drainHermesStateDb, resolveHermesStateDbPath } from './services/hermes-transcript.js';
+import { filterHermesEventsForBotmuxSession } from './services/hermes-session-filter.js';
 import { currentMtrSessionOffset, drainMtrSession, findLatestMtrSessionByDirectory, findMtrSessionById } from './services/mtr-transcript.js';
-import { drainPiTranscript, findPiTranscriptByPid, findPiTranscriptBySessionId } from './services/pi-transcript.js';
+import { drainPiTranscript } from './services/pi-transcript.js';
+import { drainGrokUpdates, grokSessionIdFromPath, } from './services/grok-transcript.js';
+import { resolveFileBridgePath } from './services/file-bridge-path.js';
+import { isStructuredBridgeAdoptIdleCli, isStructuredBridgeAdoptInputCli, isStructuredBridgeFallbackActive, } from './services/structured-bridge-clis.js';
 import { drainCursorTranscript, findCursorChatIdByPid, findCursorTranscriptByChatId, findCursorTranscriptByPid } from './services/cursor-transcript.js';
 import { shouldObserveCursorChatId, shouldPersistObservedCursorChatId } from './services/cursor-resume-policy.js';
 import { baselineJsonlCursor } from './services/jsonl-cursor.js';
@@ -65,7 +72,8 @@ import { zellijEnv } from './setup/ensure-zellij.js';
 import { isObserveBackend } from './adapters/backend/types.js';
 import { selectSessionBackend, decideBackendGate, backendGateUserMessage } from './adapters/backend/session-backend-selector.js';
 import { prepareSandbox, attachSandboxOutbox, startOutboxWatcher, sandboxEnabled, sandboxedClaudeDataDir } from './adapters/backend/sandbox.js';
-import { tmuxEnv, probeTmuxFunctional } from './setup/ensure-tmux.js';
+import { tmuxEnv, probeTmuxFunctionalWithRetry } from './setup/ensure-tmux.js';
+import { tmuxRestartJitterMs } from './core/tmux-recovery.js';
 import { IdleDetector } from './utils/idle-detector.js';
 import { ScreenAnalyzer } from './utils/screen-analyzer.js';
 import { captureToPng } from './utils/screenshot-renderer.js';
@@ -98,6 +106,7 @@ let sandboxTeardownDone = false; // guards the exit-time best-effort teardown fr
  *  (non-forced) config, so healthy restarts (e.g. user `/restart`) are
  *  unaffected. */
 let consecutiveInWorkerRestarts = 0;
+let tmuxRestartTimer = null;
 /** Guard: user_notify for "resume → fresh fallback" is sent once per worker
  *  lifecycle so a 4× crash loop does not spam the Lark thread with 4 copies
  *  of the same warning. */
@@ -289,23 +298,25 @@ const authedClients = new WeakSet();
 /** Per-WS-client tmux/zellij attach PTYs. */
 const clientPtys = new Map();
 const writeToken = randomBytes(16).toString('hex');
+// Active dashboard token, persisted by the dashboard process at this stable
+// path (mirrors dashboard.ts TOKEN_PATH). The platform proxy injects it as the
+// `botmux_dashboard_token` cookie on every request it fronts, so its presence
+// proves a request traversed the platform's authenticated front door.
+const DASHBOARD_TOKEN_PATH = join(homedir(), '.botmux', '.dashboard-token');
 /**
- * Resolve terminal write permission for one request, honoring a platform-injected
- * `X-Botmux-Role` header. The central platform fronts `/s/*` and sets the role
- * (owner | teammate | guest) after authenticating the viewer, stripping any
- * client-supplied header; it reaches the worker via dashboard /s bridge →
- * terminal-proxy → here. When the header is present we trust it (platform-fronted
- * access): only `owner` may drive the terminal; everything else (teammate / guest
- * / anything else) is read-only. When the header is absent (local direct access,
- * no platform in front), fall back to the legacy write-token query param.
+ * Resolve terminal write permission for one request. The platform-injected
+ * `X-Botmux-Role` header is trusted only when this machine is bound to a central
+ * platform AND the request actually came through the platform proxy (proven by a
+ * matching `botmux_dashboard_token` cookie — a secret a direct caller lacks).
+ * Otherwise write falls back to the `?token=` gate. See
+ * ./core/terminal-write-auth for the full rationale.
+ *
+ * Both the binding and the token are read PER REQUEST, never snapshotted:
+ * `botmux bind`/unbind and dashboard token rotation are hot-reloaded without
+ * restarting this worker, so a cached value would go stale.
  */
-function resolveTerminalWrite(req, tokenMatches) {
-    const role = req.headers['x-botmux-role'];
-    if (typeof role === 'string' && role) {
-        const hasWrite = role === 'owner';
-        return { hasWrite, platformReadonly: !hasWrite };
-    }
-    return { hasWrite: tokenMatches, platformReadonly: false };
+function resolveTerminalWriteForReq(req, tokenMatches) {
+    return resolveTerminalWriteForRequest(req.headers, tokenMatches, () => readPlatformBinding() !== null, () => loadPersistedToken(DASHBOARD_TOKEN_PATH));
 }
 /** Lazily-written locked-mode zellij config for per-WS web-terminal attach
  *  clients: cleared keybinds + locked mode so every keystroke passes straight
@@ -326,7 +337,7 @@ function ensureZellijAttachConfig() {
 }
 let sessionId = '';
 let lastInitConfig = null;
-const CLI_DISPLAY_NAMES = { 'claude-code': 'Claude', seed: 'Seed', relay: 'Relay', aiden: 'Aiden', coco: 'CoCo', codex: 'Codex', 'codex-app': 'Codex App', cursor: 'Cursor', gemini: 'Gemini', genius: 'Genius', opencode: 'OpenCode', antigravity: 'Antigravity', mtr: 'MTR', hermes: 'Hermes', mira: 'Mira', mir: 'Mir CLI', traex: 'TRAE', pi: 'Pi', copilot: 'Copilot', 'oh-my-pi': 'Oh My Pi', kimi: 'Kimi' };
+const CLI_DISPLAY_NAMES = { 'claude-code': 'Claude', seed: 'Seed', relay: 'Relay', aiden: 'Aiden', coco: 'CoCo', codex: 'Codex', 'codex-app': 'Codex App', cursor: 'Cursor', gemini: 'Gemini', genius: 'Genius', opencode: 'OpenCode', antigravity: 'Antigravity', mtr: 'MTR', hermes: 'Hermes', mira: 'Mira', mir: 'Mir CLI', traex: 'TRAE', pi: 'Pi', copilot: 'Copilot', 'oh-my-pi': 'Oh My Pi', kimi: 'Kimi', grok: 'Grok Build' };
 function cliName() { return CLI_DISPLAY_NAMES[lastInitConfig?.cliId ?? ''] ?? 'CLI'; }
 let isPromptReady = false;
 /** Mutex for async flushPending — prevents concurrent flush loops. */
@@ -719,6 +730,8 @@ let codexBridgeWatcher = null;
 let codexBridgeTimer = null;
 let hermesBridgeOffset = 0;
 let hermesBridgeBaselineDone = false;
+let hermesBridgeDbPath;
+let hermesBridgeSourceSessionId;
 let mtrBridgeSource;
 let mtrBridgeOffset = 0;
 let mtrBridgeBaselineDone = false;
@@ -1937,18 +1950,10 @@ function drainPathInto(path, fromOffset) {
 // marker IO / type-ahead serialisation / one-write-per-idle break) is
 // shared with the Claude path.
 function codexBridgeFallbackActive() {
-    // True for transcript-backed CLIs whose final output can be harvested
-    // when the model forgets to call `botmux send`.
-    const id = lastInitConfig?.cliId;
-    if (id === 'codex' || id === 'traex' || id === 'coco' || id === 'hermes' || id === 'mtr' || id === 'pi')
-        return true;
-    // Cursor only harvests its transcript in adopt mode: a botmux-spawned
-    // cursor session carries the botmux skill and replies via `botmux send`,
-    // and we never resolve a transcript path for it — so leave that flow
-    // (screen capture + botmux send) untouched and scope the bridge to adopt.
-    if (id === 'cursor')
-        return lastInitConfig?.adoptMode === true;
-    return false;
+    // Transcript-backed CLIs whose final output can be harvested when the
+    // model forgets to call `botmux send`. Cursor is adopt-only — see
+    // services/structured-bridge-clis.ts (single source of the allowlist).
+    return isStructuredBridgeFallbackActive(lastInitConfig?.cliId, lastInitConfig?.adoptMode === true);
 }
 // Both Codex and TRAE share the same rollout JSONL layout (response_item
 // messages), so drainCodexRollout works for both.
@@ -1964,9 +1969,15 @@ function structuredBridgeIsMtr() {
 function structuredBridgeIsPi() {
     return lastInitConfig?.cliId === 'pi';
 }
+function structuredBridgeIsGrok() {
+    return lastInitConfig?.cliId === 'grok';
+}
 function codexBridgeIsCursor() {
     return lastInitConfig?.cliId === 'cursor';
 }
+function currentHermesBridgeDbPath() {
+    return hermesBridgeDbPath ?? resolveHermesStateDbPath();
+}
 function structuredBridgeIngestPath(path, offset) {
     if (structuredBridgeIsCodex())
         return drainCodexRollout(path, offset);
@@ -1974,8 +1985,10 @@ function structuredBridgeIngestPath(path, offset) {
         return drainCursorTranscript(path, offset);
     if (structuredBridgeIsPi())
         return drainPiTranscript(path, offset);
+    if (structuredBridgeIsGrok())
+        return drainGrokUpdates(path, offset);
     if (structuredBridgeIsHermes()) {
-        const result = drainHermesStateDb(offset);
+        const result = drainHermesStateDb(offset, currentHermesBridgeDbPath());
         return { events: result.events, newOffset: result.newOffset, pendingTail: '' };
     }
     return drainCocoEvents(path, offset);
@@ -2050,66 +2063,19 @@ function codexBridgeStartTimer() {
                 return;
             }
             if (!codexBridgeRolloutPath) {
-                // Two discovery paths, in order: cliSessionId (known via writeInput
-                // result for non-adopt or daemon-side probe for adopt) → exact
-                // file by name; PID (adopt only) → walk /proc/<pid>/fd. Adopt
-                // attaches via split-live (history absorbed, live ingested);
-                // non-adopt uses fresh-empty (queue's markTimeMs - 5s lower bound
-                // gates historical fingerprint matches without needing a split).
-                // Discovery primitives differ per CLI: codex walks ~/.codex/sessions
-                // by sid suffix; CoCo's events.jsonl path is deterministic from
-                // sid, so the lookup is just a path computation + existence check.
-                const isCoco = lastInitConfig?.cliId === 'coco';
-                const isTraex = lastInitConfig?.cliId === 'traex';
-                const isPi = lastInitConfig?.cliId === 'pi';
-                let path;
-                if (codexBridgePendingSessionId) {
-                    if (isCoco) {
-                        path = cocoEventsPathForSession(codexBridgePendingSessionId);
-                        if (path && !existsSync(path))
-                            path = undefined;
-                    }
-                    else if (isPi) {
-                        path = findPiTranscriptBySessionId(codexBridgePendingSessionId, lastInitConfig?.workingDir);
-                    }
-                    else if (isTraex) {
-                        path = findTraexRolloutBySessionId(codexBridgePendingSessionId);
-                    }
-                    else {
-                        path = findCodexRolloutBySessionId(codexBridgePendingSessionId);
-                    }
-                }
-                if (!path && codexAdoptPendingPid) {
-                    if (isCoco) {
-                        const probed = findCocoSessionByPid(codexAdoptPendingPid);
-                        if (probed && existsSync(probed.eventsPath))
-                            path = probed.eventsPath;
-                    }
-                    else if (isPi) {
-                        const probed = findPiTranscriptByPid(codexAdoptPendingPid);
-                        if (probed)
-                            path = probed.path;
-                    }
-                    else if (isTraex) {
-                        const probed = findTraexRolloutByPid(codexAdoptPendingPid);
-                        if (probed)
-                            path = probed.path;
-                    }
-                    else {
-                        const probed = findCodexRolloutByPid(codexAdoptPendingPid);
-                        if (probed)
-                            path = probed.path;
-                    }
-                }
+                // Late-attach: cliSessionId (writeInput / daemon probe) then adopt
+                // pid. Path lookup is centralized in resolveFileBridgePath so
+                // adding a file-backed CLI does not grow this if-tree.
+                // Adopt → split-live; non-adopt → fresh-empty (queue markTimeMs
+                // lower bound handles history without a split).
+                const path = resolveFileBridgePath(lastInitConfig?.cliId, {
+                    sessionId: codexBridgePendingSessionId,
+                    cwd: lastInitConfig?.workingDir,
+                    pid: codexAdoptPendingPid,
+                });
                 if (path) {
                     codexBridgePendingSessionId = undefined;
                     codexAdoptPendingPid = undefined;
-                    // Adopt mode: split-live partitions drained events by
-                    // codexAdoptStartMs so anything the user did AFTER adopt but
-                    // BEFORE we found the rollout still emits (history is absorbed,
-                    // live is ingested). Non-adopt: fresh-empty as before — queue's
-                    // markTimeMs - 5s lower bound is enough since there's no
-                    // local-turn synthesis on that path.
                     const mode = lastInitConfig?.adoptMode ? 'split-live' : 'fresh-empty';
                     codexBridgeAttach(path, mode);
                 }
@@ -2124,20 +2090,38 @@ function codexBridgeStartTimer() {
     }, 1000);
 }
 function hermesBridgeAttach(mode) {
-    hermesBridgeOffset = currentHermesStateOffset();
+    const dbPath = currentHermesBridgeDbPath();
+    hermesBridgeOffset = currentHermesStateOffset(dbPath);
     hermesBridgeBaselineDone = true;
-    log(`Hermes bridge ${mode}: state.db offset=${hermesBridgeOffset}`);
+    hermesBridgeSourceSessionId = undefined;
+    log(`Hermes bridge ${mode}: ${dbPath} offset=${hermesBridgeOffset}`);
     codexBridgeStartTimer();
 }
 function hermesBridgeIngest() {
     if (!hermesBridgeBaselineDone)
         return;
-    const result = drainHermesStateDb(hermesBridgeOffset);
+    const result = drainHermesStateDb(hermesBridgeOffset, currentHermesBridgeDbPath());
     hermesBridgeOffset = result.newOffset;
-    if (result.events.length > 0)
+    const filtered = filterHermesEventsForBotmuxSession(result.events, {
+        botmuxSessionId: sessionId,
+        boundSourceSessionId: hermesBridgeSourceSessionId,
+    });
+    // Announce EVERY source bound this drain, not just the last. A single drain
+    // can bind multiple sources when the worker starts unbound and Hermes
+    // `/clear`-rotates mid-batch; the daemon accumulates them into its authorized
+    // set, so a completed turn from an earlier source is not dropped as foreign.
+    for (const boundSourceSessionId of filtered.newlyBoundSourceSessionIds) {
+        send({ type: 'bridge_source_session', bridge: 'hermes', sourceSessionId: boundSourceSessionId });
+        log(`Hermes bridge bound sourceSessionId=${boundSourceSessionId}`);
+    }
+    hermesBridgeSourceSessionId = filtered.boundSourceSessionId;
+    for (const drop of filtered.drops) {
+        log(`Hermes bridge dropped ${drop.kind} ${drop.uuid} from sourceSessionId=${drop.sourceSessionId ?? '?'} expected=${drop.expectedSourceSessionId ?? hermesBridgeSourceSessionId ?? 'unbound'} reason=${drop.reason}`);
+    }
+    if (filtered.events.length > 0)
         lastStructuredBridgeActivityAtMs = Date.now();
-    codexBridgeQueue.ingest(result.events);
-    if (result.events.some(e => e.kind === 'assistant_final')) {
+    codexBridgeQueue.ingest(filtered.events);
+    if (filtered.events.some(e => e.kind === 'assistant_final')) {
         idleDetector?.fireIdle();
     }
 }
@@ -2302,12 +2286,60 @@ function cursorBridgeAttach(path, mode = 'baseline-existing') {
     }
     codexBridgeAttach(path, mode === 'baseline-existing' ? 'baseline-existing-skip-tail' : mode);
 }
+/** Drop the current file-backed bridge attachment (watcher + path cursor).
+ *  Does NOT clear the pending-turn queue — mid-rotation submits still need
+ *  fingerprint matching against the next attach. */
+function codexBridgeDetachFile() {
+    if (codexBridgeWatcher) {
+        try {
+            codexBridgeWatcher.close();
+        }
+        catch { /* ignore */ }
+        codexBridgeWatcher = null;
+    }
+    codexBridgeRolloutPath = undefined;
+    codexBridgeOffset = 0;
+    codexBridgePendingTail = '';
+    codexBridgeBaselineDone = false;
+}
 /** Called from flushPending after writeInput first returns a cliSessionId.
  *  Tries to locate the rollout file immediately; if it's not on disk yet,
  *  remembers the sid so the 1s poller can keep retrying. */
 function codexBridgeNotifyCliSessionId(cliSessionId) {
-    if (!codexBridgeFallbackActive() || codexBridgeRolloutPath)
+    if (!codexBridgeFallbackActive())
         return;
+    if (codexBridgeRolloutPath) {
+        // Already attached — first-attach-wins for most CLIs. Exception: grok's
+        // `/new` / `/clear` / `/resume` rotate to a NEW session directory at the
+        // SAME pid, and writeInput's prompt_history verify reports the new
+        // session id on the very next submit. Without a re-attach the bridge
+        // stays wedged on the old updates.jsonl and the reply fallback / idle
+        // signal go dark for the rest of the session.
+        if (structuredBridgeIsGrok()) {
+            const currentSid = grokSessionIdFromPath(codexBridgeRolloutPath);
+            if (currentSid && currentSid.toLowerCase() === cliSessionId.toLowerCase())
+                return;
+            const next = resolveFileBridgePath('grok', {
+                sessionId: cliSessionId,
+                cwd: lastInitConfig?.workingDir,
+            });
+            if (next && next !== codexBridgeRolloutPath) {
+                log(`Grok session rotated ${currentSid ?? '?'} → ${cliSessionId}; re-attaching bridge to ${next}`);
+                codexBridgeDetachFile();
+                codexBridgePendingSessionId = undefined;
+                codexBridgeAttach(next, 'fresh-empty');
+            }
+            else if (!next) {
+                // New session id reported but updates.jsonl not on disk yet —
+                // detach the retired session and arm the poller for late-attach.
+                log(`Grok session rotated ${currentSid ?? '?'} → ${cliSessionId}; waiting for updates.jsonl`);
+                codexBridgeDetachFile();
+                codexBridgePendingSessionId = cliSessionId;
+                codexBridgeStartTimer();
+            }
+        }
+        return;
+    }
     if (structuredBridgeIsMtr()) {
         const source = findMtrSessionById(cliSessionId);
         if (source) {
@@ -2323,7 +2355,7 @@ function codexBridgeNotifyCliSessionId(cliSessionId) {
     if (codexBridgeIsCursor()) {
         // Cursor's cliSessionId is the chatId — the same UUID naming the
         // agent-transcript JSONL, so it resolves the path directly.
-        const cursorPath = findCursorTranscriptByChatId(cliSessionId);
+        const cursorPath = resolveFileBridgePath('cursor', { sessionId: cliSessionId });
         if (cursorPath) {
             codexBridgePendingSessionId = undefined;
             cursorBridgeAttach(cursorPath, cursorLateAttachMode(cursorPath));
@@ -2334,11 +2366,10 @@ function codexBridgeNotifyCliSessionId(cliSessionId) {
         }
         return;
     }
-    const path = lastInitConfig?.cliId === 'traex'
-        ? findTraexRolloutBySessionId(cliSessionId)
-        : lastInitConfig?.cliId === 'pi'
-            ? findPiTranscriptBySessionId(cliSessionId, lastInitConfig?.workingDir)
-            : findCodexRolloutBySessionId(cliSessionId);
+    const path = resolveFileBridgePath(lastInitConfig?.cliId, {
+        sessionId: cliSessionId,
+        cwd: lastInitConfig?.workingDir,
+    });
     if (path) {
         codexBridgePendingSessionId = undefined;
         codexBridgeAttach(path, 'fresh-empty');
@@ -2423,6 +2454,7 @@ function emitReadyCodexTurns() {
         const turn = ready[i];
         if (!turn.finalText)
             continue;
+        const sourceHermesSessionId = structuredBridgeIsHermes() ? turn.sourceSessionId : undefined;
         const nextBoundaryMs = (i + 1 < ready.length ? ready[i + 1].markTimeMs : nextPendingMarkTimeMs);
         if (shouldSuppressBridgeEmit({ markTimeMs: turn.markTimeMs, isLocal: turn.isLocal, finalText: turn.finalText }, nextBoundaryMs, markers, adoptMode)) {
             log(`Codex bridge fallback suppressed for turn ${turn.turnId.substring(0, 8)} (gate)`);
@@ -2438,6 +2470,7 @@ function emitReadyCodexTurns() {
                 continue;
             send({
                 type: 'final_output',
+                ...(sourceHermesSessionId ? { sourceHermesSessionId } : {}),
                 content: fields.content,
                 lastUuid: turn.turnId,
                 turnId: turn.turnId,
@@ -2446,7 +2479,13 @@ function emitReadyCodexTurns() {
             });
             continue;
         }
-        send({ type: 'final_output', content: turn.finalText, lastUuid: turn.turnId, turnId: turn.turnId });
+        send({
+            type: 'final_output',
+            ...(sourceHermesSessionId ? { sourceHermesSessionId } : {}),
+            content: turn.finalText,
+            lastUuid: turn.turnId,
+            turnId: turn.turnId,
+        });
     }
 }
 function stopCodexBridge() {
@@ -2467,6 +2506,7 @@ function stopCodexBridge() {
     codexBridgeBaselineDone = false;
     hermesBridgeOffset = 0;
     hermesBridgeBaselineDone = false;
+    hermesBridgeSourceSessionId = undefined;
     mtrBridgeSource = undefined;
     mtrBridgeOffset = 0;
     mtrBridgeBaselineDone = false;
@@ -4041,43 +4081,45 @@ function setupAdoptTranscriptBridges(cfg) {
             codexBridgeStartTimer();
         }
     }
-    else if (cfg.cliId === 'pi') {
-        const adoptStartMs = Date.now();
-        codexAdoptStartMs = adoptStartMs;
-        codexBridgeQueue.setLocalTurns(true, adoptStartMs);
-        let path;
+    else if (cfg.cliId === 'pi' || cfg.cliId === 'grok') {
+        // File-backed bridges share the same adopt attach skeleton (sid → pid →
+        // split-live | pending). Path lookup is resolveFileBridgePath; pi is
+        // intentionally folded here with grok so the two stay in lockstep.
+        setupAdoptFileBridge(cfg);
+    }
+}
+/** Adopt attach for file-backed structured bridges (pi/grok today; codex/
+ *  traex keep their own branches for rollout-specific probes). */
+function setupAdoptFileBridge(cfg) {
+    const adoptStartMs = Date.now();
+    codexAdoptStartMs = adoptStartMs;
+    codexBridgeQueue.setLocalTurns(true, adoptStartMs);
+    const path = resolveFileBridgePath(cfg.cliId, {
+        sessionId: cfg.cliSessionId,
+        cwd: cfg.adoptCwd ?? cfg.workingDir,
+        pid: cfg.adoptCliPid,
+    });
+    if (path) {
+        codexBridgeAttach(path, 'split-live');
+    }
+    else {
         if (cfg.cliSessionId)
-            path = findPiTranscriptBySessionId(cfg.cliSessionId, cfg.adoptCwd ?? cfg.workingDir);
-        if (!path && cfg.adoptCliPid) {
-            const probed = findPiTranscriptByPid(cfg.adoptCliPid);
-            if (probed)
-                path = probed.path;
-        }
-        if (path) {
-            codexBridgeAttach(path, 'split-live');
-        }
-        else {
-            if (cfg.cliSessionId)
-                codexBridgePendingSessionId = cfg.cliSessionId;
-            codexAdoptPendingPid = cfg.adoptCliPid;
-            codexBridgeStartTimer();
-        }
+            codexBridgePendingSessionId = cfg.cliSessionId;
+        codexAdoptPendingPid = cfg.adoptCliPid;
+        codexBridgeStartTimer();
     }
 }
 function adoptIdleAdapter(cfg) {
     return cfg.bridgeJsonlPath
         ? createCliAdapterSync('claude-code', undefined)
-        : cfg.cliId === 'codex' || cfg.cliId === 'traex' || cfg.cliId === 'coco' || cfg.cliId === 'mtr' || cfg.cliId === 'pi'
+        : isStructuredBridgeAdoptIdleCli(cfg.cliId)
             ? createCliAdapterSync(cfg.cliId, undefined)
             : { completionPattern: undefined, readyPattern: undefined };
 }
 function setupAdoptInputAdapter(cfg) {
-    if (cfg.cliId === 'codex' || cfg.cliId === 'traex' || cfg.cliId === 'pi') {
+    if (isStructuredBridgeAdoptInputCli(cfg.cliId)) {
         cliAdapter = createCliAdapterSync(cfg.cliId, cfg.cliPathOverride);
     }
-    else if (cfg.cliId === 'mtr') {
-        cliAdapter = createCliAdapterSync('mtr', cfg.cliPathOverride);
-    }
 }
 function setupAdoptIdleDetection(cfg, label) {
     idleDetector = new IdleDetector(adoptIdleAdapter(cfg));
@@ -4211,8 +4253,16 @@ function spawnCli(cfg) {
         });
         effectiveBackendType = 'herdr';
         backend = herdrBe;
+        // Same as tmux/zellij adopt: writeInput (grok preferSessionId via
+        // findGrokSessionByPid, claude pid-state) needs cliPid/cliCwd on the
+        // PtyHandle. spawn() overwrites cliCwd from opts.cwd — use adoptCwd when
+        // present so session discovery stays on the CLI's real working dir.
+        if (cfg.adoptCliPid)
+            herdrBe.cliPid = cfg.adoptCliPid;
+        const herdrAdoptCwd = cfg.adoptCwd ?? cfg.workingDir;
+        herdrBe.cliCwd = herdrAdoptCwd;
         herdrBe.spawn('', [], {
-            cwd: cfg.workingDir,
+            cwd: herdrAdoptCwd,
             cols,
             rows,
             env: process.env,
@@ -4252,6 +4302,12 @@ function spawnCli(cfg) {
             : new TmuxPipeBackend(cfg.adoptTmuxTarget, { cliPid: cfg.adoptCliPid });
         effectiveBackendType = cfg.adoptZellijPaneId ? 'zellij' : 'tmux';
         backend = observeBe;
+        // writeInput (grok concurrent prompt_history binding, claude pid-state)
+        // reads these fields off the PtyHandle — constructor only stores
+        // watchCliPid for liveness, so surface them explicitly for adopt.
+        if (cfg.adoptCliPid)
+            observeBe.cliPid = cfg.adoptCliPid;
+        observeBe.cliCwd = cfg.adoptCwd ?? cfg.workingDir;
         observeBe.spawn('', [], {
             cwd: cfg.workingDir,
             cols,
@@ -4300,7 +4356,7 @@ function spawnCli(cfg) {
         if (effectiveBackend === 'tmux') {
             hasExistingSession = TmuxBackend.hasSession(TmuxBackend.sessionName(cfg.sessionId));
             if (!hasExistingSession) {
-                const probe = probeTmuxFunctional();
+                const probe = probeTmuxFunctionalWithRetry();
                 available = probe.ok;
                 if (!probe.ok)
                     reason = probe.reason;
@@ -4759,6 +4815,10 @@ function spawnCli(cfg) {
     const perBotInjectKeys = Object.keys(perBotInjectEnv);
     if (perBotInjectKeys.length)
         log(`Injecting ${perBotInjectKeys.length} per-bot env var(s): ${perBotInjectKeys.join(', ')}`);
+    const hermesUsesBotmuxSessionProfile = basename(cfg.cliPathOverride ?? '') === 'hermes-botmux-session';
+    hermesBridgeDbPath = cfg.cliId === 'hermes'
+        ? resolveHermesStateDbPath({ ...childEnv, ...perBotInjectEnv }, { botmuxSessionProfile: hermesUsesBotmuxSessionProfile })
+        : undefined;
     // ── 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).
@@ -5047,15 +5107,15 @@ function spawnCli(cfg) {
         startWrapperRealPidResolve(cliPid);
     if (cliPid)
         observeCursorCliSessionId(cliPid);
-    // Wire pid + cwd so the claude-code adapter's writeInput can read
-    // ~/.claude/sessions/<pid>.json — the spawn-time pid-state record. Its
-    // `sessionId` is set ONCE at process start (Claude Code 2.1.123); a
-    // `--resume` lookup will surface here, but in-pane `/clear` won't, so a
-    // 'matching sessionId' answer is "no spawn-time rotation observed", not
-    // "no rotation at all". The pinned claudeJsonlPath above is still the
-    // initial guess; the resolver corrects it on first write when Claude was
-    // started with `--resume`.
-    if (claudeDataDir && cliPid) {
+    // Wire pid + cwd so adapters' writeInput can bind submits to this process:
+    //   - claude-code: ~/.claude/sessions/<pid>.json
+    //   - grok: findGrokSessionByPid → preferSessionId against shared
+    //     prompt_history (concurrent same-cwd workers must not cross-claim)
+    // Claude's sessionId is set ONCE at process start (2.1.123); a `--resume`
+    // lookup will surface here, but in-pane `/clear` won't. The pinned
+    // claudeJsonlPath above is still the initial guess; the resolver corrects
+    // it on first write when Claude was started with `--resume`.
+    if (cliPid && (claudeDataDir || cfg.cliId === 'grok')) {
         backend.cliPid = cliPid;
         backend.cliCwd = cfg.workingDir;
     }
@@ -5085,7 +5145,7 @@ function spawnCli(cfg) {
                         log(`Failed to write CLI PID marker (async): ${err.message}`);
                     }
                 }
-                if (claudeDataDir) {
+                if (claudeDataDir || cfg.cliId === 'grok') {
                     backend.cliPid = pid;
                     backend.cliCwd = cfg.workingDir;
                 }
@@ -5192,17 +5252,21 @@ function spawnCli(cfg) {
             codexBridgeStartTimer();
         }
     }
-    else if (cfg.cliId === 'pi') {
-        const piSessionId = effectiveCliSessionId ?? effectiveAdapterSessionId;
-        if (piSessionId) {
-            const transcriptPath = findPiTranscriptBySessionId(piSessionId, cfg.workingDir);
-            if (transcriptPath) {
-                codexBridgeAttach(transcriptPath, effectiveResume ? 'baseline-existing' : 'fresh-empty');
-            }
-            else {
-                codexBridgePendingSessionId = piSessionId;
-                codexBridgeStartTimer();
-            }
+    else if (cfg.cliId === 'pi' || cfg.cliId === 'grok') {
+        // File-backed: pin path when known (pi session id / grok --session-id
+        // UUID), else arm the poller. Grok collision-fallback (dir already
+        // exists → no --session-id → grok mints id) is recovered via writeInput
+        // → codexBridgeNotifyCliSessionId.
+        const sid = effectiveCliSessionId ?? effectiveAdapterSessionId;
+        const path = sid
+            ? resolveFileBridgePath(cfg.cliId, { sessionId: sid, cwd: cfg.workingDir })
+            : undefined;
+        if (path) {
+            codexBridgeAttach(path, effectiveResume ? 'baseline-existing' : 'fresh-empty');
+        }
+        else if (sid) {
+            codexBridgePendingSessionId = sid;
+            codexBridgeStartTimer();
         }
         else {
             codexBridgeStartTimer();
@@ -5411,7 +5475,7 @@ function startWebServer(host, preferredPort) {
                 return;
             }
             const tokenMatches = url.searchParams.get('token') === writeToken;
-            const { hasWrite, platformReadonly } = resolveTerminalWrite(req, tokenMatches);
+            const { hasWrite, platformReadonly } = resolveTerminalWriteForReq(req, tokenMatches);
             const loginHdr = req.headers['x-botmux-login-url'];
             const loginUrl = typeof loginHdr === 'string' && /^https?:\/\/[^"'<>\s]+$/.test(loginHdr) ? loginHdr : '';
             res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
@@ -5429,7 +5493,7 @@ function startWebServer(host, preferredPort) {
                 return;
             }
             const tokenMatches = url.searchParams.get('token') === writeToken;
-            const { hasWrite } = resolveTerminalWrite(req, tokenMatches);
+            const { hasWrite } = resolveTerminalWriteForReq(req, tokenMatches);
             if (hasWrite)
                 authedClients.add(ws);
             log(`WS client connected (total: ${wsClients.size}, write: ${hasWrite})`);
@@ -5787,6 +5851,45 @@ try{
   try{term.loadAddon(new CanvasAddon.CanvasAddon())}catch(_e2){}
 }
 fit.fit();
+// xterm parses writes asynchronously.  On a brand-new page the first tmux /
+// zellij frame (or relay history seed) can therefore finish after the browser
+// has initialised the viewport scrollbar, leaving that viewport at scrollTop=0
+// even though the buffer already contains newer rows.  Follow only the initial
+// write burst and explicitly settle at the bottom.  Any deliberate user scroll
+// cancels this so loading a busy session never fights the reader.
+var _initialFollow=true,_initialFollowT=0;
+function _cancelInitialFollow(){
+  if(!_initialFollow)return;
+  _initialFollow=false;clearTimeout(_initialFollowT);
+}
+function _settleInitialBottom(){
+  if(!_initialFollow)return;
+  try{term.scrollToBottom()}catch(_e){}
+  clearTimeout(_initialFollowT);
+  _initialFollowT=setTimeout(function(){
+    if(!_initialFollow)return;
+    try{term.scrollToBottom()}catch(_e){}
+    _initialFollow=false;
+  },500);
+}
+var _initialViewport=term.element&&term.element.querySelector('.xterm-viewport');
+var _initialTerminalRoot=document.getElementById('terminal');
+if(_initialTerminalRoot){
+  // Listen above xterm's own root: its wheel handler can stop propagation at
+  // the target, while this ancestor still sees capture-phase user intent.
+  _initialTerminalRoot.addEventListener('wheel',_cancelInitialFollow,{capture:true,passive:true});
+  _initialTerminalRoot.addEventListener('touchstart',_cancelInitialFollow,{capture:true,passive:true});
+}
+if(_initialViewport){
+  _initialViewport.addEventListener('pointerdown',function(e){
+    // A pointer press on the native scrollbar targets the viewport itself;
+    // presses on terminal cells target the screen/canvas and keep following.
+    if(e.target===_initialViewport)_cancelInitialFollow();
+  },{capture:true});
+}
+window.addEventListener('keydown',function(e){
+  if(e.key==='PageUp'||e.key==='PageDown'||e.key==='Home'||e.key==='End')_cancelInitialFollow();
+},{capture:true});
 // ── OSC 52 clipboard ──
 var _clipBuf='';
 function _doCopy(text){
@@ -5872,7 +5975,7 @@ window.addEventListener('resize',onViewportResize);
     // Intercept OSC 52 clipboard sequence from tmux (set-clipboard on)
     var m=data.match(/\\x1b\\]52;[^;]*;([A-Za-z0-9+/=]+)(?:\\x07|\\x1b\\\\)/);
     if(m){try{_clipBuf=new TextDecoder().decode(Uint8Array.from(atob(m[1]),function(c){return c.charCodeAt(0)}));_doCopy(_clipBuf);_showCopied()}catch(ex){}}
-    term.write(data);
+    term.write(data,_settleInitialBottom);
   };
   ws.onclose=function(){ws_=null;el.textContent='disconnected';el.className='err';setTimeout(connect,2000)};
   ws.onerror=function(){ws.close()};
@@ -6165,17 +6268,18 @@ process.on('message', async (raw) => {
                     }
                 }
                 // Adopt mode write:
-                //   - codex routes through cliAdapter.writeInput so the adapter's
-                //     paste-detection delay + Enter-retry + history.jsonl verify
-                //     loop handles Codex TUI's "\n treated as Enter" submit
-                //     behaviour. Without it, Lark messages get stranded in the
-                //     input box (user-reported "卡在输入框中").
+                //   - Structured-bridge adopt-input CLIs (codex/traex/pi/grok/mtr)
+                //     route through cliAdapter.writeInput so paste+Enter-retry +
+                //     transcript/history verify (and grok's prompt_history →
+                //     cliSessionId re-attach after /new) all run. Hardcoding only
+                //     codex/traex left grok on raw sendText, so /new rotation never
+                //     re-attached the bridge.
                 //   - everything else keeps the simple raw sendText+Enter — the
                 //     claude-code adopt bridge has its own dual-write recovery
                 //     path, and the other CLIs' adopt flows haven't surfaced
                 //     this submit-detection issue.
                 if (backend) {
-                    if ((lastInitConfig?.cliId === 'codex' || lastInitConfig?.cliId === 'traex') && cliAdapter) {
+                    if (isStructuredBridgeAdoptInputCli(lastInitConfig?.cliId) && cliAdapter) {
                         // writeInput is async but we're already inside an async
                         // message handler. Errors are best-effort logged; the bridge
                         // ingest path is unaffected because mark already happened
@@ -6187,11 +6291,11 @@ process.on('message', async (raw) => {
                                 codexBridgeNotifyCliSessionId(result.cliSessionId);
                             }
                             if (result && result.submitted === false) {
-                                scheduleSubmitFailureNotify(content, result.recheck, 'Codex history', undefined, result.failureReason, turnSeq);
+                                scheduleSubmitFailureNotify(content, result.recheck, 'submit history', undefined, result.failureReason, turnSeq);
                             }
                         }
                         catch (err) {
-                            log(`Codex adopt writeInput error: ${err.message}`);
+                            log(`Adopt writeInput error (${lastInitConfig?.cliId}): ${err.message}`);
                         }
                     }
                     else if ('sendText' in backend && 'sendSpecialKeys' in backend) {
@@ -6291,16 +6395,29 @@ process.on('message', async (raw) => {
             // process would never actually restart. destroySession() tears the session
             // down so the respawn starts a fresh CLI. (PTY has no destroySession, so
             // the ?. no-ops and killCli()'s kill() does the teardown.)
-            backend?.destroySession?.();
-            killCli();
-            awaitingFirstPrompt = true;
-            setTimeout(() => {
-                if (lastInitConfig) {
-                    startScreenUpdates();
-                    startScreenAnalyzer();
-                    spawnCli({ ...lastInitConfig, resume: true, prompt: '' });
-                }
-            }, 500);
+            const restart = () => {
+                tmuxRestartTimer = null;
+                backend?.destroySession?.();
+                killCli();
+                awaitingFirstPrompt = true;
+                setTimeout(() => {
+                    if (lastInitConfig) {
+                        startScreenUpdates();
+                        startScreenAnalyzer();
+                        spawnCli({ ...lastInitConfig, resume: true, prompt: '' });
+                    }
+                }, 500);
+            };
+            if (effectiveBackendType === 'tmux') {
+                const delayMs = tmuxRestartJitterMs(lastInitConfig?.sessionId ?? '', consecutiveInWorkerRestarts);
+                log(`Staggering tmux teardown/restart by ${delayMs}ms to avoid shared-server probe storms`);
+                if (tmuxRestartTimer)
+                    clearTimeout(tmuxRestartTimer);
+                tmuxRestartTimer = setTimeout(restart, delayMs);
+            }
+            else {
+                restart();
+            }
             break;
         }
         case 'tui_keys': {
@@ -6425,6 +6542,10 @@ process.on('message', async (raw) => {
 });
 // ─── Cleanup ─────────────────────────────────────────────────────────────────
 function cleanup() {
+    if (tmuxRestartTimer) {
+        clearTimeout(tmuxRestartTimer);
+        tmuxRestartTimer = null;
+    }
     for (const [, cp] of clientPtys) {
         try {
             cp.kill();