botmux 3.4.3 → 3.5.0

package/dist/worker.js

@@ -15,11 +15,11 @@
 import { randomBytes } from 'node:crypto';
 import { mkdirSync, writeFileSync, unlinkSync, rmdirSync, existsSync, statSync, lstatSync, readdirSync, readlinkSync, readFileSync, realpathSync, copyFileSync, watch as fsWatch, createWriteStream, openSync, closeSync, fstatSync, constants as fsConstants } from 'node:fs';
 import { atomicWriteFileSync } from './utils/atomic-write.js';
-import { join, basename, dirname } from 'node:path';
+import { join, basename, dirname, delimiter } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { evaluateReadIsolationGate, evaluateCredentialOnlyIsolationGate, credentialIsolationRequired, deviceCredentialIsolationMarkerPath, isCredentialIsolationReservedBasename, buildCredentialIsolationRules, buildSeatbeltProfile, isolatedPaneReattachSafe, sendCredFilePath, botHomePath, buildV2DenyPaths, buildV2DenyRegexes, buildV2CarveOuts, buildReadIsolationProtectedWriteRules, buildCliExecutableReadCarveOuts, buildWriteSandboxRules, buildLinuxReadIsolationMasks, isolationPaneMarkerContent, } from './adapters/cli/read-isolation.js';
-import { killPersistentSession } from './core/persistent-backend.js';
+import { killPersistentBackendTarget, killPersistentSession, probePersistentBackendTarget } from './core/persistent-backend.js';
 import { readProcessStartIdentity } from './core/session-marker.js';
 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';
@@ -42,14 +42,17 @@ import { readSessionMcpRuntimeManifest, sessionMcpRuntimeHostOnlyPaths, } from '
 import { prepareCliPluginGeneration } from './core/plugins/cli-generation.js';
 import { loadBotConfigs } from './bot-registry.js';
 import { readGlobalConfig } from './global-config.js';
-import { deriveTerminalViewToken, resolveTerminalAccessForRequest, safeTerminalTokenEqual, } from './core/terminal-write-auth.js';
+import { deriveTerminalViewToken, deriveTerminalWriteToken, resolveTerminalAccessForRequest, safeTerminalTokenEqual, } from './core/terminal-write-auth.js';
 import { readPlatformBinding } from './platform/binding.js';
 import { loadDashboardSecret, 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 { generateCodexAppThreadTitle, readCodexAppThreadMetadata, setCodexAppThreadName, } from './services/codex-app-threads.js';
+import { buildBotmuxLarkNativeSessionTitle } from './core/session-title.js';
 import { drainCodexRollout, findCodexRolloutBySessionId, findCodexRolloutByPid, splitCodexEventsByCutoff, extractLastCodexTurn, codexSessionIdFromRolloutPath } from './services/codex-transcript.js';
 import { drainTraexRollout, findTraexRolloutBySessionId, findTraexRolloutByPid } from './services/traex-transcript.js';
+import { parseTraexUserInputQuestions } from './services/traex-user-input.js';
 import { cocoEventsPathForSession, drainCocoEvents, findCocoSessionByPid } from './services/coco-transcript.js';
 import { currentHermesStateOffset, drainHermesStateDb, resolveHermesStateDbPath } from './services/hermes-transcript.js';
 import { filterHermesEventsForBotmuxSession } from './services/hermes-session-filter.js';
@@ -87,6 +90,7 @@ import { ZellijObserveBackend } from './adapters/backend/zellij-observe-backend.
 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 { buildReproduceCommand, selectReproduceLaunch } from './adapters/backend/reproduce-command.js';
 import { deriveRiffReposFromDirs, deriveRiffRepoFromWorkingDir, isValidRiffBaseUrl, isValidRiffSandboxCluster, } from './adapters/backend/riff-backend.js';
 import { prepareSandbox, prepareCredentialOnlySandbox, credentialOnlySandboxAvailable, probeHostCredentialIsolationMechanism, attachSandboxOutbox, startOutboxWatcher, sandboxEnabled, sandboxedClaudeDataDir, localSandboxApplies, } from './adapters/backend/sandbox.js';
 import { DEVICE_AUTHORITY_DIRECTORY, DEVICE_CREDENTIAL_FILE, } from './platform/device-paths.js';
@@ -94,6 +98,8 @@ 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 { StuckDetector, matchHookReviewScreen } from './utils/stuck-detector.js';
+import { processStuckWarningTuiKeys, shouldRearmStuckDetector } from './utils/stuck-key-guard.js';
 import { captureToPng } from './utils/screenshot-renderer.js';
 import { snapshotToPng, snapshotToText, shouldCaptureScreen, isScreenSelfDriven } from './utils/transient-snapshot.js';
 import { chooseWebTerminalSeed } from './utils/web-terminal-seed.js';
@@ -109,7 +115,8 @@ import * as pty from 'node-pty';
 import { createHash } from 'node:crypto';
 import { hasInstalledSessionReadyHook, installHook, } from './adapters/hook-installer.js';
 import { hookCommandFor } from './adapters/hook-command.js';
-import { parseDaemonIpcPort } from './utils/daemon-discovery.js';
+import { findOnlineDaemon, parseDaemonIpcPort } from './utils/daemon-discovery.js';
+import { fetchDaemonIpc } from './core/daemon-ipc-auth.js';
 import { withCodexAppContext } from './utils/codex-app-context.js';
 import { resolveCodexAppFinalTurnIdentity } from './adapters/cli/codex-app-turn.js';
 import { RunnerControlDecoder } from './adapters/cli/runner-control-channel.js';
@@ -250,6 +257,238 @@ async function codexRolloutProbe(cliId, threadId, promptText, timeoutMs) {
     } while (Date.now() < deadline);
     return false;
 }
+function codexNativeTitleEnv(cfg) {
+    const env = {
+        ...redactChildEnv(process.env),
+        ...sanitizePerBotEnv(cfg.env),
+    };
+    env.PATH = `${join(homedir(), '.botmux', 'bin')}${delimiter}${env.PATH ?? ''}`;
+    return env;
+}
+function registerNativeTitleForceClose(forceClose) {
+    nativeSessionTitleSyncForceClosers.add(forceClose);
+    return () => nativeSessionTitleSyncForceClosers.delete(forceClose);
+}
+async function applyCodexNativeSessionTitle(threadId, title, cfg, engine, wait, expectedRevision) {
+    if (expectedRevision !== nativeSessionTitleRevision)
+        return false;
+    if (engine?.activeThreadId === threadId) {
+        if (wait === 'resume') {
+            await engine.waitForThreadUpdatedAfter(nativeSessionTitleResumeUpdatedAt ?? Math.floor(Date.now() / 1000), 10_000);
+        }
+        else if (wait === 'preview') {
+            await engine.waitForThreadPreview(10_000);
+        }
+        if (expectedRevision !== nativeSessionTitleRevision)
+            return false;
+        await engine.setThreadName(title);
+        return true;
+    }
+    const adapter = createCliAdapterSync('codex', cfg.cliPathOverride);
+    const abortController = new AbortController();
+    nativeSessionTitleSyncAbortControllers.add(abortController);
+    try {
+        await setCodexAppThreadName({
+            threadId,
+            name: title,
+            codexBin: adapter.resolvedBin,
+            cwd: cfg.workingDir,
+            env: codexNativeTitleEnv(cfg),
+            timeoutMs: 10_000,
+            signal: abortController.signal,
+            detached: true,
+            waitForExistingPreview: wait === 'preview',
+            ...(wait === 'resume' ? {
+                waitForUpdatedAfter: nativeSessionTitleResumeUpdatedAt ?? Math.floor(Date.now() / 1000),
+            } : {}),
+            registerForceClose: registerNativeTitleForceClose,
+        });
+        return expectedRevision === nativeSessionTitleRevision;
+    }
+    finally {
+        nativeSessionTitleSyncAbortControllers.delete(abortController);
+    }
+}
+/** 首条 UserMessage 落盘后先写 fallback，再用隔离的临时 turn 生成语义标题。 */
+async function syncFreshCodexNativeSessionTitle(threadId, engine) {
+    const cfg = lastInitConfig;
+    const fallbackTitle = cfg?.nativeSessionTitle?.trim();
+    if (!cfg || cfg.cliId !== 'codex' || cfg.adoptMode || !fallbackTitle || !threadId)
+        return;
+    if (nativeSessionTitleAppliedThreadId === threadId || nativeSessionTitleSyncInFlight === threadId)
+        return;
+    const revision = nativeSessionTitleRevision;
+    const resumeGeneration = nativeSessionTitleCurrentGenerationResume;
+    let syncLatestTitle = false;
+    nativeSessionTitleSyncInFlight = threadId;
+    try {
+        const fallbackApplied = await applyCodexNativeSessionTitle(threadId, fallbackTitle, cfg, engine, resumeGeneration ? 'resume' : 'preview', revision);
+        if (!fallbackApplied || revision !== nativeSessionTitleRevision) {
+            syncLatestTitle = true;
+            return;
+        }
+        nativeSessionTitleAppliedThreadId = threadId;
+        log(`Applied native Codex session title: ${fallbackTitle}`);
+        const sourceText = cfg.nativeSessionTitlePrompt?.trim() ?? '';
+        cfg.nativeSessionTitlePrompt = undefined;
+        if (!sourceText)
+            return;
+        const adapter = createCliAdapterSync('codex', cfg.cliPathOverride);
+        const abortController = new AbortController();
+        nativeSessionTitleSyncAbortControllers.add(abortController);
+        let semanticCore;
+        try {
+            semanticCore = await generateCodexAppThreadTitle({
+                sourceText,
+                codexBin: adapter.resolvedBin,
+                env: codexNativeTitleEnv(cfg),
+                model: cfg.model,
+                timeoutMs: 30_000,
+                signal: abortController.signal,
+                detached: true,
+                registerForceClose: registerNativeTitleForceClose,
+            });
+        }
+        finally {
+            nativeSessionTitleSyncAbortControllers.delete(abortController);
+        }
+        if (revision !== nativeSessionTitleRevision) {
+            syncLatestTitle = true;
+            return;
+        }
+        if (!semanticCore) {
+            log('Native Codex semantic title generation unavailable; keeping fallback title');
+            return;
+        }
+        const semanticTitle = buildBotmuxLarkNativeSessionTitle(semanticCore);
+        if (semanticTitle === fallbackTitle)
+            return;
+        const semanticApplied = await applyCodexNativeSessionTitle(threadId, semanticTitle, cfg, engine, 'none', revision);
+        if (!semanticApplied || revision !== nativeSessionTitleRevision) {
+            syncLatestTitle = true;
+            return;
+        }
+        cfg.nativeSessionTitle = semanticTitle;
+        nativeSessionTitleAppliedThreadId = threadId;
+        send({ type: 'native_session_title_generated', title: semanticTitle });
+        log(`Applied generated native Codex session title: ${semanticTitle}`);
+    }
+    catch (err) {
+        if (revision !== nativeSessionTitleRevision)
+            syncLatestTitle = true;
+        else
+            log(`Native Codex session title sync failed: ${err?.message ?? err}`);
+    }
+    finally {
+        if (nativeSessionTitleSyncInFlight === threadId)
+            nativeSessionTitleSyncInFlight = undefined;
+        if (syncLatestTitle) {
+            void syncFreshCodexNativeSessionTitle(threadId, engine);
+        }
+    }
+}
+/** 在 resume 首条输入前记录 updatedAt，后续用其确认历史派生标题已完成回写。 */
+async function captureCodexResumeTitleBaseline(threadId, engine) {
+    const cfg = lastInitConfig;
+    if (!cfg || cfg.cliId !== 'codex' || cfg.adoptMode || !cfg.nativeSessionTitle)
+        return;
+    nativeSessionTitleResumeUpdatedAt = Math.floor(Date.now() / 1000);
+    try {
+        if (engine?.activeThreadId === threadId) {
+            const metadata = await engine.readThreadMetadata(7000);
+            if (metadata.updatedAt !== undefined)
+                nativeSessionTitleResumeUpdatedAt = metadata.updatedAt;
+            return;
+        }
+        const adapter = createCliAdapterSync('codex', cfg.cliPathOverride);
+        const env = {
+            ...redactChildEnv(process.env),
+            ...sanitizePerBotEnv(cfg.env),
+        };
+        env.PATH = `${join(homedir(), '.botmux', 'bin')}${delimiter}${env.PATH ?? ''}`;
+        const abortController = new AbortController();
+        nativeSessionTitleSyncAbortControllers.add(abortController);
+        try {
+            const metadata = await readCodexAppThreadMetadata({
+                threadId,
+                codexBin: adapter.resolvedBin,
+                cwd: cfg.workingDir,
+                env,
+                timeoutMs: 7000,
+                signal: abortController.signal,
+                detached: true,
+                registerForceClose: registerNativeTitleForceClose,
+            });
+            if (metadata.updatedAt !== undefined)
+                nativeSessionTitleResumeUpdatedAt = metadata.updatedAt;
+        }
+        finally {
+            nativeSessionTitleSyncAbortControllers.delete(abortController);
+        }
+    }
+    catch (err) {
+        log(`Could not capture Codex resume title baseline: ${err?.message ?? err}`);
+    }
+}
+/** 每次 CLI spawn 后重建当前 generation 的标题同步状态。 */
+async function prepareCodexNativeTitleGeneration(cfg, engine) {
+    if (cfg.cliId !== 'codex' || cfg.adoptMode || !cfg.nativeSessionTitle)
+        return;
+    nativeSessionTitleAppliedThreadId = undefined;
+    nativeSessionTitleResumeUpdatedAt = undefined;
+    nativeSessionTitleCurrentGenerationResume = lastSpawnEffectiveResume;
+    if (!lastSpawnEffectiveResume)
+        return;
+    const threadId = engine?.activeThreadId ?? lastSpawnEffectiveCliSessionId ?? cfg.cliSessionId;
+    if (threadId)
+        await captureCodexResumeTitleBaseline(threadId, engine);
+}
+/** Bridge TRAE app-server's native request_user_input request to botmux's
+ * existing Lark ask broker. The app-server owns tool execution in RPC mode, so
+ * returning this response resumes the same turn without terminal key driving. */
+async function bridgeTraexUserInput(cfg, params) {
+    const parsed = parseTraexUserInputQuestions(params);
+    if (parsed.kind === 'unsupported') {
+        // Returning empty answers makes TraeX silently complete the tool as if no
+        // one answered, dropping the whole batch. Throw instead so the RPC engine
+        // replies with a JSON-RPC error and the failure is visible on the turn.
+        throw new Error(`requestUserInput cannot be represented as an ask card: ${parsed.reason}`);
+    }
+    const { questions } = parsed;
+    const daemon = findOnlineDaemon(cfg.larkAppId);
+    if (!daemon)
+        throw new Error(`daemon not found for larkAppId=${cfg.larkAppId}`);
+    const response = await fetchDaemonIpc(daemon.ipcPort, '/api/asks', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            sessionId: cfg.sessionId,
+            chatId: cfg.chatId,
+            larkAppId: cfg.larkAppId,
+            rootMessageId: cfg.rootMessageId || null,
+            questions: questions.map(entry => entry.question),
+            timeoutMs: 3_600_000,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`ask broker HTTP ${response.status}: ${(await response.text()).slice(0, 200)}`);
+    }
+    const result = await response.json();
+    // Timeout/cancel/invalidated — surface as an error rather than an empty answer
+    // that TraeX would treat as "no one answered" and silently skip.
+    if (result.kind !== 'answered') {
+        throw new Error(`ask not answered (${result.kind ?? 'unknown'})`);
+    }
+    const customText = result.comment?.trim() ?? '';
+    const answers = {};
+    questions.forEach((entry, index) => {
+        const selected = result.answers?.[index] ?? [];
+        const values = selected.length > 0 ? [...selected] : customText ? [customText] : [];
+        if (values.length > 0)
+            answers[entry.id] = { answers: values };
+    });
+    return { answers };
+}
 /** Stand up (or re-establish) the per-session codex app-server + botmux-owned
  *  thread and point remote{WsUrl,ThreadId} at it, so the next spawnCli launches
  *  `codex --remote <ws> resume <thread>` and input flows over JSON-RPC. Fully
@@ -276,7 +515,21 @@ async function engageCodexRpc(cfg) {
         const engineEnv = { ...redactChildEnv(process.env) };
         engineEnv.PATH = `${join(homedir(), '.botmux', 'bin')}:${engineEnv.PATH ?? ''}`;
         engineEnv.BOTMUX_SESSION_ID = cfg.sessionId;
+        // In Codex/TraeX RPC mode the app-server, not the remote viewer TUI, runs
+        // model shell tools. Give that process the same non-secret route binding as
+        // spawnCli so `botmux ask` can post into the current Lark thread.
+        engineEnv.BOTMUX_CHAT_ID = cfg.chatId;
+        if (cfg.chatType)
+            engineEnv.BOTMUX_CHAT_TYPE = cfg.chatType;
+        else
+            delete engineEnv.BOTMUX_CHAT_TYPE;
         engineEnv.BOTMUX_LARK_APP_ID = cfg.larkAppId;
+        engineEnv.BOTMUX_ROOT_MESSAGE_ID = cfg.rootMessageId;
+        engineEnv.BOTMUX_SESSION_SCOPE = cfg.rootMessageId?.startsWith('om_') ? 'thread' : 'chat';
+        if (cfg.ownerOpenId)
+            engineEnv.BOTMUX_OWNER_OPEN_ID = cfg.ownerOpenId;
+        else
+            delete engineEnv.BOTMUX_OWNER_OPEN_ID;
         // The app-server owns model execution in RPC mode. Its MCP gateway child
         // must inherit the trusted host socket just like a native CLI process does.
         if (sessionMcpGatewayHost) {
@@ -295,6 +548,10 @@ async function engageCodexRpc(cfg) {
         engine = new CodexRpcEngine({
             cliBin, cwd: cfg.workingDir, env: engineEnv, sessionId: cfg.sessionId,
             model: cfg.model, log: (m) => log(m),
+            appServerFeatures: cfg.cliId === 'traex' ? ['default_mode_request_user_input'] : undefined,
+            onRequestUserInput: cfg.cliId === 'traex'
+                ? (params) => bridgeTraexUserInput(cfg, params)
+                : undefined,
             onDead: () => {
                 if (codexRpcEngine === engine) {
                     log('Codex RPC app-server died; replacing the tmux session and re-engaging the thread');
@@ -348,10 +605,13 @@ async function engageCodexRpc(cfg) {
                 codexBridgeMarkPendingTurn(cfg.prompt, cfg.turnId);
             outcome = first; // 'accepted' | 'ambiguous' — both stay engaged, prompt never re-queued
         }
-        persistCliSessionId(threadId);
         codexRpcEngine = engine;
         remoteWsUrl = engine.wsUrl;
         remoteThreadId = threadId;
+        persistCliSessionId(threadId);
+        if (!wantResume && cfg.prompt && outcome === 'accepted') {
+            void syncFreshCodexNativeSessionTitle(threadId, engine);
+        }
         log(`Codex RPC input engaged (${outcome}${wantResume ? '/resume' : '/fresh'}): app-server ${engine.wsUrl} thread ${threadId}`);
         return outcome;
     }
@@ -739,7 +999,12 @@ const authedClients = new WeakSet();
 const clientPtys = new Map();
 /** Managed-Herdr viewers survive an in-worker /restart while backend changes. */
 const herdrWebBindings = new Map();
-const writeToken = randomBytes(16).toString('hex');
+// Standalone/test fallback. Production replaces this after init with a stable
+// per-session HMAC derived from the host-only dashboard secret, so an
+// already-issued 「操作链接」/write link survives a worker restart (a silent
+// daemon restart re-forks every worker — a per-process random token would 403
+// every previously-issued operate link).
+let writeToken = randomBytes(16).toString('hex');
 // Standalone/test fallback. Production replaces this after init with a stable
 // per-session HMAC derived from the host-only dashboard secret.
 let viewToken = randomBytes(32).toString('base64url');
@@ -754,6 +1019,15 @@ function refreshTerminalViewToken() {
     if (secret && sessionId)
         viewToken = deriveTerminalViewToken(secret, sessionId);
 }
+/** Re-derive the stable write (operate) token from the host-only dashboard
+ *  secret so a restarted worker mints the SAME token — keeping already-issued
+ *  「操作链接」/write links valid across restarts. Falls back to the random
+ *  boot token when the secret is unavailable (standalone/test). */
+function refreshTerminalWriteToken() {
+    const secret = loadDashboardSecret(DASHBOARD_SECRET_PATH);
+    if (secret && sessionId)
+        writeToken = deriveTerminalWriteToken(secret, sessionId);
+}
 /**
  * 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
@@ -790,6 +1064,10 @@ function ensureZellijAttachConfig() {
 }
 let sessionId = '';
 let lastInitConfig = null;
+/** Dashboard「复现命令」：session 冷启时最终交给 backend.spawn 的真实调用
+ *  （bin + argv + cwd + 关键 env）。原样保留，worker `ready` 时随消息上报给 daemon
+ *  持久化。仅有写权限的 dashboard 视图可见。 */
+let capturedSpawnCommand = null;
 let deferredTopicOutputTail = '';
 const reportedDeferredTopicRoots = new Set();
 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', 'kiro-cli': 'Kiro', riff: 'Riff' };
@@ -1073,6 +1351,21 @@ const pendingRawInputs = [];
  * administrative TUI command: never type-ahead while the agent is busy, never
  * open a model turn, and latest-wins if several renames arrive before idle. */
 let pendingSessionRename = null;
+let nativeSessionTitleSyncInFlight;
+let nativeSessionTitleAppliedThreadId;
+let nativeSessionTitleRevision = 0;
+let nativeSessionTitleResumeUpdatedAt;
+let nativeSessionTitleCurrentGenerationResume = false;
+const nativeSessionTitleSyncAbortControllers = new Set();
+const nativeSessionTitleSyncForceClosers = new Set();
+function stopNativeSessionTitleSync() {
+    for (const abortController of nativeSessionTitleSyncAbortControllers)
+        abortController.abort();
+    nativeSessionTitleSyncAbortControllers.clear();
+    for (const forceClose of nativeSessionTitleSyncForceClosers)
+        forceClose();
+    nativeSessionTitleSyncForceClosers.clear();
+}
 /** True after the rename command's Enter lands and until the TUI returns to its
  * prompt. Blocks type-ahead user messages from racing into the command UI. */
 let sessionRenameInFlight = false;
@@ -3734,6 +4027,7 @@ function parkCrashDiagnosticTerminal(code, signal) {
     // both when the next message respawns the CLI.
     stopScreenUpdates();
     stopScreenAnalyzer();
+    stopStuckDetector();
     log(`Crash diagnostic tmux session parked at ${TmuxBackend.diagnosticSessionName(sessionId)}`);
     return true;
 }
@@ -3849,6 +4143,68 @@ function stopScreenAnalyzer() {
     screenAnalyzer = null;
     tuiPromptBlocking = false;
 }
+// ─── Stuck Detector (AI-free fallback for blocked CLI states) ───────────────
+let stuckDetector = null;
+// Monotonic counter bumped on every CLI/backend (re)start within this worker.
+// Paired with the backend object identity, it lets the worker verify that a
+// stuck-warning card click still targets the same CLI instance that was stuck —
+// a restart within the same Node worker must invalidate outstanding cards.
+let cliLifetimeNonce = 0;
+function startStuckDetector() {
+    const sd = config.stuckDetector;
+    if (!sd.enabled)
+        return;
+    stopStuckDetector();
+    stuckDetector = new StuckDetector(sd.timeoutMs, {
+        isActuallyStuck: () => {
+            // Scope gate: this PR only handles the Codex PreToolUse hook-review
+            // screen. Other CLIs (Claude Code, Gemini, ...) must never see the
+            // Codex-specific t/Enter/Esc card, even if their output happens to
+            // contain the same strings.
+            if (lastInitConfig?.cliId !== 'codex')
+                return false;
+            // Only warn if the CLI is not at its idle prompt AND no TUI prompt card
+            // is already posted. A long legitimate turn (model thinking, tool calls)
+            // must not trigger this.
+            if (isPromptReady)
+                return false;
+            if (tuiPromptBlocking)
+                return false;
+            // Anti-false-positive: if the PTY produced output recently the CLI is
+            // still actively working (model streaming, tool output, spinner) — not
+            // stuck. Require quiescence before firing.
+            const sincePty = Date.now() - lastPtyActivityAtMs;
+            if (sincePty < 15_000)
+                return false;
+            // Do NOT gate on durableTurnInFlight: the original hook-review incident
+            // ran on a non-durable (ordinary IM) turn, and a durable turn's 20s
+            // submit-recheck failure clears durableTurnInFlight before the 45s
+            // detector fires. The PTY-quiescence + !isPromptReady combination is
+            // sufficient to detect a genuinely stalled turn.
+            return true;
+        },
+        onStuck: (elapsedMs, matchedLabel) => {
+            // Prefer lastAnalyzerSnapshot (the capture-pane authoritative current
+            // screen) over the long-lived renderer, which can drift under tmux.
+            const snapshot = lastAnalyzerSnapshot || renderer?.rawSnapshot() || '';
+            log(`StuckDetector: turn unresolved for ${Math.round(elapsedMs / 1000)}s${matchedLabel ? ` (${matchedLabel})` : ''}`);
+            send({
+                type: 'stuck_warning',
+                elapsedMs,
+                snapshot: snapshot.slice(-3000),
+                matchedPattern: matchedLabel,
+                turnId: currentBotmuxTurnId,
+                dispatchAttempt: currentBotmuxDispatchAttempt,
+                cliLifetime: cliLifetimeNonce,
+            });
+        },
+        getSnapshot: () => lastAnalyzerSnapshot || renderer?.rawSnapshot() || '',
+    });
+}
+function stopStuckDetector() {
+    stuckDetector?.dispose();
+    stuckDetector = null;
+}
 // ─── Screenshot Capture (PNG → Feishu image_key) ────────────────────────────
 const SCREENSHOT_INTERVAL_MS = 10_000;
 const POST_ACTION_DELAY_MS = 1_000;
@@ -4096,24 +4452,32 @@ const KEY_TO_ANSI = {
  * Execute an AI-provided key sequence with delays between each key.
  * @param keys — key names like ["Down","Down","Space","Up","Up"]
  * @param isFinal — if true, this action ends the prompt (clear blocking state)
+ * @returns true if all keys were written successfully; false if backend is gone
+ *          or a write threw (caller must NOT send tui_keys_delivered on false).
  */
 async function handleTuiKeys(keys, isFinal) {
     if (!backend || keys.length === 0)
-        return;
-    if ('sendSpecialKeys' in backend) {
-        const b = backend;
-        // Send each key individually with 100ms delay for TUI state processing
-        for (const key of keys) {
-            b.sendSpecialKeys(key);
-            await new Promise(r => setTimeout(r, 100));
+        return false;
+    try {
+        if ('sendSpecialKeys' in backend) {
+            const b = backend;
+            // Send each key individually with 100ms delay for TUI state processing
+            for (const key of keys) {
+                b.sendSpecialKeys(key);
+                await new Promise(r => setTimeout(r, 100));
+            }
         }
-    }
-    else {
-        for (const key of keys) {
-            backend.write(KEY_TO_ANSI[key] ?? key);
-            await new Promise(r => setTimeout(r, 100));
+        else {
+            for (const key of keys) {
+                backend.write(KEY_TO_ANSI[key] ?? key);
+                await new Promise(r => setTimeout(r, 100));
+            }
         }
     }
+    catch (e) {
+        logError(`handleTuiKeys write failed: ${e?.message ?? e}`);
+        return false;
+    }
     if (isFinal) {
         tuiPromptBlocking = false;
         if (isPromptReady) {
@@ -4123,6 +4487,7 @@ async function handleTuiKeys(keys, isFinal) {
         screenAnalyzer?.notifySelection('final');
     }
     log(`TUI keys: ${keys.join(' ')}${isFinal ? ' (final)' : ''}`);
+    return true;
 }
 // 待注入的 TUI 命令队列。生命周期绑定当前 CLI 进程：killCli() 会清空它，
 // 防止 restart 后残留命令重放进新 CLI——新增清理状态时记得同步那里。
@@ -4630,6 +4995,7 @@ function markPromptReady() {
     // worker-local replay of the durable attempt.
     if (!durableTurnInFlight)
         inflightInputs.onTurnComplete();
+    stuckDetector?.disarm();
     maybeEmitWorkflowTranscriptOutput();
     if (awaitingFirstPrompt) {
         awaitingFirstPrompt = false;
@@ -4814,6 +5180,7 @@ function scheduleSubmitFailureNotify(msg, recheck, transcriptLabel, bridgeTurnId
                     persistCliSessionId(cliSessionId);
                     if (codexBridgeFallbackActive())
                         codexBridgeNotifyCliSessionId(cliSessionId);
+                    void syncFreshCodexNativeSessionTitle(cliSessionId, codexRpcEngine);
                 }
                 log(`Deferred recheck found submit in ${transcriptLabel} — suppressing warning. preview="${preview}"`);
                 return;
@@ -5098,8 +5465,10 @@ async function flushPending() {
             // auto-re-queued: a lost/late ack surfaces as a submit-failure the user can
             // resend manually, and the stable clientUserMessageId lets codex dedupe a
             // resend (Codex delta P1-1).
-            if (!codexRpcEngine)
+            if (!codexRpcEngine) {
                 inflightInputs.onWrite(item);
+                stuckDetector?.arm();
+            }
             const msg = item.content;
             const logicalMsg = item.logicalContent ?? msg;
             currentBotmuxTurnId = item.turnId;
@@ -5197,6 +5566,13 @@ async function flushPending() {
                 if (codexBridgeActive)
                     codexBridgeNotifyCliSessionId(result.cliSessionId);
             }
+            if (lastInitConfig?.cliId === 'codex' && result?.submitted !== false) {
+                const threadId = result?.cliSessionId
+                    ?? codexRpcEngine?.activeThreadId
+                    ?? lastInitConfig.cliSessionId;
+                if (threadId)
+                    void syncFreshCodexNativeSessionTitle(threadId, codexRpcEngine);
+            }
             // `&& backend`: if the CLI exited during this write (pane gone → onExit
             // nulled backend) the user already got a "CLI exited" notice; don't also
             // nag that the submit wasn't confirmed.
@@ -5222,7 +5598,7 @@ async function flushPending() {
 }
 function sendToPty(content, turnId, opts = {}) {
     if (!cliAdapter)
-        return;
+        return false;
     const next = {
         content,
         turnId,
@@ -5239,7 +5615,7 @@ function sendToPty(content, turnId, opts = {}) {
     if (cliRestartInProgress || !backend) {
         pendingMessages.push(next);
         log(`Queued message while CLI backend is restarting (${pendingMessages.length} pending)`);
-        return;
+        return true;
     }
     const supportsTypeAhead = pendingInputAllowsTypeAhead(cliAdapter.supportsTypeAhead === true, durableTurnInFlight, next);
     const shouldMergeQueued = opts.dispatchAttempt === undefined && !durableTurnInFlight
@@ -5296,6 +5672,7 @@ function sendToPty(content, turnId, opts = {}) {
             log(`Queued message (${pendingMessages.length} pending): "${content.substring(0, 80)}" — ${cliName()} ${awaitingFirstPrompt ? 'still booting' : 'is busy'}`);
         scheduleBusyPatternIdleProbe(`${cliName()} queued-message`);
     }
+    return true;
 }
 // ─── Screen Update Timer ─────────────────────────────────────────────────────
 function startScreenUpdates() {
@@ -5733,6 +6110,7 @@ async function spawnCli(cfg, opts = {}) {
         });
         effectiveBackendType = 'herdr';
         backend = herdrBe;
+        cliLifetimeNonce++;
         // 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
@@ -5791,6 +6169,7 @@ async function spawnCli(cfg, opts = {}) {
             : new TmuxPipeBackend(cfg.adoptTmuxTarget, { cliPid: cfg.adoptCliPid });
         effectiveBackendType = cfg.adoptZellijPaneId ? 'zellij' : 'tmux';
         backend = observeBe;
+        cliLifetimeNonce++;
         // 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.
@@ -5970,11 +6349,6 @@ async function spawnCli(cfg, opts = {}) {
             }
         }
     }
-    const selectedBackend = selectSessionBackend({ sessionId: cfg.sessionId, backendType: effectiveBackend, backendConfig: riffBackendConfig });
-    isTmuxMode = selectedBackend.isTmuxMode;
-    isPipeMode = selectedBackend.isPipeMode;
-    isZellijMode = selectedBackend.isZellijMode;
-    backend = selectedBackend.backend;
     const adapterSessionId = cfg.resume
         ? (cfg.originalSessionId ?? cfg.sessionId)
         : cfg.sessionId;
@@ -6110,6 +6484,31 @@ async function spawnCli(cfg, opts = {}) {
     currentCliCredentialIsolated = appliedIsolationCapabilities.includes('credential');
     const isolationRuntimeDataDir = process.env.SESSION_DATA_DIR
         ?? join(defaultBotmuxHome, 'data');
+    let mcpRuntimeManifest = readSessionMcpRuntimeManifest(cfg.sessionId, config.session.dataDir);
+    const hasMcpRuntimeEntries = !!cliAdapter.mcpGateway && !!mcpRuntimeManifest?.entries.length;
+    const selectBackend = () => selectSessionBackend({
+        sessionId: cfg.sessionId,
+        backendType: effectiveBackend,
+        backendConfig: riffBackendConfig,
+        persistentBackendTarget: cfg.persistentBackendTarget,
+        // Old builds could place managed agents in a user's shared Herdr session.
+        // Preserve that recorded target for compatibility unless this incarnation
+        // requires an isolation/MCP boundary that only a Botmux-owned session can
+        // safely provide. Fresh tasks use distinct agents in one machine-wide host.
+        reuseRecordedHerdrTarget: !willReadIsolate
+            && !willWriteSandbox
+            && !hasMcpRuntimeEntries,
+    });
+    let selectedBackend = selectBackend();
+    isTmuxMode = selectedBackend.isTmuxMode;
+    isPipeMode = selectedBackend.isPipeMode;
+    isZellijMode = selectedBackend.isZellijMode;
+    backend = selectedBackend.backend;
+    // Bump the CLI-lifetime nonce: any stuck-warning card posted by a previous
+    // backend instance (within this same worker) must not inject keys into the
+    // new one. The worker echoes this nonce in stuck_warning and re-checks it on
+    // tui_keys, alongside the backend object identity.
+    cliLifetimeNonce++;
     // Every bot — isolated OR not — gets its own BOT_HOME dir as a ready-made private-
     // storage slot. An isolated sibling denies this path regardless of whether the owner
     // is isolated (deny uses the full bots.json), so a non-isolated bot can drop private
@@ -6175,13 +6574,7 @@ async function spawnCli(cfg, opts = {}) {
     // on EVERY restart, e.g. for a sandboxed session whose transcript lives in
     // an ephemeral overlay upper that the probe can't see). Computed here (not at
     // the spawn site below) so the pre-flight can short-circuit on it.
-    const persistentSessionName = effectiveBackendType === 'tmux'
-        ? TmuxBackend.sessionName(cfg.sessionId)
-        : effectiveBackendType === 'herdr'
-            ? HerdrBackend.sessionName(cfg.sessionId)
-            : effectiveBackendType === 'zellij'
-                ? ZellijBackend.sessionName(cfg.sessionId)
-                : undefined;
+    let persistentSessionName = selectedBackend.persistentSessionName;
     // [read-isolation] Before we decide to reattach a persistent pane: a pane can
     // survive a daemon restart still running a CLI that may NOT be isolated (e.g.
     // spawned before isolation was enabled, or by an old build). Isolation is only
@@ -6192,11 +6585,10 @@ async function spawnCli(cfg, opts = {}) {
     // policy pane survives daemon restarts and suspend→resume safely because the
     // confinement remains attached to the live process.
     if (appliedIsolationCapabilities.length > 0 && persistentSessionName && effectiveBackendType !== 'pty') {
-        const paneLive = effectiveBackendType === 'tmux'
-            ? TmuxBackend.hasSession(persistentSessionName)
-            : effectiveBackendType === 'zellij'
-                ? ZellijBackend.hasSession(persistentSessionName)
-                : HerdrBackend.hasSession(persistentSessionName);
+        const persistentTarget = selectedBackend.persistentBackendTarget;
+        const paneLive = persistentTarget
+            ? probePersistentBackendTarget(persistentTarget) === 'exists'
+            : false;
         if (paneLive) {
             let marker = null;
             marker = readRegularHostFileNoFollow(join(isolationRuntimeDataDir, 'read-isolation', `${cfg.sessionId}.boot`));
@@ -6211,7 +6603,18 @@ async function spawnCli(cfg, opts = {}) {
                 // obsolete permissions. Kill it before publishing any new capability.
                 log(`[read-isolation] legacy/unmarked persistent pane for ${cfg.sessionId} — killing + cold-spawning with current policy`);
                 try {
-                    killPersistentSession(effectiveBackendType, persistentSessionName);
+                    const persistentTarget = selectedBackend.persistentBackendTarget;
+                    if (persistentTarget)
+                        killPersistentBackendTarget(persistentTarget);
+                    else
+                        killPersistentSession(effectiveBackendType, persistentSessionName);
+                    selectedBackend = selectBackend();
+                    isTmuxMode = selectedBackend.isTmuxMode;
+                    isPipeMode = selectedBackend.isPipeMode;
+                    isZellijMode = selectedBackend.isZellijMode;
+                    backend = selectedBackend.backend;
+                    cliLifetimeNonce++;
+                    persistentSessionName = selectedBackend.persistentSessionName;
                 }
                 catch (e) {
                     throw new Error(`[read-isolation] refusing to start session ${cfg.sessionId}: could not kill stale persistent pane (${e.message})`);
@@ -6219,28 +6622,32 @@ async function spawnCli(cfg, opts = {}) {
             }
         }
     }
-    let mcpRuntimeManifest = readSessionMcpRuntimeManifest(cfg.sessionId, config.session.dataDir);
+    let willReattachPersistent = selectedBackend.isReattach === true;
     if (cliAdapter.mcpGateway && mcpRuntimeManifest?.entries.length && persistentSessionName && effectiveBackendType !== 'pty') {
-        const paneLive = effectiveBackendType === 'tmux'
-            ? TmuxBackend.hasSession(persistentSessionName)
-            : effectiveBackendType === 'zellij'
-                ? ZellijBackend.hasSession(persistentSessionName)
-                : HerdrBackend.hasSession(persistentSessionName);
+        const persistentTarget = selectedBackend.persistentBackendTarget;
+        const paneLive = persistentTarget
+            ? probePersistentBackendTarget(persistentTarget) === 'exists'
+            : false;
         if (paneLive) {
             // The trusted Gateway host belongs to the worker and cannot survive a
             // worker/daemon replacement. Cold-resume the CLI so its MCP client gets a
             // fresh relay socket instead of reattaching to a dead connection.
             log(`[mcp-gateway] persistent pane ${cfg.sessionId} has plugin MCP state — cold-resuming with a fresh host`);
-            killPersistentSession(effectiveBackendType, persistentSessionName);
+            const persistentTarget = selectedBackend.persistentBackendTarget;
+            if (persistentTarget)
+                killPersistentBackendTarget(persistentTarget);
+            else
+                killPersistentSession(effectiveBackendType, persistentSessionName);
+            selectedBackend = selectBackend();
+            isTmuxMode = selectedBackend.isTmuxMode;
+            isPipeMode = selectedBackend.isPipeMode;
+            isZellijMode = selectedBackend.isZellijMode;
+            backend = selectedBackend.backend;
+            cliLifetimeNonce++;
+            persistentSessionName = selectedBackend.persistentSessionName;
+            willReattachPersistent = selectedBackend.isReattach === true;
         }
     }
-    const willReattachPersistent = persistentSessionName
-        ? effectiveBackendType === 'tmux'
-            ? TmuxBackend.hasSession(persistentSessionName)
-            : effectiveBackendType === 'zellij'
-                ? ZellijBackend.hasSession(persistentSessionName)
-                : HerdrBackend.hasSession(persistentSessionName)
-        : false;
     // The plugin set is stable only for the lifetime of one real CLI process.
     // A warm worker reattach keeps the existing Gateway and catalog untouched;
     // every fresh/resumed CLI spawn atomically refreshes both from current Bot config.
@@ -6694,6 +7101,13 @@ async function spawnCli(cfg, opts = {}) {
     let spawnBin = cliAdapter.resolvedBin;
     let spawnArgs = args;
     let spawnCwd = cfg.workingDir;
+    // Dashboard「复现命令」：在**任何** sandbox 包装（下方 macOS Seatbelt / Linux bwrap /
+    // credential-only）之前，记下**基础 CLI** 的 bin/args（cliAdapter.resolvedBin +
+    // buildArgs 产出）。独立维护、绝不从已被外层包装的 spawnBin/spawnArgs 回推。最终
+    // 复现形态（是否套 wrapperCli）由 selectReproduceLaunch 在 spawn 时统一决策——见
+    // reproduce-command.ts。这里只锁定"包装前的基础"这个事实。
+    const reproduceBaseBin = spawnBin;
+    const reproduceBaseArgs = [...spawnArgs];
     // Read isolation (macOS): wrap the whole CLI process in a Seatbelt sandbox that
     // denies reads of the sensitive paths (blocklist). The CLI bypasses its OWN
     // sandbox (see adapter) so the outer wrapper is the sole enforcer. DARWIN ONLY —
@@ -7087,6 +7501,19 @@ async function spawnCli(cfg, opts = {}) {
             }
         }
     }
+    // Publish the exact selected resource BEFORE spawn. This both restores host
+    // affinity for later in-worker restarts and closes the crash window where a
+    // shared Herdr agent could be created but the daemon still knew only bmx-*.
+    // A failed spawn leaving an intent stamp is safe: lifecycle probes see the
+    // missing agent and close/cold-resume instead of leaking an untracked pane.
+    cfg.persistentBackendTarget = selectedBackend.persistentBackendTarget;
+    if (lastInitConfig) {
+        lastInitConfig.persistentBackendTarget = selectedBackend.persistentBackendTarget;
+    }
+    send({
+        type: 'persistent_backend_target',
+        target: selectedBackend.persistentBackendTarget,
+    });
     // Mandatory credential-only confinement is the OUTERMOST launch wrapper so
     // wrapperCli and every descendant it starts inherit the boundary. Full
     // Seatbelt/bwrap sessions were already wrapped above and never enter these
@@ -7224,6 +7651,32 @@ async function spawnCli(cfg, opts = {}) {
         log(`[device-credential-isolation] wrapping ${cliAdapter.id} in credential-only bwrap `
             + `(${hideDirectories.size} authority dir(s), ${hideFiles.size} exact file(s))`);
     }
+    // Dashboard「复现命令」：算出本次冷启的**近似**可复现命令（bin + argv + cwd +
+    // 权威注入 env），随 ready 上报、只驻 daemon 内存（含凭证，绝不落盘）。基础 CLI
+    // bin/args 取 sandbox 包装前的快照，最终形态（含/不含 wrapperCli）由
+    // selectReproduceLaunch 决策——绝不含 sandbox-exec/bwrap 外层。riff 返回 null。
+    try {
+        const reproduceLaunch = selectReproduceLaunch({
+            baseBin: reproduceBaseBin,
+            baseArgs: reproduceBaseArgs,
+            wrapperCli: cfg.wrapperCli,
+            sandboxOn,
+            binResolver: (b) => locateOnPath(b) ?? b,
+            ttadkModel: cfg.model,
+        });
+        capturedSpawnCommand = buildReproduceCommand({
+            backendType: effectiveBackendType,
+            bin: reproduceLaunch.bin,
+            args: reproduceLaunch.args,
+            cwd: spawnCwd,
+            env: childEnv,
+            injectEnv: perBotInjectKeys.length ? perBotInjectEnv : undefined,
+        });
+    }
+    catch (err) {
+        capturedSpawnCommand = null;
+        log(`Failed to capture reproduce command: ${err?.message ?? err}`);
+    }
     backend.spawn(spawnBin, spawnArgs, {
         cwd: spawnCwd,
         cols: PTY_COLS,
@@ -7232,6 +7685,13 @@ async function spawnCli(cfg, opts = {}) {
         injectEnv: perBotInjectKeys.length ? perBotInjectEnv : undefined,
         launchShell: lastInitConfig?.launchShell,
     });
+    if (selectedBackend.createdHerdrSessionName) {
+        send({
+            type: 'user_notify',
+            turnId: currentBotmuxTurnId,
+            message: `已创建 Botmux 专属 Herdr 会话：\`${selectedBackend.createdHerdrSessionName}\``,
+        });
+    }
     // Write CLI PID marker so agent-facing subcommands (`botmux send`, etc.)
     // can verify they were spawned inside a botmux session by walking the
     // process tree and looking for a matching pid file in this directory.
@@ -7519,44 +7979,59 @@ async function spawnCli(cfg, opts = {}) {
         }, READY_SIGNAL_TIMEOUT_MS);
         readySignalTimer.unref?.();
     }
+    // A settled signal is a turn boundary. Drain structured transcripts before
+    // markPromptReady(): that call may synchronously flush a type-ahead turn and
+    // advance bridge attribution. Both screen-idle and authoritative Herdr status
+    // must preserve this ordering.
+    const drainBridgesThenMarkReady = (evidenceSource) => {
+        if (bridgeJsonlPath) {
+            try {
+                bridgeDrainAndMaybeEmit();
+            }
+            catch (err) {
+                log(`Bridge emit error: ${err.message}`);
+            }
+        }
+        if (codexBridgeFallbackActive()) {
+            try {
+                codexBridgeDrainAndMaybeEmit();
+            }
+            catch (err) {
+                log(`Codex bridge emit error: ${err.message}`);
+            }
+        }
+        if (evidenceSource === 'screen')
+            markPromptReadyFromPty();
+        else
+            markPromptReady();
+    };
     // Set up idle detection. Riff (remote HTTP backend) has no PTY output and
     // is marked ready immediately after spawn (see below), so the idle detector
     // is unnecessary — and without a readyPattern it would fire on every
     // quiescence, repeatedly triggering markPromptReady() and duplicate cards.
     if (effectiveBackendType !== 'riff') {
         idleDetector = new IdleDetector(cliAdapter);
-        idleDetector.onIdle(async (evidenceSource) => {
+        idleDetector.onIdle((evidenceSource) => {
             log('Prompt detected (idle)');
-            // Bridge drain MUST run before markPromptReady() — the latter calls
-            // flushPending() which can immediately fire the next queued message
-            // (type-ahead adapters), shifting bridgeQueue's notion of "current
-            // turn" before we've had a chance to emit the previous one.
-            if (bridgeJsonlPath) {
-                try {
-                    bridgeDrainAndMaybeEmit();
-                }
-                catch (err) {
-                    log(`Bridge emit error: ${err.message}`);
-                }
-            }
-            if (codexBridgeFallbackActive()) {
-                try {
-                    codexBridgeDrainAndMaybeEmit();
-                }
-                catch (err) {
-                    log(`Codex bridge emit error: ${err.message}`);
-                }
-            }
-            if (evidenceSource === 'screen') {
-                markPromptReadyFromPty();
-            }
-            else {
-                markPromptReady();
-            }
+            drainBridgesThenMarkReady(evidenceSource);
         });
     }
     backend.onData(onPtyData);
     const observedBackend = backend;
+    if (observedBackend instanceof HerdrBackend) {
+        observedBackend.onAgentStatus((status) => {
+            if (backend !== observedBackend)
+                return;
+            if (status === 'idle' || status === 'done') {
+                log(`Herdr agent ${status} — draining bridges before marking prompt ready`);
+                drainBridgesThenMarkReady('structured');
+            }
+            else if (status === 'working') {
+                isPromptReady = false;
+                idleDetector?.reset();
+            }
+        });
+    }
     backend.onAccessUrl?.((url) => {
         send({
             type: 'riff_access_url',
@@ -7744,6 +8219,7 @@ async function spawnCli(cfg, opts = {}) {
 }
 function killCli(opts = {}) {
     currentCliCredentialIsolated = false;
+    stopNativeSessionTitleSync();
     stopSessionMcpGatewayHost();
     stopCodexRpcEngine();
     if (!opts.preservePending)
@@ -7767,6 +8243,7 @@ function killCli(opts = {}) {
     readyPatternSeenDuringHold = false;
     awaitingPostSessionStartPromptEvidence = false;
     stopScreenAnalyzer();
+    stopStuckDetector();
     stopScreenUpdates();
     backend?.kill();
     backend = null;
@@ -7883,6 +8360,7 @@ async function restartCliProcess(reason, opts = {}) {
                 if (lastInitConfig) {
                     startScreenUpdates();
                     startScreenAnalyzer();
+                    startStuckDetector();
                     try {
                         const restartCfg = { ...lastInitConfig, resume: true, prompt: '', cliSessionId: rpcThreadId ?? lastInitConfig.cliSessionId };
                         // Re-engage RPC so the new --remote pane binds to the CURRENT app-server
@@ -7896,6 +8374,7 @@ async function restartCliProcess(reason, opts = {}) {
                             await engageCodexRpc(restartCfg);
                         }
                         await spawnCli(restartCfg, { pluginGenerationPrepared: rpcPluginGenerationPrepared });
+                        await prepareCodexNativeTitleGeneration(restartCfg, codexRpcEngine);
                         if (codexRpcEngine)
                             armRpcStartupDialogDismiss();
                     }
@@ -7960,8 +8439,24 @@ function startWebServer(host, preferredPort) {
             // normal buffer until resize causes a redraw. Preserve that mode so
             // scroll gestures continue to target the CLI's own transcript.
             const forceRemoteScroll = effectiveBackendType === 'herdr' && cliAdapter?.altScreen === true;
+            // The wheel burst cap throttles backends where a forwarded wheel is
+            // EXPENSIVE or has no local terminal to drive:
+            //   • Herdr — each forwarded wheel → pane send-text + snapshot re-render.
+            //   • Riff  — has NO drivable terminal; writes become remote task/follow-up
+            //             creations (handleTermAction even rejects ANSI to Riff), so an
+            //             uncapped spin would flood remote task creation.
+            // This is a BACKEND property, independent of the adapter's declared
+            // altScreen: an altScreen:false CLI (Claude/Codex) that enters the
+            // alternate buffer at runtime (vim/less, or the CLI's own alt-screen) still
+            // forwards via _fwdScroll and must inherit its backend's cap. So gate the
+            // cap on a POSITIVE allowlist of cheap, locally-drivable terminal backends
+            // (pty/tmux/zellij); every other backend — Herdr, Riff, and any future one
+            // — stays safely capped by default.
+            const localTerminalBackend = effectiveBackendType === 'pty'
+                || effectiveBackendType === 'tmux'
+                || effectiveBackendType === 'zellij';
             res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-            res.end(getTerminalHtml(hasWrite, platformReadonly, loginUrl, forceRemoteScroll));
+            res.end(getTerminalHtml(hasWrite, platformReadonly, loginUrl, forceRemoteScroll, localTerminalBackend));
         });
         wss = new WebSocketServer({
             server: httpServer,
@@ -8258,7 +8753,7 @@ function startWebServer(host, preferredPort) {
             .then(resolve, reject);
     });
 }
-function getTerminalHtml(hasWrite, platformReadonly = false, loginUrl = '', forceRemoteScroll = false) {
+function getTerminalHtml(hasWrite, platformReadonly = false, loginUrl = '', forceRemoteScroll = false, localTerminalBackend = false) {
     const label = sessionId.substring(0, 8);
     return `<!DOCTYPE html>
 <html>
@@ -8395,6 +8890,7 @@ if(isTouch){document.body.classList.add('touch');}
 var hasToken=${hasWrite};
 var platformReadonly=${platformReadonly};
 var remoteScroll=${forceRemoteScroll};
+var localTerminalBackend=${localTerminalBackend};
 if(!hasToken){
   if(platformReadonly){var _lb=document.getElementById('login-banner');_lb.classList.add('show');}
   else{var _rb=document.getElementById('readonly-banner');_rb.classList.add('show');_rb.addEventListener('click',function(){_rb.classList.remove('show')});}
@@ -8601,8 +9097,21 @@ window.addEventListener('resize',onViewportResize);
 // A high-resolution trackpad emits dozens of wheel events for one gesture, so
 // cap the whole continuous burst — not each browser event — then require an idle
 // gap (or direction reversal) before loading the next history chunk.
+//
+// The burst ceiling throttles backends where a forwarded wheel is EXPENSIVE or
+// has no local terminal to drive: Herdr (each tick → pane send-text + snapshot
+// re-render) and Riff (no drivable terminal — writes become remote task/follow-up
+// creations, so an uncapped spin would flood remote task creation). That cost is
+// a BACKEND property, not the adapter's declared altScreen — an altScreen:false
+// CLI (Claude/Codex) that enters the alternate buffer at runtime (vim/less, the
+// CLI's own alt-screen) still hits this path and inherits its backend's cap. A
+// local PTY/tmux/zellij backend repaints its own alt-screen cheaply, so capping
+// it at 6 ticks is what froze a continuous wheel spin after ~2 notches — the
+// "not smooth / stuck" symptom. Gate the release on a POSITIVE allowlist of
+// cheap local terminal backends (localTerminalBackend); every other backend —
+// Herdr, Riff, and any future one — stays safely capped by default.
 var _scrollAccum=0,_scrollBurstTicks=0,_scrollBurstDir=0,_scrollBurstT=0;
-var _SCROLL_STEP=33;var _SCROLL_BURST_MAX=6;var _SCROLL_BURST_IDLE_MS=250;
+var _SCROLL_STEP=33;var _SCROLL_BURST_MAX=localTerminalBackend?Infinity:6;var _SCROLL_BURST_IDLE_MS=250;
 function _endScrollBurst(){
   clearTimeout(_scrollBurstT);_scrollBurstT=0;
   _scrollAccum=0;_scrollBurstTicks=0;_scrollBurstDir=0;
@@ -9058,6 +9567,10 @@ function send(msg) {
     }
     process.send?.(payload);
 }
+function acknowledgeTurnInputCommitted(turnId) {
+    if (turnId)
+        send({ type: 'turn_input_committed', turnId });
+}
 function publishLocalProcessAttestation(cliPid) {
     const cliProcStart = cliPid ? readProcessStartIdentity(cliPid) : undefined;
     send({
@@ -9115,11 +9628,13 @@ process.on('message', async (raw) => {
     const msg = raw;
     switch (msg.type) {
         case 'init': {
+            const initStartedAtMs = Date.now();
             if (lastInitConfig)
                 return; // already initialized
             lastInitConfig = msg;
             sessionId = msg.sessionId;
             refreshTerminalViewToken();
+            refreshTerminalWriteToken();
             if (msg.ownerOpenId)
                 process.env.__OWNER_OPEN_ID = msg.ownerOpenId;
             // Pin this worker's i18n locale early so every t() call below resolves
@@ -9163,6 +9678,7 @@ process.on('message', async (raw) => {
                     port = await startWebServer(config.web.workerHost, msg.webPort);
                     startScreenUpdates();
                     startScreenAnalyzer();
+                    startStuckDetector();
                 }
                 else {
                     // Workflow attempts still expose a read-only web terminal so the
@@ -9206,6 +9722,7 @@ process.on('message', async (raw) => {
                     throw new Error('codex RPC resume: could not replace stale --remote pane; aborting init');
                 }
                 await spawnCli(msg, { pluginGenerationPrepared: rpcPluginGenerationPrepared });
+                await prepareCodexNativeTitleGeneration(msg, codexRpcEngine);
                 if (codexRpcEngine)
                     armRpcStartupDialogDismiss(); // boundary #4: keep the --remote pane from freezing on a startup dialog
                 // Queue the initial prompt — flushed when CLI shows idle.
@@ -9237,6 +9754,7 @@ process.on('message', async (raw) => {
                 //    execution — exactly-once, Codex P1-1). Ambiguous never reaches here.
                 //  - RPC RESUME: queuePrompt=true → queue for post-ready flush (bridge
                 //    marked at flush time, P0-1).
+                let initialInputCommitted = false;
                 if (shouldQueueInitialPrompt({
                     hasPrompt: !!msg.prompt,
                     rpcEngineActive: !!codexRpcEngine,
@@ -9254,13 +9772,22 @@ process.on('message', async (raw) => {
                         vcMeetingImTurnOrigin: msg.vcMeetingImTurnOrigin,
                         codexAppInput: msg.promptCodexAppInput,
                     });
+                    initialInputCommitted = true;
+                }
+                else if (msg.prompt) {
+                    // A successful spawn with a non-queued prompt means the adapter baked
+                    // it into argv or the RPC engine already accepted it.
+                    initialInputCommitted = true;
                 }
-                // Riff (remote HTTP backends): spawnCli already marked the prompt ready
-                // (no local boot → isPromptReady=true immediately), but the initial prompt
-                // was queued AFTER spawnCli returned, so flushPending() ran on an empty
-                // queue. Flush now that the prompt is enqueued. isPromptReady is already
-                // true so the flush gates all pass.
-                if (effectiveBackendType === 'riff' && pendingMessages.length > 0) {
+                if (initialInputCommitted)
+                    acknowledgeTurnInputCommitted(msg.turnId);
+                // A backend may become prompt-ready before spawnCli() returns. The
+                // initial prompt is queued only afterwards, so the earlier
+                // markPromptReady() necessarily flushed an empty queue. This is normal
+                // for riff (ready immediately) and can also happen when Herdr reports a
+                // fast-starting TUI as idle during spawn. Flush again after enqueueing;
+                // the ready flag keeps booting/busy backends gated.
+                if (isPromptReady && pendingMessages.length > 0) {
                     flushPending();
                 }
                 send({
@@ -9268,6 +9795,11 @@ process.on('message', async (raw) => {
                     port,
                     token: writeToken,
                     viewToken,
+                    ...(capturedSpawnCommand ? { spawnCommand: capturedSpawnCommand } : {}),
+                    // A fast initial turn can complete via `botmux send` before Herdr
+                    // reports idle and this ready IPC is emitted. Tell the daemon not to
+                    // post a stale Starting card after the final reply is already visible.
+                    replyAlreadySent: readSendMarkers().some(marker => marker.sentAtMs >= initStartedAtMs),
                     turnId: currentBotmuxTurnId,
                     dispatchAttempt: currentBotmuxDispatchAttempt,
                 });
@@ -9282,6 +9814,21 @@ process.on('message', async (raw) => {
             // Mark new turn baseline so the streaming card only shows this turn's content
             renderer?.markNewTurn();
             const turnSeq = usageLimitTracker.beginTurn(currentUsageLimitSnapshot());
+            if (msg.nativeSessionTitlePrompt
+                && msg.nativeSessionTitle
+                && lastInitConfig?.cliId === 'codex'
+                && !lastInitConfig.adoptMode) {
+                nativeSessionTitleRevision += 1;
+                nativeSessionTitleAppliedThreadId = undefined;
+                lastInitConfig.nativeSessionTitle = msg.nativeSessionTitle;
+                lastInitConfig.nativeSessionTitlePrompt = msg.nativeSessionTitlePrompt;
+                stopNativeSessionTitleSync();
+                const threadId = codexRpcEngine?.activeThreadId
+                    ?? lastSpawnEffectiveCliSessionId
+                    ?? lastInitConfig.cliSessionId;
+                if (threadId)
+                    void syncFreshCodexNativeSessionTitle(threadId, codexRpcEngine);
+            }
             // Cancel any active tmux copy-mode scroll so user input reaches the CLI.
             if (tmuxScrolledHalfPages > 0)
                 exitTmuxScrollMode();
@@ -9299,12 +9846,16 @@ process.on('message', async (raw) => {
                 log('Message received after crash-loop stop; retrying CLI start');
                 destroyCrashDiagnosticTerminal('retry after message');
                 stopScreenAnalyzer();
+                stopStuckDetector();
                 stopScreenUpdates();
                 awaitingFirstPrompt = true;
                 startScreenUpdates();
                 startScreenAnalyzer();
+                startStuckDetector();
                 try {
-                    await spawnCli({ ...lastInitConfig, resume: true, prompt: '' });
+                    const restartCfg = { ...lastInitConfig, resume: true, prompt: '' };
+                    await spawnCli(restartCfg);
+                    await prepareCodexNativeTitleGeneration(restartCfg, codexRpcEngine);
                 }
                 catch (err) {
                     // Pass the message's own attempt (not the stale currentBotmux* from a
@@ -9386,6 +9937,9 @@ process.on('message', async (raw) => {
                             if (result && result.submitted === false) {
                                 scheduleSubmitFailureNotify(content, result.recheck, 'submit history', undefined, result.failureReason, turnSeq);
                             }
+                            else {
+                                acknowledgeTurnInputCommitted(msg.turnId);
+                            }
                         }
                         catch (err) {
                             log(`Adopt writeInput error (${lastInitConfig?.cliId}): ${err.message}`);
@@ -9403,9 +9957,11 @@ process.on('message', async (raw) => {
                         // command (raw_input) fix.
                         await new Promise(r => setTimeout(r, 200));
                         backend.sendSpecialKeys('Enter');
+                        acknowledgeTurnInputCommitted(msg.turnId);
                     }
                     else {
                         backend.write(content + '\r');
+                        acknowledgeTurnInputCommitted(msg.turnId);
                     }
                     isPromptReady = false;
                     idleDetector?.reset();
@@ -9417,11 +9973,13 @@ 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, msg.turnId, {
+                const inputCommitted = sendToPty(content, msg.turnId, {
                     codexAppInput,
                     dispatchAttempt: msg.dispatchAttempt,
                     vcMeetingImTurnOrigin: msg.vcMeetingImTurnOrigin,
                 });
+                if (inputCommitted)
+                    acknowledgeTurnInputCommitted(msg.turnId);
             }
             break;
         }
@@ -9449,6 +10007,13 @@ process.on('message', async (raw) => {
             // IPC handlers are concurrent with async init, so queue first even when
             // the adapter/backend has not finished initializing. flushPending will
             // capability-check and deliver the latest title once a real prompt is idle.
+            nativeSessionTitleRevision += 1;
+            nativeSessionTitleAppliedThreadId = undefined;
+            if (lastInitConfig) {
+                lastInitConfig.nativeSessionTitle = msg.title;
+                lastInitConfig.nativeSessionTitlePrompt = undefined;
+            }
+            stopNativeSessionTitleSync();
             pendingSessionRename = msg.title;
             log(`Queued native session rename: ${msg.title}`);
             void flushPending();
@@ -9545,7 +10110,49 @@ process.on('message', async (raw) => {
             break;
         }
         case 'tui_keys': {
-            handleTuiKeys(msg.keys, msg.isFinal);
+            // Stale-card guard: if this key press came from a stuck-warning card,
+            // delegate to processStuckWarningTuiKeys which does a FRESH capture (not
+            // the 2s-cached lastAnalyzerSnapshot) and re-verifies the current screen
+            // still matches the page type the card was built for. Fail-closed: any
+            // mismatch (lifetime, capture, backend, page type, write failure) sends
+            // stuck_warning_expired and drops the keys. ScreenAnalyzer TUI cards
+            // (no stuckNonce) bypass the guard and write keys directly.
+            let wroteKeys = false;
+            if (msg.stuckNonce !== undefined && msg.stuckPageType) {
+                const result = await processStuckWarningTuiKeys({
+                    stuckNonce: msg.stuckNonce,
+                    stuckPageType: msg.stuckPageType,
+                    stuckCliLifetime: msg.stuckCliLifetime,
+                    keys: msg.keys,
+                    isFinal: msg.isFinal,
+                }, {
+                    getBackend: () => backend,
+                    getCurrentLifetime: () => cliLifetimeNonce,
+                    renderCols,
+                    renderRows,
+                    turnId: currentBotmuxTurnId,
+                    dispatchAttempt: currentBotmuxDispatchAttempt,
+                    capture: snapshotToText,
+                    match: matchHookReviewScreen,
+                    writeKeys: handleTuiKeys,
+                    sendExpired: (nonce, turnId, dispatchAttempt) => send({ type: 'stuck_warning_expired', nonce, turnId, dispatchAttempt }),
+                    sendDelivered: (nonce, turnId, dispatchAttempt) => send({ type: 'tui_keys_delivered', nonce, turnId, dispatchAttempt }),
+                    log,
+                });
+                wroteKeys = result.wroteKeys;
+            }
+            else {
+                await handleTuiKeys(msg.keys, msg.isFinal);
+                wroteKeys = true;
+            }
+            // Re-arm the stuck detector ONLY when the card-handler explicitly flags
+            // this as a stuck-warning card's Enter action (advances to the next
+            // review layer) AND keys were actually written. An expired click (CLI
+            // recovered, page changed) must NOT re-arm — the detector should stay
+            // disarmed until the next real stall. t/Esc and all ScreenAnalyzer cards
+            // never set this flag.
+            if (shouldRearmStuckDetector(!!msg.rearmStuckDetector, wroteKeys))
+                stuckDetector?.arm();
             break;
         }
         case 'inject_command': {
@@ -9710,6 +10317,7 @@ process.on('message', async (raw) => {
 });
 // ─── Cleanup ─────────────────────────────────────────────────────────────────
 function cleanup() {
+    stopNativeSessionTitleSync();
     cleanupPiInitialPromptFiles();
     stopSessionMcpGatewayHost();
     if (tmuxRestartTimer) {
@@ -9814,7 +10422,11 @@ function teardownSandboxBestEffort() {
 // 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(); stopCodexRpcEngine(); });
+process.on('exit', () => {
+    stopNativeSessionTitleSync();
+    teardownSandboxBestEffort();
+    stopCodexRpcEngine();
+});
 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.