botmux 3.5.0 → 3.6.0

package/dist/worker.js

@@ -18,14 +18,17 @@ import { atomicWriteFileSync } from './utils/atomic-write.js';
 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 { evaluateCredentialOnlyIsolationGate, credentialIsolationRequired, deviceCredentialIsolationMarkerPath, isCredentialIsolationReservedBasename, buildCredentialIsolationRules, buildSeatbeltProfile, isolatedPaneReattachSafe, sendCredFilePath, botHomePath, buildCliExecutableReadCarveOuts, isolationPaneMarkerContent, } from './adapters/cli/read-isolation.js';
+import { buildFsPolicy, compileToSeatbelt, migrateLegacySandboxFields } from './adapters/cli/fs-policy.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 { drainTranscript, joinAssistantText, trailingAssistantText, findJsonlContainingFingerprint, findJsonlsContainingExactContent, findLatestJsonl, extractLastAssistantTurn, extractTurnStartText, splitTranscriptEventsByCutoff, isTranscriptRateLimitEvent, apiErrorMessageText } from './services/claude-transcript.js';
 import { BridgeTurnQueue, makeFingerprint, normaliseForFingerprint } from './services/bridge-turn-queue.js';
-import { shouldSuppressBridgeEmit } from './services/bridge-fallback-gate.js';
+import { shouldEmitEmptyCompletedBridgeFallback, shouldSuppressBridgeEmit } from './services/bridge-fallback-gate.js';
 import { decideHardTimeoutAction, decideSettleMarkReady, shouldReleaseFirstPromptTimeout, shouldWaitForPostSessionStartPromptEvidence, shouldWriteNow, } from './utils/input-gate.js';
+import { decideCodexRunnerFreshness, CodexRunnerFreshnessInputQueue, shouldHoldCodexRunnerInput, } from './services/codex-runner-freshness.js';
 import { canStartInjectionFlush, shouldDeferUserFlush, shouldFlushInjectionsFirst } from './core/inject-queue-policy.js';
+import { decideRestartFollowup, settleDurableTurnForRestart } from './core/restart-followup-policy.js';
 import { stripAnsiForLog, tailChars } from './utils/crash-log.js';
 import { CodexUpdateDialogGuard } from './utils/codex-update-dialog.js';
 import { installStdioEpipeGuard, isIgnorableStreamError } from './utils/stdio-epipe-guard.js';
@@ -40,7 +43,7 @@ import { sessionMcpGatewayPathRegex, startSessionMcpGatewayHost, } from './core/
 import { MCP_GATEWAY_REQUIRED_ENV, MCP_GATEWAY_SOCKET_ENV, } from './core/plugins/mcp/environment.js';
 import { readSessionMcpRuntimeManifest, sessionMcpRuntimeHostOnlyPaths, } from './core/plugins/mcp/session-runtime.js';
 import { prepareCliPluginGeneration } from './core/plugins/cli-generation.js';
-import { loadBotConfigs } from './bot-registry.js';
+import { loadBotConfigs, resolveBrandLabel } from './bot-registry.js';
 import { readGlobalConfig } from './global-config.js';
 import { deriveTerminalViewToken, deriveTerminalWriteToken, resolveTerminalAccessForRequest, safeTerminalTokenEqual, } from './core/terminal-write-auth.js';
 import { readPlatformBinding } from './platform/binding.js';
@@ -65,6 +68,7 @@ import { drainCursorTranscript, findCursorChatIdByPid, findCursorTranscriptByCha
 import { shouldObserveCursorChatId, shouldPersistObservedCursorChatId } from './services/cursor-resume-policy.js';
 import { extractKiroSessionIdFromOutput } from './services/kiro-session.js';
 import { baselineJsonlCursor } from './services/jsonl-cursor.js';
+import { fileURLToPath } from 'node:url';
 import { createServer as createHttpServer } from 'node:http';
 import { WebSocketServer, WebSocket } from 'ws';
 import { listenWebTerminalWithFallback } from './utils/web-terminal-listen.js';
@@ -76,7 +80,7 @@ import { DEFAULT_RENDER_COLS, DEFAULT_RENDER_ROWS, MAX_RENDER_COLS, MAX_RENDER_R
 import { createCliAdapterSync, locateOnPath } from './adapters/cli/registry.js';
 import { buildWrappedLaunch, parseWrapperCli, isTtadkWrapper } from './setup/cli-selection.js';
 import { cliUnavailableMessage } from './setup/cli-availability.js';
-import { findLaunchedCliPid, scheduleWrapperRealCliPid, readComm, isBareShellComm, bareShellLaunchKind } from './core/session-discovery.js';
+import { findLaunchedCliPid, scheduleWrapperRealCliPid, readComm, isBareShellComm, bareShellLaunchKind, settleLaunchComm, } from './core/session-discovery.js';
 import { codexRpcEligible, paneRunsRemoteTui, orchestrateCodexRpcInit, rolloutUserTurnMatches, decideStartupDialogAction, shouldQueueInitialPrompt, shouldPreMarkFirstTurn, killAndVerifyPersistentPane } from './codex-rpc-lifecycle.js';
 import { delay } from './utils/timing.js';
 import { claudeJsonlPathForSession, resolveJsonlFromPid, findOpenClaudeSessionIds, syncClaudeResumeTargetToCwd, DEFAULT_CLAUDE_DATA_DIR } from './adapters/cli/claude-code.js';
@@ -92,12 +96,11 @@ 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 { prepareDirectSandbox, prepareCredentialOnlySandbox, credentialOnlySandboxAvailable, probeHostCredentialIsolationMechanism, attachSandboxOutbox, startOutboxWatcher, sandboxEnabled, localSandboxApplies, } from './adapters/backend/sandbox.js';
 import { DEVICE_AUTHORITY_DIRECTORY, DEVICE_CREDENTIAL_FILE, } from './platform/device-paths.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 { StuckDetector, matchHookReviewScreen } from './utils/stuck-detector.js';
 import { processStuckWarningTuiKeys, shouldRearmStuckDetector } from './utils/stuck-key-guard.js';
 import { captureToPng } from './utils/screenshot-renderer.js';
@@ -105,7 +108,7 @@ import { snapshotToPng, snapshotToText, shouldCaptureScreen, isScreenSelfDriven
 import { chooseWebTerminalSeed } from './utils/web-terminal-seed.js';
 import { mergeHerdrWebSnapshot, renderHerdrWebHistory, } from './utils/herdr-web-history.js';
 import { parseWorkerRequestUrl } from './utils/worker-http.js';
-import { detectCliUsageLimit, usageLimitStateKey } from './utils/cli-usage-limit.js';
+import { detectCliUsageLimit, usageLimitStateKey, structuredRateLimitState } from './utils/cli-usage-limit.js';
 import { uploadImageBuffer } from './utils/lark-upload.js';
 import { redactChildEnv, scrubSessionCliHomeEnv } from './utils/child-env.js';
 import { decideSubmitConfirmationAction } from './services/submit-confirmation.js';
@@ -120,6 +123,7 @@ 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';
+import { normalizeAppRunnerFinalMarker, normalizeCodexAppLifecycleEvent, projectAppRunnerFinalIds, } from './services/codex-app-runner-protocol.js';
 import { hasMatchingManagedOriginCapability, managedOriginCapabilityPath, RELAY_ORIGIN_CAPABILITY_BASENAME, replaceManagedOriginCapabilityFile, } from './core/managed-origin-capability.js';
 import { CodexRpcEngine } from './codex-rpc-engine.js';
 // A worker must never trust an INHERITED session-level CLI home pointer
@@ -690,7 +694,7 @@ function armRpcStartupDialogDismiss() {
 let cliPidMarker = null; // path to .botmux-cli-pids/<pid>
 let seatbeltProfilePath = null; // per-session Seatbelt .sb profile to rm at exit (external-wrapper read isolation)
 let sandboxStopWatcher = null; // stop fn for the sandbox outbox watcher
-let sandboxCleanup = null; // unmount overlays + rm the per-session sandbox tree
+let sandboxCleanup = null; // reclaim deny-mask mountpoints + rm the per-session sandbox tree
 let sandboxRelayOutbox = null;
 let sandboxRelayCapability = null;
 let readIsolationOriginCapabilityFile = null;
@@ -953,6 +957,12 @@ const IDLE_PROBE_INTERVAL_MS = 3_500;
 const IDLE_PROBE_MAX_ATTEMPTS = 24;
 let busyPatternIdleProbeTimer = null;
 let reattachIdleProbeTimer = null;
+let codexRunnerFreshness = 'current';
+let persistCodexRunnerBuildOnReady = false;
+let activeRestartAttemptId;
+/** Distinguishes a replacement's synchronous ready signal (Riff) from a late
+ * idle callback emitted by the backend being torn down. */
+let replacementSpawnInProgress = false;
 /** The effectiveResume flag used by the most recent spawnCli call. Written
  *  immediately after the two-tier fallback check so late-attach timers
  *  (hermes, cursor, etc.) can read THE SAME semantics the spawn used,
@@ -1104,6 +1114,17 @@ let bareShellLaunchBlocked = false;
  *  one-shot so it also covers a reattach onto a pane that degraded to a bare
  *  shell. Reset per spawn in spawnCli. */
 let bareShellChecked = false;
+/** True only while detectBareShellLaunch() is inside its async launch-settle
+ *  window (settleLaunchComm's bounded ≤2s poll for a wrapper's final `exec
+ *  <cli>`). The message/injection flush paths already hold the isFlushing /
+ *  injectionFlushing mutexes across that await, but raw_input (passthrough
+ *  slash commands: /compact, /model, /btw) deliberately bypasses those to
+ *  preserve busy-delivery — so it would otherwise type into a pane whose leaf
+ *  is still the transient shell (or a shell already about to be blocked). This
+ *  latch lets raw_input defer for exactly that window without borrowing the
+ *  general isFlushing mutex (which would wrongly also block busy-delivery when
+ *  no settle is in progress). Reset per spawn in spawnCli. */
+let bareShellCheckInProgress = false;
 /** Ready-gate (Claude-family): holds the first prompt until the SessionStart
  *  hook proves a cjadk-style startup selector is behind us. Claude then needs
  *  fresh post-hook prompt evidence because sibling hooks may still be running.
@@ -1342,11 +1363,42 @@ async function runStartupCommands() {
     isPromptReady = false;
     idleDetector?.reset();
 }
-const pendingMessages = [];
+const freshnessInputQueue = new CodexRunnerFreshnessInputQueue(() => codexRunnerFreshness, state => { codexRunnerFreshness = state; });
+const pendingMessages = freshnessInputQueue.normal;
+/** Correlation ids that this worker actually wrote into the owned Codex App
+ * runner. Runner lifecycle/final markers may route only to ids in this bounded
+ * local set; model/user display bytes cannot add entries. */
+const submittedCodexAppReplyTurnIds = new Set();
+const pendingCodexAppSteerAckIds = new Map();
+const acknowledgedCodexAppSteers = new Set();
+const CODEX_APP_CORRELATION_LIMIT = 256;
+function rememberBounded(set, value) {
+    set.delete(value);
+    set.add(value);
+    while (set.size > CODEX_APP_CORRELATION_LIMIT) {
+        const oldest = set.values().next().value;
+        if (typeof oldest !== 'string')
+            break;
+        set.delete(oldest);
+    }
+}
+function rememberBoundedMap(map, key, value) {
+    map.delete(key);
+    map.set(key, value);
+    while (map.size > CODEX_APP_CORRELATION_LIMIT) {
+        const oldest = map.keys().next().value;
+        if (typeof oldest !== 'string')
+            break;
+        map.delete(oldest);
+    }
+}
+function shortCorrelationId(value) {
+    return value?.slice(0, 12) ?? '-';
+}
 /** Literal commands that arrived while native /rename owned the TUI or while
  * an owned CLI restart was fenced. Normal raw_input commands are still
  * delivered immediately (including while busy). */
-const pendingRawInputs = [];
+const pendingRawInputs = freshnessInputQueue.raw;
 /** Latest requested canonical session title. Unlike a normal prompt this is an
  * 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. */
@@ -1690,6 +1742,24 @@ function writeCliPidMarker() {
     }
 }
 let lastStructuredBridgeActivityAtMs = 0;
+/**
+ * True when this CLI has an authoritative STRUCTURED rate-limit signal in its
+ * transcript (Claude family — `error:"rate_limit"`, surfaced by
+ * maybeEmitStructuredRateLimit). For those CLIs the screen-text `rate`
+ * heuristic is not just redundant but harmful: the model's own output or a dev
+ * editing rate-limit code/tests puts phrases like "429 Too Many Requests" /
+ * "exceeded retry limit" on screen, which the scraper cannot distinguish from a
+ * real limit. So we suppress the screen-scan `rate` verdict and let the
+ * structured path be the sole authority. `usage` (quota "hit your limit …")
+ * has no structured equivalent yet, so it still comes from the screen.
+ *
+ * reliableTurnTerminal is exactly the "transcript-backed" capability flag
+ * (claude-code / seed set it); non-transcript CLIs (Codex, gemini, …) keep the
+ * screen scanner as their only rate-limit signal.
+ */
+function structuredRateLimitAuthoritative() {
+    return cliAdapter?.reliableTurnTerminal === true;
+}
 // Per-turn usage-limit state machine. Owns the turn counter plus the
 // "did this turn hit a limit" / "suppress a stale retry-ready banner" flags, so
 // classify()'s state writes are explicit method calls rather than hidden
@@ -1708,7 +1778,7 @@ function createUsageLimitTracker() {
         beginTurn(snapshot) {
             turnSeq++;
             detectedTurn = undefined;
-            const current = detectCliUsageLimit(snapshot);
+            const current = detectCliUsageLimit(snapshot, undefined, { suppressRateKind: structuredRateLimitAuthoritative() });
             suppressedRetryReadyKey = current.limited && current.retryReady
                 ? usageLimitStateKey(current)
                 : undefined;
@@ -1717,7 +1787,7 @@ function createUsageLimitTracker() {
         // Map a runtime status to a usage-limit-aware status, recording whether this
         // turn hit a limit (read back via detectedThisTurn).
         classify(content, status) {
-            const detected = detectCliUsageLimit(content);
+            const detected = detectCliUsageLimit(content, undefined, { suppressRateKind: structuredRateLimitAuthoritative() });
             if (!detected.limited)
                 return { status };
             const key = usageLimitStateKey(detected);
@@ -1731,6 +1801,15 @@ function createUsageLimitTracker() {
         detectedThisTurn(seq) {
             return detectedTurn === seq;
         },
+        // Record a limit that came from a STRUCTURED signal (transcript error
+        // record) rather than screen text. Mirrors classify()'s state writes so
+        // the tracker stays coherent: mark this turn as having hit a limit (read
+        // by detectedThisTurn for the submit-confirmation recheck) and clear any
+        // stale retry-ready suppression. The actual emit is done by the caller.
+        noteStructuredLimit() {
+            suppressedRetryReadyKey = undefined;
+            detectedTurn = turnSeq;
+        },
     };
 }
 const usageLimitTracker = createUsageLimitTracker();
@@ -1800,6 +1879,11 @@ const bridgeSecondaryPaths = new Map(); // path → offset
 let bridgeOffset = 0;
 let bridgePendingTail = '';
 const bridgeQueue = new BridgeTurnQueue();
+/** uuids of Claude transcript rate-limit records we've already turned into a
+ *  `limited` emit. drainTranscript re-reads from offset 0 on truncation /
+ *  rotation and emitReadyTurns re-drains from 0, so the same rate_limit record
+ *  can resurface; keying on the record's stable uuid makes the emit idempotent. */
+const emittedRateLimitUuids = new Set();
 let bridgeWatcher = null;
 let bridgeFallbackTimer = null;
 let herdrAdoptBridgeQuietTimer = null;
@@ -1893,6 +1977,9 @@ function formatHeadlessLocalTurnContent(assistantText) {
     const a = truncatePreambleText(assistantText.trim(), LOCAL_TURN_ASSISTANT_MAX);
     return a || null;
 }
+function emptyCompletedBridgeFallbackContent() {
+    return t('worker.empty_final_completed', { cliName: cliName() });
+}
 // ─── Bridge fallback marker (non-adopt) ────────────────────────────────────
 //
 // `botmux send` (cli.ts cmdSend) appends a line
@@ -2730,11 +2817,45 @@ function bridgeIngest() {
     if (result.events.length > 0)
         lastStructuredBridgeActivityAtMs = Date.now();
     bridgeQueue.ingest(result.events, bridgeJsonlPath);
+    // Structured rate-limit: Claude Code writes an `error:"rate_limit"` record
+    // at the turn's terminal boundary. This is the authoritative "limited"
+    // signal — read it here (event-driven, once per record) instead of scraping
+    // the TUI. The queue already skips it as an assistant reply.
+    maybeEmitStructuredRateLimit(result.events);
     // Transcript terminal markers are authoritative and may settle a durable
     // turn immediately. Do not wait for the screen prompt: permission/AskUser
     // surfaces can resemble idle, while an explicit JSONL boundary cannot.
     emitReadyTurns({ explicitTerminalOnly: true });
 }
+/** Scan newly-drained Claude transcript events for a structured rate-limit
+ *  record and, on the first unseen one, emit a `limited` screen_update so the
+ *  session surfaces in Dashboard「需要你」with a retry countdown — identical
+ *  wire shape to the screen-text detector's classify() output, so the daemon /
+ *  card / persistence paths need no change. Claude-only (bridgeQueue is the
+ *  Claude bridge; Codex uses codexBridgeQueue and has no structured 429). */
+function maybeEmitStructuredRateLimit(events) {
+    for (const ev of events) {
+        if (!ev.uuid || emittedRateLimitUuids.has(ev.uuid))
+            continue;
+        if (!isTranscriptRateLimitEvent(ev))
+            continue;
+        emittedRateLimitUuids.add(ev.uuid);
+        // Prefer a clock parsed from the record's own text ("... resets 10:40pm");
+        // fall back to the shared bucketed cooldown when it carries none.
+        const usageLimit = structuredRateLimitState(apiErrorMessageText(ev));
+        usageLimitTracker.noteStructuredLimit();
+        send({
+            type: 'screen_update',
+            content: currentUsageLimitSnapshot(),
+            status: 'limited',
+            usageLimit,
+            turnId: currentBotmuxTurnId,
+            dispatchAttempt: currentBotmuxDispatchAttempt,
+        });
+        log(`Structured rate-limit detected in Claude transcript (uuid=${ev.uuid.substring(0, 8)}, retryLabel=${usageLimit.retryLabel}) → emitted limited state.`);
+        return; // one limited emit per ingest is enough; state key is stable
+    }
+}
 function performBridgeIngestAndScheduleQuietEmit() {
     const beforePath = bridgeJsonlPath;
     const beforeOffset = bridgeOffset;
@@ -3263,6 +3384,7 @@ function hermesBridgeIngest() {
     // `/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) {
+        persistCliSessionId(boundSourceSessionId);
         send({ type: 'bridge_source_session', bridge: 'hermes', sourceSessionId: boundSourceSessionId });
         log(`Hermes bridge bound sourceSessionId=${boundSourceSessionId}`);
     }
@@ -3675,6 +3797,37 @@ function codexBridgeDrainAndMaybeEmit(opts = {}) {
     }
     emitReadyCodexTurns();
 }
+/** Before we emit a fail-closed `ambiguous` terminal for a durable turn that a
+ *  CLI kill is about to interrupt, give an already-persisted `completed` record
+ *  a chance to win the worker-local terminal deduper. `reliableTurnTerminal`
+ *  CLIs (claude-code / codex / grok / traex) durably append their terminal line
+ *  to the transcript; if that line landed microseconds before the kill but the
+ *  fs.watch/1s poller hasn't consumed it yet, an unconditional `ambiguous` would
+ *  claim the deduper first and needlessly mark a turn that actually completed →
+ *  same durable key re-dispatchable → external side effect executed twice.
+ *  Draining here publishes that `completed` (claiming the deduper) so the later
+ *  `ambiguous` becomes a no-op. Shared by the CLI `onExit` path and the daemon
+ *  `restart` IPC path — both must drain identically before their ambiguous emit. */
+function drainReliableTerminalBeforeInterrupt() {
+    if (cliAdapter?.reliableTurnTerminal !== true)
+        return;
+    if (bridgeJsonlPath) {
+        try {
+            bridgeDrainAndMaybeEmit();
+        }
+        catch (err) {
+            log(`Bridge terminal drain failed: ${err.message}`);
+        }
+    }
+    if (codexBridgeFallbackActive()) {
+        try {
+            codexBridgeDrainAndMaybeEmit({ signalIdle: false });
+        }
+        catch (err) {
+            log(`Codex bridge terminal drain failed: ${err.message}`);
+        }
+    }
+}
 function emitReadyCodexTurns() {
     const ready = codexBridgeQueue.drainEmittable();
     if (ready.length === 0)
@@ -3698,11 +3851,22 @@ function emitReadyCodexTurns() {
         : undefined;
     for (let i = 0; i < ready.length; i++) {
         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)) {
+        const gateInput = {
+            markTimeMs: turn.markTimeMs,
+            isLocal: turn.isLocal,
+            finalText: turn.finalText,
+            terminalStatus: turn.terminalStatus,
+        };
+        const content = turn.finalText && turn.finalText.trim()
+            ? turn.finalText
+            : shouldEmitEmptyCompletedBridgeFallback(gateInput, nextBoundaryMs, markers, adoptMode)
+                ? emptyCompletedBridgeFallbackContent()
+                : '';
+        if (!content)
+            continue;
+        if (shouldSuppressBridgeEmit(gateInput, nextBoundaryMs, markers, adoptMode)) {
             log(`Codex bridge fallback suppressed for turn ${turn.turnId.substring(0, 8)} (gate)`);
             continue;
         }
@@ -3711,7 +3875,7 @@ function emitReadyCodexTurns() {
             // so the Lark thread sees a complete exchange instead of an orphan
             // reply. formatLocalTurnFields caps both texts to keep within
             // Lark's per-message limit; daemon owns the card chrome.
-            const fields = formatLocalTurnFields(turn.userText ?? '', turn.finalText);
+            const fields = formatLocalTurnFields(turn.userText ?? '', content);
             if (!fields)
                 continue;
             send({
@@ -3729,7 +3893,7 @@ function emitReadyCodexTurns() {
         send({
             type: 'final_output',
             ...(sourceHermesSessionId ? { sourceHermesSessionId } : {}),
-            content: turn.finalText,
+            content,
             lastUuid: turn.turnId,
             turnId: turn.turnId,
             ...(turn.dispatchAttempt !== undefined ? { dispatchAttempt: turn.dispatchAttempt } : {}),
@@ -3851,8 +4015,9 @@ let renderRows = PTY_ROWS;
 // ─── Headless Terminal for Screen Capture ────────────────────────────────────
 let renderer = null;
 /** Most recent unfiltered viewport text — kept in sync by the screen_update
- *  timer for pipe-pane backends so ScreenAnalyzer (which is synchronous) has
- *  a fresh snapshot to read without needing its own tmux capture-pane call. */
+ *  timer for pipe-pane backends so usage-limit detection and the CoCo picker
+ *  have a fresh snapshot to read without needing their own tmux capture-pane
+ *  call. (Historically also fed the AI ScreenAnalyzer, now removed.) */
 let lastAnalyzerSnapshot = '';
 let screenUpdateTimer = null;
 const SCREEN_UPDATE_INTERVAL_MS = 2_000;
@@ -4026,14 +4191,14 @@ function parkCrashDiagnosticTerminal(code, signal) {
     // so the diagnostic shell stays visible. flushPending's retry path restarts
     // both when the next message respawns the CLI.
     stopScreenUpdates();
-    stopScreenAnalyzer();
     stopStuckDetector();
     log(`Crash diagnostic tmux session parked at ${TmuxBackend.diagnosticSessionName(sessionId)}`);
     return true;
 }
-// ─── Screen Analyzer (AI-based TUI prompt detection) ────────────────────────
-let screenAnalyzer = null;
-/** When true, user messages are queued because a TUI prompt is active */
+// ─── TUI prompt blocking state ──────────────────────────────────────────────
+/** When true, user messages are queued because a TUI prompt is active. Set by
+ *  the ask-hook / CoCo picker paths (driveCocoPicker, handleTuiKeys); cleared
+ *  when the prompt resolves or a Lark/terminal input overrides it. */
 let tuiPromptBlocking = false;
 function isWorkflowWorker() {
     return process.env.BOTMUX_WORKFLOW === '1';
@@ -4095,54 +4260,6 @@ function maybeEmitWorkflowTranscriptOutput() {
     });
     log('Workflow PTY transcript final_output emitted');
 }
-function startScreenAnalyzer() {
-    const sa = config.screenAnalyzer;
-    log(`ScreenAnalyzer config: enabled=${sa.enabled}, baseUrl=${sa.baseUrl ? 'set' : 'empty'}, model=${sa.model || 'empty'}, extraHeaders=${JSON.stringify(sa.extraHeaders)}`);
-    if (!sa.enabled || !sa.baseUrl || !sa.apiKey || !sa.model)
-        return;
-    screenAnalyzer = new ScreenAnalyzer({
-        baseUrl: sa.baseUrl,
-        apiKey: sa.apiKey,
-        model: sa.model,
-        intervalMs: sa.intervalMs,
-        stableCount: sa.stableCount,
-        snapshotMaxChars: sa.snapshotMaxChars,
-        extraHeaders: sa.extraHeaders,
-        extraBody: sa.extraBody,
-    }, {
-        getSnapshot: () => {
-            // ScreenAnalyzer is called every ~5s for TUI-prompt detection. We
-            // can't make this async without overhauling the analyzer, so cache
-            // the last pipe-pane text snapshot here and refresh it eagerly.
-            // For pipe-pane backends, the cache is repopulated by the screen
-            // update timer; for others, fall through to the long-lived renderer.
-            return lastAnalyzerSnapshot || renderer?.rawSnapshot() || '';
-        },
-        onAnalyzing: () => { },
-        onTuiPrompt: (description, options, multiSelect) => {
-            tuiPromptBlocking = true;
-            send({ type: 'tui_prompt', description, options, multiSelect, turnId: currentBotmuxTurnId, dispatchAttempt: currentBotmuxDispatchAttempt });
-        },
-        onTuiPromptResolved: (selectedText) => {
-            tuiPromptBlocking = false;
-            send({
-                type: 'tui_prompt_resolved',
-                selectedText,
-                turnId: currentBotmuxTurnId,
-                dispatchAttempt: currentBotmuxDispatchAttempt,
-            });
-            // Flush any messages that were queued during the prompt
-            flushPending();
-        },
-        log,
-    });
-    screenAnalyzer.start();
-}
-function stopScreenAnalyzer() {
-    screenAnalyzer?.dispose();
-    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.
@@ -4339,8 +4456,6 @@ async function captureAndUpload() {
         return;
     }
     let status = isPromptReady ? 'idle' : 'working';
-    if (screenAnalyzer?.isAnalyzing)
-        status = 'analyzing';
     send({
         type: 'screenshot_uploaded',
         imageKey,
@@ -4430,14 +4545,12 @@ function handleTermAction(key) {
     else if (PTY_SEQ_MAP[key]) {
         backend.write(PTY_SEQ_MAP[key]);
     }
-    // ESC/Ctrl-C/Enter likely ends an active TUI prompt. The analyzer
-    // won't re-analyze while promptActive=true, so un-wedge both flags here.
-    // Without this, dismissing an AskUserQuestion dialog via the quick-key
-    // button leaves tuiPromptBlocking=true forever and silently queues every
-    // subsequent user message.
+    // ESC/Ctrl-C/Enter likely ends an active TUI prompt. Un-wedge the blocking
+    // flag here — without this, dismissing an AskUserQuestion dialog via the
+    // quick-key button leaves tuiPromptBlocking=true forever and silently queues
+    // every subsequent user message.
     if (tuiPromptBlocking && (key === 'esc' || key === 'ctrlc' || key === 'enter')) {
         tuiPromptBlocking = false;
-        screenAnalyzer?.notifySelection(`term_action:${key}`);
         void flushPending();
     }
     log(`Term action: ${key}`);
@@ -4484,18 +4597,18 @@ async function handleTuiKeys(keys, isFinal) {
             isPromptReady = false;
             idleDetector?.reset();
         }
-        screenAnalyzer?.notifySelection('final');
     }
     log(`TUI keys: ${keys.join(' ')}${isFinal ? ' (final)' : ''}`);
     return true;
 }
 // 待注入的 TUI 命令队列。生命周期绑定当前 CLI 进程：killCli() 会清空它，
 // 防止 restart 后残留命令重放进新 CLI——新增清理状态时记得同步那里。
-// barrier=true 标记该注入携带 updateWorkingDir（cwd-move，如 /cd）：markPromptReady
-// 里 barrier 注入必须先于本次 pending 用户消息落地，防止用户消息在「记录已是新
-// cwd、进程仍在旧 cwd」的窗口里被写进旧目录的 CLI。排队策略判定收敛到
-// core/inject-queue-policy.ts（shouldDeferUserFlush / shouldFlushInjectionsFirst）
-// 以获得可单测的纯函数单元——本文件只持有队列状态。
+// barrier 语义：barrier=true 的注入必须先于本次 pending 用户消息落地。历史上
+// 唯一的 barrier 来源是 cwd-move 的 /cd 注入；角色切换改为 restart respawn 后
+// 现存发送方（/slash 白名单注入）全部 barrier=false，机制保留供未来有顺序
+// 依赖的注入复用。排队策略判定收敛到 core/inject-queue-policy.ts
+// （shouldDeferUserFlush / shouldFlushInjectionsFirst）以获得可单测的纯函数
+// 单元——本文件只持有队列状态。
 const pendingInjections = [];
 let injectionFlushing = false;
 /** 排队注入一行 TUI 命令：idle（isPromptReady）时经 sendRawCommandLineSerially 敲入。 */
@@ -4532,9 +4645,18 @@ async function flushPendingInjections() {
             // path sends first runs the detection.
             if (!bareShellChecked) {
                 bareShellChecked = true;
-                if (detectBareShellLaunch())
+                if (await detectBareShellLaunch())
                     return; // finally{} releases the mutex; queue stays
             }
+            // The detector's settle await can span a restart's tmux jitter window
+            // (cliRestartInProgress true, old backend still alive). Re-check the fence
+            // before shift()/write so a queued injection never lands in a CLI already
+            // being torn down. The pending injections are then handled by killCli's
+            // restart policy — which drops them (barrier /cd is already durable in
+            // workingDir; non-barrier injects are best-effort and not replayed
+            // cross-process), unlike pendingMessages which killCli preserves.
+            if (cliRestartInProgress)
+                return;
             const item = pendingInjections.shift();
             const cmd = item.command;
             isPromptReady = false;
@@ -4594,7 +4716,6 @@ async function handleTuiTextInput(keys, text) {
         isPromptReady = false;
         idleDetector?.reset();
     }
-    screenAnalyzer?.notifySelection('text-input');
     // Wait briefly so the cursor position is stable before pasting
     await new Promise(r => setTimeout(r, 200));
     // Step 3: write text via cliAdapter (auto-switches to text mode + submits with Enter)
@@ -4753,9 +4874,74 @@ function handleCodexAppMarker(body) {
         persistCliSessionId(payload.threadId);
         return;
     }
-    if (kind === 'final' && typeof payload.content === 'string') {
-        const startedAtMs = typeof payload.startedAtMs === 'number' ? payload.startedAtMs : undefined;
-        const completedAtMs = typeof payload.completedAtMs === 'number' ? payload.completedAtMs : Date.now();
+    if (kind === 'lifecycle') {
+        const event = normalizeCodexAppLifecycleEvent(payload);
+        if (!event) {
+            log(`${cliName()} rejected malformed lifecycle marker`);
+            return;
+        }
+        log(`${cliName()} lifecycle kind=${event.kind}`
+            + ` appTurn=${shortCorrelationId(event.appTurnId)}`
+            + ` replyTurn=${shortCorrelationId(event.replyTurnId)}`
+            + `${event.queueLength !== undefined ? ` queue=${event.queueLength}` : ''}`);
+        if (!event.replyTurnId || !submittedCodexAppReplyTurnIds.has(event.replyTurnId))
+            return;
+        if (event.kind === 'steer_attempt') {
+            rememberBoundedMap(pendingCodexAppSteerAckIds, event.replyTurnId, event.appTurnId);
+            return;
+        }
+        const steerKey = `${event.appTurnId}\0${event.replyTurnId}`;
+        if (event.kind !== 'steer_accepted'
+            || pendingCodexAppSteerAckIds.get(event.replyTurnId) !== event.appTurnId
+            || acknowledgedCodexAppSteers.has(steerKey))
+            return;
+        pendingCodexAppSteerAckIds.delete(event.replyTurnId);
+        rememberBounded(acknowledgedCodexAppSteers, steerKey);
+        send({
+            type: 'steer_accepted',
+            appTurnId: event.appTurnId,
+            turnId: event.replyTurnId,
+        });
+        return;
+    }
+    if (kind === 'final') {
+        const marker = normalizeAppRunnerFinalMarker(payload);
+        if (!marker) {
+            log(`${cliName()} rejected malformed final marker`);
+            return;
+        }
+        const startedAtMs = marker.startedAtMs;
+        const completedAtMs = marker.completedAtMs ?? Date.now();
+        if (marker.appTurnId) {
+            const trustedReplyTurnId = marker.replyTurnId
+                && submittedCodexAppReplyTurnIds.has(marker.replyTurnId)
+                ? marker.replyTurnId
+                : undefined;
+            if (marker.replyTurnId && !trustedReplyTurnId) {
+                log(`${cliName()} ignored unsubmitted final reply route `
+                    + `(replyTurn=${shortCorrelationId(marker.replyTurnId)})`);
+            }
+            const identity = projectAppRunnerFinalIds({ ...marker, replyTurnId: trustedReplyTurnId }, currentBotmuxTurnId, `${lastInitConfig?.cliId ?? 'app'}-${Date.now()}`);
+            if (marker.appTurnId !== identity.turnId) {
+                log(`${cliName()} app turn ${shortCorrelationId(marker.appTurnId)} mapped `
+                    + `to botmux turn ${shortCorrelationId(identity.turnId)}`);
+            }
+            const dispatchAttempt = currentBotmuxDispatchAttempt;
+            if (startedAtMs !== undefined && shouldSuppressBridgeEmit({ markTimeMs: startedAtMs, isLocal: false, finalText: marker.content }, completedAtMs + 5_001, readSendMarkers(), false)) {
+                log(`${cliName()} final_output suppressed (model already called botmux send)`);
+                emitTurnTerminal(identity.turnId, 'completed', undefined, dispatchAttempt);
+                return;
+            }
+            send({
+                type: 'final_output',
+                content: marker.content,
+                lastUuid: identity.lastUuid,
+                turnId: identity.turnId,
+                ...(dispatchAttempt !== undefined ? { dispatchAttempt } : {}),
+            });
+            emitTurnTerminal(identity.turnId, 'completed', undefined, dispatchAttempt);
+            return;
+        }
         // Codex App keeps the app-server-generated id separately for diagnostics.
         // Routing must use its stable clientUserMessageId marker; legacy envelopes
         // intentionally omit it and fall back to the worker's frozen botmux turn.
@@ -4780,7 +4966,7 @@ function handleCodexAppMarker(body) {
         // equality for compatibility, but can never select another attempt.
         const dispatchAttempt = currentBotmuxDispatchAttempt;
         if (startedAtMs !== undefined) {
-            const sentByModel = shouldSuppressBridgeEmit({ markTimeMs: startedAtMs, isLocal: false, finalText: payload.content }, completedAtMs + 5_001, readSendMarkers(), false);
+            const sentByModel = shouldSuppressBridgeEmit({ markTimeMs: startedAtMs, isLocal: false, finalText: marker.content }, completedAtMs + 5_001, readSendMarkers(), false);
             if (sentByModel) {
                 log(`${cliName()} final_output suppressed (model already called botmux send)`);
                 emitTurnTerminal(turnId, 'completed', undefined, dispatchAttempt);
@@ -4789,7 +4975,7 @@ function handleCodexAppMarker(body) {
         }
         send({
             type: 'final_output',
-            content: payload.content,
+            content: marker.content,
             lastUuid: turnId,
             turnId,
             ...(dispatchAttempt !== undefined ? { dispatchAttempt } : {}),
@@ -4943,6 +5129,10 @@ function markPromptReadyFromPty() {
 function markPromptReady() {
     if (isPromptReady)
         return; // guard against duplicate calls
+    if (cliRestartInProgress && !replacementSpawnInProgress) {
+        log('Ignoring prompt-ready from backend generation being replaced');
+        return;
+    }
     stopBusyPatternIdleProbe();
     // Ready-gate: a startup selector's ❯ (cjadk et al.) falsely matches
     // readyPattern → the IdleDetector fires idle while the CLI is NOT actually at
@@ -4972,6 +5162,14 @@ function markPromptReady() {
         log('Idle detected during ready-gate settle; deferring prompt-ready until settle completes');
         return;
     }
+    const freshnessAction = freshnessInputQueue.onPromptReady();
+    if (freshnessAction === 'reload') {
+        log('Stale Codex App runner became idle; replacing it before releasing queued input');
+        void restartCliProcess('stale runner reached idle', { immediate: true, preservePending: true });
+        return;
+    }
+    if (freshnessAction === 'ignore')
+        return;
     isPromptReady = true;
     clearSessionRenameInFlight();
     // An old backend can still report idle while its async teardown is running.
@@ -5003,6 +5201,33 @@ function markPromptReady() {
         renderer?.markNewTurn(); // exclude history replay from streaming card
     }
     send({ type: 'prompt_ready' });
+    if (persistCodexRunnerBuildOnReady
+        && lastInitConfig?.cliId === 'codex-app'
+        && lastInitConfig.runnerBuildId) {
+        send({ type: 'runner_build_ready', runnerBuildId: lastInitConfig.runnerBuildId });
+        persistCodexRunnerBuildOnReady = false;
+    }
+    if (activeRestartAttemptId) {
+        // Defense in depth: only report a successful restart when a replacement
+        // backend is actually installed. Every legitimate ready path assigns
+        // `backend` before firing (spawnCli sets it, then idle/PTY callbacks run);
+        // a stray callback that reached here with no backend (e.g. a late stale
+        // generation slipping through a future gate change) must NOT claim success
+        // and consume the attempt id — leave it for the real replacement or the
+        // coordinator timeout.
+        if (backend) {
+            send({
+                type: 'restart_result',
+                attemptId: activeRestartAttemptId,
+                status: 'succeeded',
+                category: 'prompt_ready',
+            });
+            activeRestartAttemptId = undefined;
+        }
+        else {
+            log('prompt-ready with no backend installed — deferring restart success receipt');
+        }
+    }
     // Send immediate idle snapshot so Lark card reflects idle status.
     // BUT: skip when messages are pending — flushPending() will immediately
     // make the CLI busy, so the idle state is transient and shouldn't appear
@@ -5012,13 +5237,11 @@ function markPromptReady() {
         const { content } = renderer.snapshot();
         send({ type: 'screen_update', content, ...usageLimitTracker.classify(content, 'idle'), turnId: currentBotmuxTurnId, dispatchAttempt: currentBotmuxDispatchAttempt });
     }
-    // cwd-move 注入（barrier=true，如 /cd）必须先于本次 pending 用户消息落地：
-    // 用户在 bot 发完「已切换角色」确认后立刻发下一条消息是最常见路径——若
-    // flushPending 先跑，该消息会在 barrier 注入之前被写进旧 cwd 的 CLI（daemon
-    // 记录已是新目录，实际执行仍在旧目录）。跳过本次 flushPending 不会饿死用户
-    // 消息：flushPending 自身的 injectionFlushing 守卫会挡住并发写入，
-    // flushPendingInjections 的 finally 会在注入完成、CLI 重新 idle 后补踢一次
-    // flushPending 排空 pendingMessages。
+    // barrier 注入必须先于本次 pending 用户消息落地（现存发送方均 barrier=false，
+    // 该分支目前不触发；机制保留见 pendingInjections 声明处注释）。跳过本次
+    // flushPending 不会饿死用户消息：flushPending 自身的 injectionFlushing 守卫
+    // 会挡住并发写入，flushPendingInjections 的 finally 会在注入完成、CLI 重新
+    // idle 后补踢一次 flushPending 排空 pendingMessages。
     if (shouldFlushInjectionsFirst(pendingInjections)) {
         void flushPendingInjections();
     }
@@ -5236,19 +5459,41 @@ function scheduleSubmitFailureNotify(msg, recheck, transcriptLabel, bridgeTurnId
  * and the pty/herdr backends (which `exec` the CLI directly — getChildPid is the
  * CLI itself, never a shell).
  *
- * Returns true when a bare-shell launch was detected (caller must NOT flush).
+ * Returns true when a persistent bare-shell launch was detected (caller must
+ * NOT flush). A transient wrapper shell gets a bounded chance to exec the CLI.
  */
-function detectBareShellLaunch() {
+async function detectBareShellLaunch() {
     if (bareShellLaunchBlocked)
         return true;
     if (lastInitConfig?.adoptMode)
         return false; // observing an existing pane, not launching
     if (lastInitConfig?.wrapperCli)
         return false; // launcher legitimately wraps the CLI (transient shell shim)
-    const pid = backend?.getChildPid?.();
-    if (!pid)
+    // Hold the raw_input passthrough latch across the bounded settle poll: the
+    // await below yields the event loop for up to 2s, and a concurrent raw_input
+    // IPC handler (which bypasses isFlushing to preserve busy-delivery) must not
+    // type into the pane while its leaf is still the unsettled shell.
+    bareShellCheckInProgress = true;
+    let comm;
+    try {
+        comm = await settleLaunchComm(() => {
+            const pid = backend?.getChildPid?.();
+            return pid ? readComm(pid) : undefined;
+        });
+    }
+    finally {
+        bareShellCheckInProgress = false;
+    }
+    // A restart can begin while we're suspended in the settle await: tmux staggers
+    // teardown behind a 250–1999ms jitter, so cliRestartInProgress is already true
+    // but the old backend is still alive. Do NOT classify that torn-down pane as a
+    // failed launch — it would set the persistent bareShellLaunchBlocked and emit a
+    // misdiagnosis card for a CLI that's about to be replaced. Return healthy; the
+    // caller's own post-await restart fence keeps the queue intact for the
+    // replacement generation (whose spawnCli resets bareShellChecked and re-runs
+    // this check).
+    if (cliRestartInProgress)
         return false;
-    const comm = readComm(pid);
     if (!isBareShellComm(comm))
         return false; // CLI (rust/go/node) is running — healthy launch
     // Bare shell is the pane leaf → the CLI never launched. Tier the message on
@@ -5297,6 +5542,8 @@ async function flushPending() {
     // backend's idle/task-done callback) write across that restart boundary.
     if (cliRestartInProgress)
         return;
+    if (shouldHoldCodexRunnerInput(codexRunnerFreshness))
+        return;
     if (isFlushing)
         return; // while loop in active flush will pick up new messages
     if (!backend || !cliAdapter)
@@ -5405,10 +5652,19 @@ async function flushPending() {
         // doesn't get them typed into the bare shell first.
         if (!bareShellChecked) {
             bareShellChecked = true;
-            if (detectBareShellLaunch()) {
+            if (await detectBareShellLaunch()) {
                 return; // finally{} releases the mutex; pendingMessages stay queued, untouched
             }
         }
+        // detectBareShellLaunch() awaits a bounded settle poll; a restart can begin
+        // during that yield (tmux staggers teardown behind a 250–1999ms jitter, so
+        // cliRestartInProgress flips true while the old backend is still alive). Do
+        // not write startup commands / rename / user prompts into a CLI already
+        // promised to teardown — re-check the restart fence now, before any shift or
+        // write. The queue is untouched; the replacement generation's markPromptReady
+        // re-invokes flushPending.
+        if (cliRestartInProgress)
+            return; // finally{} releases the mutex; queue stays
         // One-shot per spawn: type the bot's startup commands (e.g. `/effort
         // ultracode`) into the CLI before the first user prompt drains. Both ready
         // paths funnel through flushPending — the ready-gate settle for Claude-family
@@ -5423,7 +5679,9 @@ async function flushPending() {
         // rename. Some passthroughs (/clear, /new) can rotate the native session;
         // applying the canonical title last keeps the resume-picker label aligned.
         if (rawInputReady && pendingRawInputs.length > 0 && backend) {
-            const raw = pendingRawInputs.shift();
+            const raw = freshnessInputQueue.takeRaw();
+            if (!raw)
+                return;
             await deliverRawInput(raw);
             return;
         }
@@ -5452,7 +5710,9 @@ async function flushPending() {
             return;
         }
         while (pendingMessages.length > 0 && backend && cliAdapter) {
-            const item = pendingMessages.shift();
+            const item = freshnessInputQueue.takeNormal();
+            if (!item)
+                break;
             const durableWrite = item.dispatchAttempt !== undefined;
             if (durableWrite)
                 durableTurnInFlight = true;
@@ -5512,7 +5772,13 @@ async function flushPending() {
                 log('Refused durable Claude submit: transcript terminal bridge is unavailable');
                 break;
             }
-            log(`Writing to PTY (flush): "${msg.substring(0, 80)}"`);
+            if (lastInitConfig?.cliId === 'codex-app') {
+                log(`Writing Codex App input to PTY (flush): `
+                    + `replyTurn=${shortCorrelationId(item.turnId)} chars=${msg.length}`);
+            }
+            else {
+                log(`Writing to PTY (flush): "${msg.substring(0, 80)}"`);
+            }
             // Defense in depth: TmuxPipeBackend's send methods no longer throw on a
             // dead pane (they fire onExit instead), but writeInput can still throw
             // for other reasons (fs errors while resolving the JSONL, a future
@@ -5531,10 +5797,10 @@ async function flushPending() {
                     result = { submitted: true };
                 }
                 else if (item.codexAppInput && cliAdapter.writeStructuredInput) {
-                    result = await cliAdapter.writeStructuredInput(backend, msg, item.codexAppInput);
+                    result = await cliAdapter.writeStructuredInput(backend, msg, item.codexAppInput, { turnId: item.turnId });
                 }
                 else {
-                    result = await cliAdapter.writeInput(backend, msg);
+                    result = await cliAdapter.writeInput(backend, msg, { turnId: item.turnId });
                 }
                 scheduleBusyPatternIdleProbe(`${cliName()} post-submit`);
             }
@@ -5554,6 +5820,11 @@ async function flushPending() {
                     scheduleSubmitFailureNotify(logicalMsg, undefined, '会话 JSONL', bridgeTurnId, undefined, turnSeq, item);
                 break;
             }
+            if (lastInitConfig?.cliId === 'codex-app'
+                && item.turnId
+                && result?.submitted !== false) {
+                rememberBounded(submittedCodexAppReplyTurnIds, item.turnId);
+            }
             // Persist any sessionId the adapter observed via authoritative sources
             // (Claude's pid file, Codex's history). Done independently of submit
             // outcome — the rotation is real even when the current Enter didn't
@@ -5613,7 +5884,7 @@ function sendToPty(content, turnId, opts = {}) {
     // old early-return silently dropped it after receiver had already persisted
     // DISPATCHED.
     if (cliRestartInProgress || !backend) {
-        pendingMessages.push(next);
+        freshnessInputQueue.enqueueNormal(next);
         log(`Queued message while CLI backend is restarting (${pendingMessages.length} pending)`);
         return true;
     }
@@ -5624,13 +5895,14 @@ function sendToPty(content, turnId, opts = {}) {
         isFlushing,
         supportsTypeAhead,
         awaitingFirstPrompt,
+        holdForRunnerReload: shouldHoldCodexRunnerInput(codexRunnerFreshness),
     }) && cliAdapter.mergeQueuedInput === true;
     const mergedQueued = shouldMergeQueued && mergeQueuedCliInput(pendingMessages, next);
     if (mergedQueued) {
         log(`Merged queued message (${pendingMessages.length} pending): "${content.substring(0, 80)}" — ${cliName()} ${awaitingFirstPrompt ? 'still booting' : 'is busy'}`);
     }
     else {
-        pendingMessages.push(next);
+        freshnessInputQueue.enqueueNormal(next);
     }
     // User-override semantics: a fresh Lark message while a TUI prompt is "active"
     // takes precedence over the AI-detected prompt. The screen analyzer can be
@@ -5641,7 +5913,6 @@ function sendToPty(content, turnId, opts = {}) {
     if (tuiPromptBlocking) {
         log(`User override: incoming Lark message clears tuiPromptBlocking — "${content.substring(0, 80)}"`);
         tuiPromptBlocking = false;
-        screenAnalyzer?.notifySelection('lark-input');
         // Tear down the prompt card so the user doesn't see stale options.
         send({
             type: 'tui_prompt_resolved',
@@ -5661,7 +5932,11 @@ function sendToPty(content, turnId, opts = {}) {
     // delivers queued messages instead. See input-gate.ts; this fixes dispatch's
     // brief reaching Codex before its first idle and never landing.
     if (!sessionRenameInFlight && commandLineWritesPending === 0 && shouldWriteNow({
-        isPromptReady, isFlushing, supportsTypeAhead, awaitingFirstPrompt,
+        isPromptReady,
+        isFlushing,
+        supportsTypeAhead,
+        awaitingFirstPrompt,
+        holdForRunnerReload: shouldHoldCodexRunnerInput(codexRunnerFreshness),
     })) {
         if (!mergedQueued)
             log(`Writing to PTY: "${content.substring(0, 80)}"`);
@@ -5697,8 +5972,6 @@ function startScreenUpdates() {
         if (awaitingFirstPrompt)
             return;
         let status = isPromptReady ? 'idle' : 'working';
-        if (screenAnalyzer?.isAnalyzing)
-            status = 'analyzing';
         void (async () => {
             let content = lastContent;
             let changed = false;
@@ -5725,8 +5998,9 @@ function startScreenUpdates() {
                     const hash = pipeText.ansi;
                     changed = hash !== lastTextSnapshotHash;
                     lastTextSnapshotHash = hash;
-                    // Refresh the unfiltered cache that ScreenAnalyzer reads from. Same
-                    // tmux call would otherwise need to fire twice per tick.
+                    // Refresh the unfiltered snapshot cache (lastAnalyzerSnapshot) that
+                    // usage-limit detection and the CoCo picker read from. Same tmux
+                    // call would otherwise need to fire twice per tick.
                     if (changed) {
                         const rawSnap = await snapshotToText(backend, renderCols, renderRows, { filter: false });
                         if (rawSnap)
@@ -6364,81 +6638,20 @@ async function spawnCli(cfg, opts = {}) {
     // so a fork inherits the whole submit-confirm + bridge-fallback machinery.
     let claudeDataDir = cliAdapter.claudeDataDir;
     let effectiveReadyHookInstall = cliAdapter.hookInstall;
-    // When this session will be file-sandboxed, the CLI's session jsonl is written
-    // into the overlay's EPHEMERAL home upper (CLAUDE_CONFIG_DIR lives under $HOME),
-    // invisible at the real path the bridge normally watches → "Bridge mark expired"
-    // and the turn never relays (2026-06-10 incident). Redirect every jsonl/pid/
-    // bridge gate below to the upper copy where the sandboxed CLI actually writes.
-    const willFileSandbox = process.platform === 'linux' && // bwrap overlay is Linux-only; macOS uses the Seatbelt write-sandbox below
-        (cfg.sandbox === true || sandboxEnabled()) &&
-        (effectiveBackendType === 'pty' || effectiveBackendType === 'tmux') &&
-        !!process.env.SESSION_DATA_DIR;
-    if (claudeDataDir && willFileSandbox) {
-        const redirected = sandboxedClaudeDataDir(cfg.sessionId, claudeDataDir, {
-            sourceWorkingDir: cfg.workingDir,
-            dataDir: process.env.SESSION_DATA_DIR,
-        });
-        log(`[sandbox] redirecting Claude bridge dataDir → overlay upper: ${redirected}`);
-        claudeDataDir = redirected;
-    }
-    // v2 read isolation: relocate the CLI's data root into the per-bot BOT_HOME
-    // (`<BOTMUX_HOME>/bots/<appId>/{claude,codex}`) so each bot's transcripts/memory
-    // land in its OWN (Seatbelt-allowed) dir, NOT the shared/global ~/.claude|~/.codex
-    // (which v2 denies wholesale). Decided EARLY — like willFileSandbox above — so
-    // every JSONL/bridge/resume path below already targets the per-bot dir. The
-    // matching CLAUDE_CONFIG_DIR/CODEX_HOME env, per-bot provisioning and Seatbelt
-    // wrapper are applied at spawn time further down. This gate is the SINGLE
-    // decision point: configured-but-unenforceable fail-closes HERE (never run a
-    // session unisolated that asked for isolation).
-    // UNIFIED file sandbox: read isolation engages with the same toggle as write
-    // isolation. On darwin the legacy standalone `readIsolation` flag ALSO engages it
-    // (Seatbelt can read-deny without a write overlay). On Linux read isolation RIDES
-    // the bwrap sandbox (its masks go into the same bwrap plan), so it requires the
-    // sandbox to be on — hence the trigger is the sandbox toggle there, never the bare
-    // legacy flag (which would redirect the data dir but apply no masks → a hole).
-    // riff runs in its own REMOTE sandbox with no local CLI process — every
-    // local isolation flavor (Linux bwrap, macOS Seatbelt write-sandbox, read
-    // isolation incl. the legacy fail-closed flag) is meaningless for it and
-    // must be bypassed on ALL platforms, or a sandbox/readIsolation-enabled bot
-    // bricks the moment it switches to riff.
-    const riffRemoteBackend = effectiveBackendType === 'riff';
+    // ── UNIFIED file sandbox (fs-policy, 2026-07-16 refactor) ──
+    // ONE toggle, BOTH platforms, identical three-tier deny-by-default semantics
+    // (adapters/cli/fs-policy.ts). Legacy `readIsolation` is auto-migrated to
+    // `sandbox` at daemon startup; honored here too for an unmigrated read-only
+    // BOTS_CONFIG. riff runs in its own REMOTE sandbox with no local CLI process —
+    // local confinement is meaningless there and must be bypassed on ALL
+    // platforms, or a sandbox-enabled bot bricks the moment it switches to riff.
+    const riffRemoteBackend = !localSandboxApplies(effectiveBackendType);
     if (riffRemoteBackend && (cfg.sandbox === true || cfg.readIsolation === true)) {
-        log('Sandbox/read-isolation flags set but backend is riff (remote sandbox, no local process) — local isolation bypassed');
-    }
-    const wantsFileSandbox = !riffRemoteBackend && (cfg.sandbox === true || sandboxEnabled());
-    // Legacy EXPLICIT read-isolation opt-in (macOS only — Linux read-iso rides the
-    // bwrap sandbox, so it's driven solely by the sandbox toggle there). Keeps
-    // FAIL-CLOSED semantics: you asked for read isolation → refuse to start without it.
-    const explicitLegacyReadIso = process.platform === 'darwin' && cfg.readIsolation === true && !riffRemoteBackend;
-    const readIsolationGate = evaluateReadIsolationGate({
-        configured: wantsFileSandbox || explicitLegacyReadIso,
-        adapterSupports: cliAdapter.supportsReadIsolation === true,
-        wrapperCliSet: !!cfg.wrapperCli,
-        platform: process.platform,
-        sessionDataDirSet: !!process.env.SESSION_DATA_DIR,
-    });
-    // Fail-closed ONLY for the explicit legacy flag. Under the UNIFIED sandbox toggle
-    // read isolation is BEST-EFFORT: a CLI/platform that can't enforce the read-deny
-    // (e.g. a non-supporting adapter) still runs WRITE-isolated — it just doesn't get
-    // the read masks. Never brick a sandboxed session just because read-iso is N/A.
-    if (readIsolationGate.failClosedReason && explicitLegacyReadIso) {
-        throw new Error(`[read-isolation] refusing to start session ${cfg.sessionId}: ${readIsolationGate.failClosedReason}`);
-    }
-    const willReadIsolate = readIsolationGate.enabled;
-    // macOS FILE SANDBOX — the Seatbelt WRITE-isolation twin of the Linux bwrap
-    // overlay. On darwin, `sandbox: true` (or the global sandboxEnabled()) confines
-    // WRITES via the same `sandbox-exec` wrapper as read isolation instead of bwrap
-    // (Linux-only). Reads stay open, matching the Linux "read-all / write-isolated"
-    // model; if read isolation is ALSO on, its read-deny set layers into the SAME
-    // profile. Like bwrap this is FAIL-SAFE: a requested sandbox that can't be
-    // established (unsandboxable backend, no SESSION_DATA_DIR) is a hard error at the
-    // spawn site below, never a silent unconfined run.
-    const willWriteSandbox = process.platform === 'darwin' && wantsFileSandbox;
-    if (willWriteSandbox && !process.env.SESSION_DATA_DIR) {
-        throw new Error(`[file-sandbox] refusing to start session ${cfg.sessionId}: missing SESSION_DATA_DIR`);
-    }
-    const fullIsolationCoversCredentials = !riffRemoteBackend && ((process.platform === 'darwin' && (willReadIsolate || willWriteSandbox))
-        || (process.platform === 'linux' && wantsFileSandbox));
+        log('Sandbox flag set but backend is riff (remote sandbox, no local process) — local sandbox bypassed');
+    }
+    const sandboxRequested = !riffRemoteBackend
+        && (cfg.sandbox === true || cfg.readIsolation === true || sandboxEnabled());
+    const fullIsolationCoversCredentials = sandboxRequested;
     let credentialMechanismAvailable = true;
     let credentialMechanismExecutable;
     if (mandatoryCredentialIsolation && !riffRemoteBackend && !fullIsolationCoversCredentials) {
@@ -6471,16 +6684,11 @@ async function spawnCli(cfg, opts = {}) {
     const credentialOnlySeatbelt = credentialIsolationGate.mode === 'seatbelt';
     const credentialOnlyBwrap = credentialIsolationGate.mode === 'bwrap';
     const appliedIsolationCapabilities = [];
-    if (credentialBoundaryActive
-        || willReadIsolate
-        || (process.platform === 'linux' && wantsFileSandbox)) {
+    if (credentialBoundaryActive || sandboxRequested) {
         appliedIsolationCapabilities.push('credential');
     }
-    if (willReadIsolate)
-        appliedIsolationCapabilities.push('read');
-    if (willWriteSandbox || (process.platform === 'linux' && wantsFileSandbox)) {
-        appliedIsolationCapabilities.push('write');
-    }
+    if (sandboxRequested)
+        appliedIsolationCapabilities.push('read', 'write');
     currentCliCredentialIsolated = appliedIsolationCapabilities.includes('credential');
     const isolationRuntimeDataDir = process.env.SESSION_DATA_DIR
         ?? join(defaultBotmuxHome, 'data');
@@ -6495,8 +6703,7 @@ async function spawnCli(cfg, opts = {}) {
         // 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
+        reuseRecordedHerdrTarget: !sandboxRequested
             && !hasMcpRuntimeEntries,
     });
     let selectedBackend = selectBackend();
@@ -6504,6 +6711,18 @@ async function spawnCli(cfg, opts = {}) {
     isPipeMode = selectedBackend.isPipeMode;
     isZellijMode = selectedBackend.isZellijMode;
     backend = selectedBackend.backend;
+    // BOT_HOME CLI-data redirect: sandboxed bots whose adapter supports it keep
+    // their CLI data (transcripts/memory/auth) in their own BOT_HOME via
+    // CLAUDE_CONFIG_DIR/CODEX_HOME — under deny-by-default the global ~/.claude|
+    // ~/.codex are simply not exposed. Best-effort: a non-supporting adapter
+    // keeps its REAL data dirs instead, which the policy exposes readWrite (the
+    // sandbox itself still applies). Decided EARLY so every JSONL/bridge/resume
+    // path below already targets the right dir. wrapperCli strips spawn args, so
+    // the redirect (and its env) can't be guaranteed there → not redirected.
+    const willRedirectCliData = sandboxRequested
+        && cliAdapter.supportsReadIsolation === true
+        && !cfg.wrapperCli
+        && !!process.env.SESSION_DATA_DIR;
     // 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
@@ -6527,7 +6746,7 @@ async function spawnCli(cfg, opts = {}) {
     }
     let isolationBotHome;
     let isolatedCodexHome;
-    if (willReadIsolate) {
+    if (willRedirectCliData) {
         isolationBotHome = ownBotHome;
         const isClaudeFam = !!claudeDataDir;
         if (isClaudeFam)
@@ -6571,19 +6790,19 @@ async function spawnCli(cfg, opts = {}) {
     // the full in-memory conversation. In that case the resume-vs-fresh question
     // is moot: we must NOT run the pre-flight fallback (which would drop --resume
     // and post a misleading "started a fresh clean session — context lost" card
-    // 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
+    // on EVERY restart, e.g. for a sandboxed session whose transcript lives at a
+    // real host path the probe may not be able to stat). Computed here (not at
     // the spawn site below) so the pre-flight can short-circuit on it.
     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
     // injectable at spawn time, so reattaching such a pane would silently run
-    // unisolated. We stamp a versioned policy marker when we spawn an isolated
-    // pane; if an existing pane was not spawned under the current policy, kill it
-    // so the probe below sees no pane and we cold-spawn fresh isolated. A current-
-    // policy pane survives daemon restarts and suspend→resume safely because the
-    // confinement remains attached to the live process.
+    // unisolated. We stamp a boot-id marker when we spawn an isolated pane; if this
+    // isolated bot's existing pane is NOT stamped by THIS daemon lifetime, kill it
+    // so the probe below sees no pane and we cold-spawn fresh isolated. A pane from
+    // this lifetime (suspend→resume) keeps its marker → reattaches normally (it is
+    // still the isolated process). This lets isolated bots use tmux/zellij/herdr.
     if (appliedIsolationCapabilities.length > 0 && persistentSessionName && effectiveBackendType !== 'pty') {
         const persistentTarget = selectedBackend.persistentBackendTarget;
         const paneLive = persistentTarget
@@ -6648,6 +6867,27 @@ async function spawnCli(cfg, opts = {}) {
             willReattachPersistent = selectedBackend.isReattach === true;
         }
     }
+    const replacementExpectedFresh = codexRunnerFreshness === 'restarting_fresh';
+    const freshness = decideCodexRunnerFreshness({
+        cliId: cfg.cliId,
+        adoptMode: cfg.adoptMode === true,
+        persistentReattach: willReattachPersistent,
+        replacementExpectedFresh,
+        currentBuildId: cfg.runnerBuildId,
+        persistedBuildId: cfg.persistedRunnerBuildId,
+    });
+    codexRunnerFreshness = freshness.state;
+    persistCodexRunnerBuildOnReady = freshness.persistOnReady;
+    log(`Codex runner freshness=${freshness.state} reason=${freshness.reason}`);
+    if (freshness.reason === 'replacement_reattached' && activeRestartAttemptId) {
+        send({
+            type: 'restart_result',
+            attemptId: activeRestartAttemptId,
+            status: 'failed',
+            category: 'spawn_failed',
+        });
+        activeRestartAttemptId = undefined;
+    }
     // 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.
@@ -6671,6 +6911,7 @@ async function spawnCli(cfg, opts = {}) {
     // diagnostic instead of having the prompt typed into it.
     bareShellLaunchBlocked = false;
     bareShellChecked = false;
+    bareShellCheckInProgress = false;
     // ── Resume pre-flight check + two-tier fallback ──────────────────────────
     // Tier 1 (adapter probe): adapter.checkResumeTargetExists returns false
     // → skip --resume, spawn FRESH.
@@ -6708,6 +6949,13 @@ async function spawnCli(cfg, opts = {}) {
             log(`WARN Claude resume transcript sync failed: ${err.message}`);
         }
     }
+    // Hermes stores sessions in a SQLite state.db (not cwd-scoped JSONL). Resolve
+    // the same path the bridge uses — honoring per-bot env, the forced
+    // BOTMUX_SESSION_ID, and the hermes-botmux-session wrapper profile — so the
+    // adapter probe below queries the exact DB Hermes will `--resume` against.
+    const hermesResumeStateDbPath = cfg.cliId === 'hermes'
+        ? resolveHermesStateDbPath({ ...process.env, ...sanitizePerBotEnv(cfg.env), BOTMUX_SESSION_ID: cfg.sessionId }, { botmuxSessionProfile: basename(cfg.cliPathOverride ?? '') === 'hermes-botmux-session' })
+        : undefined;
     const tier2ForceFresh = effectiveResume && consecutiveInWorkerRestarts >= 2;
     let tier1ProbeFalse = false;
     if (effectiveResume && !tier2ForceFresh && !willReattachPersistent) {
@@ -6716,6 +6964,7 @@ async function spawnCli(cfg, opts = {}) {
             cliSessionId: effectiveCliSessionId,
             workingDir: cfg.workingDir,
             dataDir: claudeDataDir,
+            stateDbPath: hermesResumeStateDbPath,
         });
         if (probe === false)
             tier1ProbeFalse = true;
@@ -6835,81 +7084,39 @@ async function spawnCli(cfg, opts = {}) {
     lastSpawnDeferInitialPrompt = deferInitialPrompt;
     kiroSessionIdCaptureArmed = cfg.cliId === 'kiro-cli' && !effectiveCliSessionId && !willReattachPersistent;
     kiroSessionIdCaptureBuffer = '';
-    // Per-bot local read isolation: assemble the Seatbelt profile context (the gate
-    // already fail-closed above — reaching here with willReadIsolate means it is
-    // enforceable). The worker is on the host (NOT sandboxed), so it holds the
-    // secret; only the spawned CLI child is confined. A reattach that reaches here
-    // is safe: the stale-pane guard above already killed any persistent pane not
-    // stamped as isolated, so `willReattachPersistent` can now only be true for a
-    // pane spawned isolated (still the confined process).
-    let readIsolationCtx;
-    if (willReadIsolate) {
-        const sessionDataDir = process.env.SESSION_DATA_DIR;
-        readIsolationCtx = {
-            homeDir: homedir(),
-            botmuxHome: dirname(sessionDataDir),
-            defaultBotmuxHome: join(homedir(), '.botmux'),
-            sessionDataDir,
-            currentAppId: cfg.larkAppId,
-            currentSessionId: cfg.sessionId,
-            extraDenyPaths: cfg.readDenyExtraPaths,
-        };
-        readIsolationOriginCapabilityFile = process.platform === 'darwin'
-            ? managedOriginCapabilityPath(sessionDataDir, cfg.sessionId)
-            : null;
-        // Replace any legacy child-planted symlink before Seatbelt canonicalizes
-        // carve-outs. A failure is fatal: spawning with a missing/ambiguous
-        // capability transport would either break all IPC or reopen an attacker-
-        // selected realpath in the generated profile.
-        if (readIsolationOriginCapabilityFile) {
-            publishSandboxRelayCapability({ failClosed: true });
-        }
-        // Write this bot's OWN send-credential into its BOT_HOME (the same per-bot
-        // private storage as its CLI data; siblings' BOT_HOMEs are whole-denied).
-        // `botmux send` reads the secret from here instead of bots.json — so the
-        // secret never travels via env/argv (no cross-bot `ps aux` leak) and the CLI
-        // never needs to escape the sandbox.
+    // Sandboxed sessions: write this bot's OWN send-credential into its BOT_HOME.
+    // `botmux send` reads the secret from here instead of bots.json (which
+    // deny-by-default never exposes) — the secret never travels via env/argv (no
+    // cross-bot `ps aux` leak) and the CLI never needs to escape the sandbox.
+    // The worker itself runs on the host (NOT sandboxed) and keeps full access.
+    if (sandboxRequested && process.env.SESSION_DATA_DIR) {
         try {
-            const credPath = sendCredFilePath(sessionDataDir, cfg.larkAppId);
+            const credPath = sendCredFilePath(process.env.SESSION_DATA_DIR, cfg.larkAppId);
             mkdirSync(dirname(credPath), { recursive: true });
             writeFileSync(credPath, JSON.stringify({ larkAppId: cfg.larkAppId, larkAppSecret: cfg.larkAppSecret, brand: cfg.brand }), { mode: 0o600 });
         }
         catch (e) {
-            log(`[read-isolation] WARN could not write send-cred file: ${e.message}`);
+            log(`[sandbox] WARN could not write send-cred file: ${e.message}`);
         }
     }
-    // macOS write-sandbox rules (pure): the writable-zone allow-list + crown-jewel
-    // re-denies. Realpath'd + emitted into the Seatbelt profile at the spawn site.
-    let writeSandboxRules;
-    if (willWriteSandbox && process.env.SESSION_DATA_DIR) {
-        const sessionDataDir = process.env.SESSION_DATA_DIR;
-        // Regex rules cannot be realpath'd after construction, so build their home
-        // prefix from the canonical path up front (Seatbelt matches canonical paths).
-        const canonicalSandboxPath = (path) => {
-            try {
-                return realpathSync(path);
-            }
-            catch {
-                return path;
-            }
-        };
-        const sandboxHome = canonicalSandboxPath(homedir());
-        writeSandboxRules = buildWriteSandboxRules({
-            homeDir: sandboxHome,
-            botmuxHome: canonicalSandboxPath(dirname(sessionDataDir)),
-            defaultBotmuxHome: canonicalSandboxPath(join(homedir(), '.botmux')),
-            sessionDataDir: canonicalSandboxPath(sessionDataDir),
-            workingDir: cfg.workingDir,
-            currentAppId: cfg.larkAppId,
-            // TMPDIR on macOS resolves under /private/var/folders (already allowed), but
-            // pass it explicitly so a customized TMPDIR is covered too.
-            extraWritePaths: process.env.TMPDIR ? [process.env.TMPDIR] : [],
-        });
-    }
+    // In the file sandbox, canonicalize the workingDir handed to buildArgs. CLIs
+    // that pass it as a chdir arg (codex/traex `-C`) fail otherwise on a symlinked
+    // $HOME host: the lexical /home/u/... prefix doesn't exist inside the bwrap
+    // root (only canonical /data00/... is bound), so the CLI's chdir/readlink
+    // ENOENTs and it aborts with "No such file or directory (os error 2)". Off
+    // sandbox this is a no-op (same dir); best-effort if unresolvable.
+    const buildArgsWorkingDir = sandboxRequested
+        ? (() => { try {
+            return realpathSync(cfg.workingDir);
+        }
+        catch {
+            return cfg.workingDir;
+        } })()
+        : cfg.workingDir;
     const args = cliAdapter.buildArgs({
         sessionId: effectiveAdapterSessionId,
         resume: effectiveResume,
-        workingDir: cfg.workingDir,
+        workingDir: buildArgsWorkingDir,
         resumeSessionId: effectiveCliSessionId,
         initialPrompt: preparedInitialPrompt,
         botName: cfg.botName,
@@ -6919,12 +7126,7 @@ async function spawnCli(cfg, opts = {}) {
         model: ttadkGateway ? undefined : cfg.model,
         disableCliBypass: cfg.disableCliBypass === true,
         skillPluginDir: cfg.skillPluginDir,
-        readIsolation: willReadIsolate,
-        // Set (as a pair) by the init handler when hybrid RPC input is engaged;
-        // makes buildArgs launch `codex --remote <ws> resume <thread>` instead of
-        // the normal paste-mode codex. Undefined for every other bot/CLI.
-        remoteWsUrl,
-        remoteThreadId,
+        readIsolation: willRedirectCliData,
     });
     // Pi's deferred long-first-prompt command is implemented by a session-scoped
     // extension. Keep its launch args across owned process restarts while the
@@ -7023,15 +7225,18 @@ async function spawnCli(cfg, opts = {}) {
         delete childEnv.BOTMUX_CHAT_TYPE;
     childEnv.BOTMUX_LARK_APP_ID = cfg.larkAppId;
     childEnv.BOTMUX_ROOT_MESSAGE_ID = cfg.rootMessageId;
-    // Session owner under the standard BOTMUX_* name (the riff backend already
-    // exposes it; `__OWNER_OPEN_ID` stays for back-compat). Custom CLI wrappers
-    // use it for per-user permission isolation. Advisory identity only — botmux's
-    // own authz paths (v3 command authority, host.ts) ignore env owner values and
-    // resolve the current-turn caller from turn provenance instead.
-    if (cfg.ownerOpenId)
-        childEnv.BOTMUX_OWNER_OPEN_ID = cfg.ownerOpenId;
-    else
-        delete childEnv.BOTMUX_OWNER_OPEN_ID;
+    // This bot's resolved brandLabel template, injected so a SANDBOXED `botmux
+    // send` renders the role-name footer without reading bots.json (deny-by-
+    // default → EPERM → role footer would silently fall back to the default
+    // [botmux] label). resolveBrandLabel honours this env first (gated on the
+    // own appId). Only set the key when a brandLabel is configured (present-but-
+    // empty '' = suppress is preserved; unset key → the CLI falls through). It is
+    // a cosmetic markdown template, not a credential, so env-passing is safe.
+    {
+        const bl = resolveBrandLabel(cfg.larkAppId);
+        if (typeof bl === 'string')
+            childEnv.BOTMUX_BRAND_LABEL = bl;
+    }
     // NOTE: under read isolation `botmux send` gets this bot's secret from the worker-
     // written cred FILE in its BOT_HOME (send-cred.json, see sendCredFilePath) located
     // via the BOTMUX_LARK_APP_ID above — NOT from the env. The secret is deliberately kept OUT
@@ -7075,10 +7280,27 @@ async function spawnCli(cfg, opts = {}) {
     // already guarantee the pane starts clean, and the CLI's built-in default
     // preserves stock semantics.
     if (isolationBotHome) {
+        // In the file sandbox, bwrap binds only CANONICAL paths (the fs-policy
+        // realpaths every rule). On a symlinked-$HOME host (/home/u → /data00/home/u)
+        // the lexical BOT_HOME (/home/u/.botmux/bots/…/claude) does NOT exist in the
+        // fresh bwrap root, so the CLI can't open its own CLAUDE_CONFIG_DIR/CODEX_HOME
+        // → settings.json (with ANTHROPIC_BASE_URL/token) is unreadable → it falls
+        // back to the public endpoint and fails to connect. Canonicalize so the env
+        // points at the same path bwrap bound. Best-effort: keep lexical if unresolved.
+        const canonicalizeForSandbox = (p) => {
+            if (!sandboxRequested)
+                return p;
+            try {
+                return realpathSync(p);
+            }
+            catch {
+                return p;
+            }
+        };
         if (claudeDataDir)
-            childEnv.CLAUDE_CONFIG_DIR = claudeDataDir; // = <BOT_HOME>/claude
+            childEnv.CLAUDE_CONFIG_DIR = canonicalizeForSandbox(claudeDataDir); // = <BOT_HOME>/claude
         else
-            childEnv.CODEX_HOME = isolatedCodexHome;
+            childEnv.CODEX_HOME = canonicalizeForSandbox(isolatedCodexHome);
     }
     // Per-bot env (bots.json `env`): extra vars for THIS bot's CLI only — e.g.
     // ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN to run a bot on GLM/a 3rd-party
@@ -7108,356 +7330,348 @@ async function spawnCli(cfg, opts = {}) {
     // 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 —
-    // on Linux read isolation is enforced by bwrap masks fed into the overlay sandbox
-    // below (see readIsoLinuxMasks), NOT sandbox-exec (which doesn't exist there).
-    if (process.platform === 'darwin' && (readIsolationCtx || writeSandboxRules)) {
-        // Seatbelt matches CANONICAL paths (it resolves symlinks), so realpath every
-        // deny/allow before emitting the profile — otherwise a sensitive root reached
-        // through a symlinked prefix (e.g. a symlinked home / SESSION_DATA_DIR) would
-        // silently fail-open (the /tmp→/private/tmp class of miss). realpath-if-exists:
-        // a non-existent path has nothing to read, so its literal form is harmless.
-        // The ROOT dirs are canonicalized FIRST (profileCtx) so the regex patterns —
-        // which can't be realpath'd as a result — are built on canonical prefixes too.
+    // ── UNIFIED file sandbox (fs-policy): ONE policy source, BOTH platforms. ──
+    // Three-tier deny-by-default whitelist compiled to Seatbelt (darwin) or bwrap
+    // (linux). Cross-bot read isolation is inherent (siblings' data simply isn't
+    // exposed) — no enumeration, no deny-list to keep in sync.
+    if (sandboxRequested) {
+        const dataDir = process.env.SESSION_DATA_DIR;
+        // FAIL-SAFE (not fail-open): a requested sandbox that can't be established
+        // must be a HARD ERROR, never a silent unconfined run.
+        if (effectiveBackendType !== 'pty' && effectiveBackendType !== 'tmux') {
+            const msg = `Sandbox ENABLED but backend "${effectiveBackendType}" is not sandboxable (only pty/tmux) — aborting spawn to avoid an unsandboxed run`;
+            log(msg);
+            throw new Error(msg);
+        }
+        if (!dataDir) {
+            const msg = 'Sandbox ENABLED but SESSION_DATA_DIR is unset — aborting spawn to avoid an unsandboxed run';
+            log(msg);
+            throw new Error(msg);
+        }
+        // Both engines match CANONICAL paths (Seatbelt resolves symlinks, bwrap
+        // resolves mount sources) — realpath everything, or a symlinked prefix
+        // (the /tmp→/private/tmp class) silently fail-opens.
         const canonical = (p) => { try {
             return realpathSync(p);
         }
         catch {
             return p;
         } };
-        // READ rules — only when read isolation is on. v2 HYBRID model: whole-deny
-        // ~/.claude|~/.codex (F1 fix — own CLI data is redirected into BOT_HOME,
-        // readable) + surgical-deny only the cross-bot-SENSITIVE parts of the otherwise-
-        // readable ~/.botmux + system creds; the own slice is re-opened via carve-outs.
-        // For a WRITE-sandbox-only session these stay empty → reads wide open (Linux parity).
-        let denyPaths = [], denyRegexes = [], allowPaths = [], finalDenyPaths = [], traverseDirs = [];
-        let protectedWrites;
-        if (readIsolationCtx) {
-            const profileCtx = {
-                ...readIsolationCtx,
-                homeDir: canonical(readIsolationCtx.homeDir),
-                botmuxHome: canonical(readIsolationCtx.botmuxHome),
-                defaultBotmuxHome: canonical(readIsolationCtx.defaultBotmuxHome ?? join(readIsolationCtx.homeDir, '.botmux')),
-                sessionDataDir: canonical(readIsolationCtx.sessionDataDir),
-            };
-            denyPaths = buildV2DenyPaths(profileCtx).map(canonical);
-            denyRegexes = buildV2DenyRegexes(profileCtx);
-            const carve = buildV2CarveOuts(profileCtx);
-            const capabilityCarvePath = managedOriginCapabilityPath(profileCtx.sessionDataDir, profileCtx.currentSessionId);
-            allowPaths = [
-                // Never realpath the capability leaf: another legacy sandbox can race
-                // a symlink into that shared host directory while multiple persistent
-                // sessions recover. Keeping the exact path may fail closed on a raced
-                // symlink, but can never turn its target into a Seatbelt allow rule.
-                ...carve.allowPaths.map(path => path === capabilityCarvePath ? path : canonical(path)),
-                ...buildCliExecutableReadCarveOuts({
-                    homeDir: profileCtx.homeDir,
-                    cliId: cliAdapter.id,
-                    resolvedBin: canonical(cliAdapter.resolvedBin),
-                }),
-                // buildV2DenyPaths masks the shared pi-initial-prompts root. Re-open
-                // only this session's private child directory for Pi's @file/extension.
-                ...piInitialPromptReadonlyRoots.map(canonical),
-            ];
-            finalDenyPaths = carve.finalDenyPaths.map(canonical);
-            traverseDirs = carve.traverseDirs.map(canonical);
-            protectedWrites = buildReadIsolationProtectedWriteRules(profileCtx, {
-                // Keep lexical roots as well as their canonical targets. Canonical
-                // rules protect contents reached through a symlink; lexical literals
-                // prevent replacing the symlink/root directory entry itself.
-                dashboardRoots: [
-                    readIsolationCtx.defaultBotmuxHome ?? join(readIsolationCtx.homeDir, '.botmux'),
-                    readIsolationCtx.botmuxHome,
-                ],
-                sessionDataDirs: [readIsolationCtx.sessionDataDir],
-            });
-        }
-        if (credentialBoundaryActive) {
-            const credentialRules = buildCredentialIsolationRules({
-                homeDir: canonical(hostHomeDir),
-                botmuxHome: canonical(configuredBotmuxHome),
-                defaultBotmuxHome: canonical(defaultBotmuxHome),
-            });
-            denyPaths = [...new Set([...denyPaths, ...credentialRules.denyPaths.map(canonical)])];
-            denyRegexes = [...new Set([...denyRegexes, ...credentialRules.denyRegexes])];
-            protectedWrites = {
-                denyWritePaths: [...new Set([
-                        ...(protectedWrites?.denyWritePaths ?? []),
-                        ...credentialRules.denyWritePaths.map(canonical),
-                    ])],
-                denyWriteRegexes: [...new Set([
-                        ...(protectedWrites?.denyWriteRegexes ?? []),
-                        ...credentialRules.denyWriteRegexes,
-                    ])],
-                denyWriteLiterals: [...new Set([
-                        ...(protectedWrites?.denyWriteLiterals ?? []),
-                        ...credentialRules.denyWriteLiterals.map(canonical),
-                        defaultBotmuxHome,
-                        configuredBotmuxHome,
-                    ])],
-            };
-        }
-        if (mcpRuntimeManifest) {
-            finalDenyPaths.push(...sessionMcpRuntimeHostOnlyPaths(mcpRuntimeManifest, config.session.dataDir).map(canonical));
-        }
-        // Every isolated macOS CLI is denied access to all same-UID Gateway socket
-        // directories. A session with its own Gateway gets one narrow, later READ
-        // carve-out for its token; writes stay denied so the CLI cannot unlink or
-        // replace even its own worker-managed socket. Sessions without plugin MCP
-        // state get no read carve-out at all.
-        const gatewaySocketRoot = canonical(sessionMcpGatewayHost ? dirname(sessionMcpGatewayHost.socketDir) : tmpdir());
-        const gatewaySocketRegex = sessionMcpGatewayPathRegex(gatewaySocketRoot);
-        denyRegexes.push(gatewaySocketRegex);
-        if (sessionMcpGatewayHost)
-            allowPaths.push(canonical(sessionMcpGatewayHost.socketDir));
-        protectedWrites = {
-            denyWritePaths: protectedWrites?.denyWritePaths ?? [],
-            denyWriteRegexes: [...(protectedWrites?.denyWriteRegexes ?? []), gatewaySocketRegex],
-            denyWriteLiterals: protectedWrites?.denyWriteLiterals ?? [],
+        const sandboxHome = canonical(homedir());
+        const expandTilde = (raw) => raw.replace(/^~(?=\/|$)/, sandboxHome);
+        const keepExisting = (paths) => {
+            const out = [];
+            for (const raw of paths) {
+                if (!raw || typeof raw !== 'string')
+                    continue;
+                const p = expandTilde(raw);
+                try {
+                    if (existsSync(p))
+                        out.push(canonical(p));
+                }
+                catch { /* */ }
+            }
+            return out;
         };
-        // WRITE rules — the macOS file-sandbox (Linux-bwrap twin). Realpath the writable
-        // zones + crown-jewel re-denies for the same symlink-safety reason as reads.
-        const writeRules = writeSandboxRules
-            ? {
-                allowWritePaths: writeSandboxRules.allowWritePaths.map(canonical),
-                allowWriteRegexes: writeSandboxRules.allowWriteRegexes,
-                denyWritePaths: writeSandboxRules.denyWritePaths.map(canonical),
-                denyWriteRegexes: writeSandboxRules.denyWriteRegexes,
+        // User three-tier lists: the new sandboxPaths field, or a pre-migration
+        // session/config's legacy fields mapped through the SAME lossless mapping
+        // the startup migration uses.
+        const legacyMapped = migrateLegacySandboxFields({
+            sandbox: cfg.sandbox,
+            readIsolation: cfg.readIsolation,
+            sandboxReadonlyPaths: cfg.sandboxReadonlyPaths,
+            sandboxHidePaths: cfg.sandboxHidePaths,
+            readDenyExtraPaths: cfg.readDenyExtraPaths,
+            sandboxPaths: cfg.sandboxPaths,
+        });
+        const userLists = cfg.sandboxPaths ?? legacyMapped?.sandboxPaths;
+        const droppedUser = [];
+        const resolveUser = (paths) => {
+            const out = [];
+            for (const raw of paths ?? []) {
+                if (!raw || typeof raw !== 'string')
+                    continue;
+                const p = expandTilde(raw);
+                if (existsSync(p))
+                    out.push(canonical(p));
+                else
+                    droppedUser.push(raw);
             }
+            return out;
+        };
+        // deny paths are NOT existence-filtered on EITHER platform: a deny must guard
+        // a path that does not exist YET (else the agent creates it under an exposed
+        // rw parent and the deny is bypassed — codex review finding). Seatbelt keeps
+        // the rule literally; bwrap masks it with a tmpfs the mount creates (writes
+        // land in the ephemeral tmpfs, the real path is never created).
+        const resolveDeny = (paths) => (paths ?? []).filter((p) => typeof p === 'string' && !!p).map(p => canonical(expandTilde(p)));
+        const userPaths = {
+            readWrite: resolveUser(userLists?.readWrite),
+            readOnly: resolveUser(userLists?.readOnly),
+            deny: resolveDeny(userLists?.deny),
+        };
+        if (droppedUser.length)
+            log(`[sandbox] sandboxPaths entries dropped (path not found): ${droppedUser.join(', ')}`);
+        // Every executable spawned INSIDE the sandbox must be readable: the CLI
+        // binary's dir, the daemon's own node (fnm farms under /run land here),
+        // adapter second-stage bins, plus the standalone-codex package tree.
+        const execDirs = [cliAdapter.resolvedBin, process.execPath, ...(cliAdapter.sandboxExtraExecPaths?.() ?? [])]
+            .filter((p) => typeof p === 'string' && !!p)
+            .map(p => dirname(canonical(p)));
+        const execCarve = buildCliExecutableReadCarveOuts({
+            homeDir: sandboxHome,
+            cliId: cliAdapter.id,
+            resolvedBin: canonical(cliAdapter.resolvedBin),
+        }).map(canonical);
+        // Linux relay outbox (created by prepareDirectSandbox; in the policy so the
+        // compiled plan binds it read-write).
+        const outbox = process.platform === 'linux'
+            ? join(canonical(dataDir), 'sandboxes', cfg.sessionId, 'outbox')
             : undefined;
-        if (!locateOnPath('sandbox-exec')) {
-            throw new Error(`[file-sandbox] refusing to start session ${cfg.sessionId}: sandbox-exec not found`);
-        }
-        const profileDir = join(isolationRuntimeDataDir, 'read-isolation');
-        mkdirSync(profileDir, { recursive: true });
-        const profilePath = join(profileDir, `${cfg.sessionId}.sb`);
-        replaceManagedOriginCapabilityFile(profilePath, buildSeatbeltProfile(denyPaths, allowPaths, finalDenyPaths, traverseDirs, denyRegexes, writeRules, protectedWrites));
-        seatbeltProfilePath = profilePath;
-        spawnArgs = ['-f', profilePath, spawnBin, ...spawnArgs];
-        spawnBin = credentialMechanismExecutable ?? '/usr/bin/sandbox-exec';
-        log(`[file-sandbox] wrapping ${cliAdapter.id} in Seatbelt (read-isolation=${!!readIsolationCtx}, write-sandbox=${!!writeRules}): sandbox-exec -f ${profilePath}`);
-    }
-    // Fresh sandboxed spawn on a persistent backend: stamp the pane with this daemon's
-    // policy version + boot id so a later suspend→resume reattach can be trusted (see the stale-pane
-    // guard above). Applies to read-isolation AND write-sandbox panes (both carry the
-    // Seatbelt confinement on the live process). pty needs no marker (never reattached).
-    if (appliedIsolationCapabilities.length > 0 && persistentSessionName && !willReattachPersistent) {
+        // Pre-create the outbox BEFORE buildFsPolicy so it survives the allow-rule
+        // existence-filter below (a not-yet-existing readWrite path is dropped, and
+        // bwrap can't bind a missing source → the sandboxed `botmux send` relay
+        // would EPERM/ENOENT writing its <hash>.content into an unbound dir).
+        // prepareDirectSandbox re-mkdirs it too; recursive make is idempotent.
+        if (outbox) {
+            try {
+                mkdirSync(outbox, { recursive: true });
+            }
+            catch { /* best-effort; prepareDirectSandbox retries */ }
+        }
+        // The botmux install/checkout root (dir containing dist/ + node_modules).
+        // This module compiles to <checkout>/dist/worker.js, so `../../` from here is
+        // the checkout root. Exposed readOnly so `botmux` + claude hooks can exec
+        // `node <checkout>/dist/cli.js`.
+        const botmuxInstallRoot = canonical(dirname(dirname(fileURLToPath(import.meta.url))));
+        // Pre-create the OWN writable dirs/files the sandboxed CLI creates on
+        // demand, so they EXIST at spawn and survive the existence-filter below
+        // (bwrap can't bind a nonexistent source; a dropped rule → the CLI's
+        // mkdir/write EPERMs).
+        //  - data/turn-sends/<sessionId>.jsonl: `botmux send` appends its dedup
+        //    marker. The policy grants ONLY this exact file (not the whole dir) so a
+        //    sandboxed CLI can't rewrite another session's marker — pre-create the
+        //    file itself (touch) so the single-file bind has a source.
+        //  - data/attachments/<self>: `botmux quoted`/downloadResources writes here
+        // (BOT_HOME + outbox are created elsewhere.) Best-effort — a failure just
+        // reverts to the pre-existing drop behaviour.
         try {
-            const markerDir = join(isolationRuntimeDataDir, 'read-isolation');
-            mkdirSync(markerDir, { recursive: true });
-            replaceManagedOriginCapabilityFile(join(markerDir, `${cfg.sessionId}.boot`), isolationPaneMarkerContent(cfg.daemonBootId ?? '', appliedIsolationCapabilities));
-        }
-        catch { /* non-fatal: worst case a same-lifetime reattach cold-spawns instead */ }
-    }
-    // Sandbox wraps the spawned binary in bwrap. Works for pty (PtyBackend runs
-    // bwrap directly) and tmux (the tmux pane's command becomes `bwrap … -- cli`);
-    // env is carried via bwrap --setenv (see prepareSandbox), not the backend.
-    // Linux ONLY — on macOS the same `sandbox: true` is enforced by the Seatbelt
-    // write-sandbox above (willWriteSandbox), so bwrap must not run here.
-    //
-    // riff bypass: there is NO local CLI process to wrap — execution happens in
-    // riff's own remote sandbox, and the fail-safe "backend not sandboxable"
-    // hard error below would otherwise brick every sandbox-enabled bot the
-    // moment it switches to riff (the dashboard agent switch clears only
-    // readIsolation, not `sandbox`). Bypassing is safe (nothing local runs);
-    // log it so the state is visible.
-    if (cfg.sandbox === true && effectiveBackendType === 'riff') {
-        log('Sandbox flag set but backend is riff (remote sandbox, no local process) — local file sandbox bypassed');
-    }
-    const sandboxOn = localSandboxApplies(process.platform, effectiveBackendType) && (cfg.sandbox === true || sandboxEnabled());
-    // Linux read isolation: build the bwrap MASK set (the Seatbelt read-deny twin) and
-    // fold it into the SAME overlay sandbox plan below. Enumerate sibling bots from the
-    // FILESYSTEM (the worker runs unsandboxed on the host; bots.json may be denied) —
-    // spawn-time-static, so a bot added after this spawn is covered on its next cold
-    // start (the accepted Linux tradeoff vs the macOS regex). Only when read isolation
-    // is enforceable here (willReadIsolate ⇒ readIsolationCtx set) AND on Linux.
-    let readIsoLinuxMasks;
-    if (readIsolationCtx && process.platform === 'linux') {
-        const canon = (p) => { try {
-            return realpathSync(p);
+            const tsDir = join(dataDir, 'turn-sends');
+            mkdirSync(tsDir, { recursive: true });
+            const tsFile = join(tsDir, `${cfg.sessionId}.jsonl`);
+            if (!existsSync(tsFile))
+                writeFileSync(tsFile, '');
         }
-        catch {
-            return p;
-        } };
-        // Canonicalize the root prefixes FIRST so every derived mask path is symlink-safe
-        // (bwrap masks resolve symlinks — a symlinked home/data root would else fail-open).
-        const ctxReal = {
-            ...readIsolationCtx,
-            homeDir: canon(readIsolationCtx.homeDir),
-            botmuxHome: canon(readIsolationCtx.botmuxHome),
-            defaultBotmuxHome: canon(readIsolationCtx.defaultBotmuxHome ?? join(readIsolationCtx.homeDir, '.botmux')),
-            sessionDataDir: canon(readIsolationCtx.sessionDataDir),
-        };
-        const ids = new Set();
-        const scan = (dir, pick) => {
-            try {
-                for (const name of readdirSync(dir)) {
-                    const id = pick(name);
-                    if (id)
-                        ids.add(id);
-                }
-            }
-            catch { /* dir absent → no siblings there */ }
-        };
-        scan(join(ctxReal.botmuxHome, 'bots'), n => n); // sibling BOT_HOME dirs
-        scan(join(ctxReal.homeDir, '.lark-cli-bots'), n => n); // sibling lark configs
-        scan(ctxReal.sessionDataDir, n => { const m = /^sessions-(.+)\.json$/.exec(n); return m ? m[1] : null; });
-        ids.delete(cfg.larkAppId); // never mask own
-        let sidecars = [];
+        catch { /* */ }
         try {
-            sidecars = readdirSync(ctxReal.botmuxHome).filter(n => n.startsWith('bots.json.')).map(n => join(ctxReal.botmuxHome, n));
+            mkdirSync(join(dataDir, 'attachments', cfg.larkAppId), { recursive: true });
         }
         catch { /* */ }
-        const m = buildLinuxReadIsolationMasks({ ctx: ctxReal, siblingAppIds: [...ids], botsJsonSidecars: sidecars });
-        // Same execvp carve-out as macOS (Codex 342a3e1c): a standalone Codex whose
-        // binary lives UNDER the now-masked ~/.codex would fail execvp. Re-expose ONLY
-        // its executable package tree (read-only, after the masks) — auth/config/sessions
-        // stay masked. No-op for npm/system installs (binary not under ~/.codex) + non-codex.
-        const execCarveOuts = buildCliExecutableReadCarveOuts({
-            homeDir: ctxReal.homeDir,
-            cliId: cliAdapter.id,
-            resolvedBin: canon(cliAdapter.resolvedBin),
-        }).map(canon);
-        readIsoLinuxMasks = {
-            hidePaths: m.hidePaths.map(canon),
-            ownReadWritePaths: m.ownReadWritePaths.map(canon),
-            ownReadOnlyPaths: [...m.ownReadOnlyPaths.map(canon), ...execCarveOuts],
-        };
-        log(`[read-isolation] linux bwrap masks: ${m.hidePaths.length} hide, ${[...ids].length} siblings enumerated${execCarveOuts.length ? ', +codex-standalone exec carve' : ''}`);
-    }
-    if (sandboxOn) {
-        // FAIL-SAFE (not fail-open): when the sandbox is requested, a missing
-        // precondition (no SESSION_DATA_DIR, or a backend we can't wrap) must be a
-        // HARD ERROR, never a silent skip — otherwise the CLI would spawn UNSANDBOXED
-        // with full host write access and no log, the exact opposite of the
-        // oncall-untrusted-agent invariant. In normal operation worker-pool sets
-        // SESSION_DATA_DIR and the backend is pty/tmux, so this never trips.
-        const dataDir = process.env.SESSION_DATA_DIR;
-        if (effectiveBackendType !== 'pty' && effectiveBackendType !== 'tmux') {
-            const msg = `Sandbox ENABLED but backend "${effectiveBackendType}" is not sandboxable (only pty/tmux) — aborting spawn to avoid an unsandboxed run`;
-            log(msg);
-            throw new Error(msg);
+        // (Schedules moved into each bot's BOT_HOME — the whole dir is already
+        // bound readWrite for the owner, so no per-file pre-create is needed.)
+        const mandatoryDenyPaths = [];
+        const mandatoryDenyRegexes = [];
+        const mandatoryReadOnlyPaths = [];
+        // Linux: the per-session sandbox tree (`sandboxes/<sid>`) holds the deny-mask
+        // cleanup manifest + the mode-000 empty ro-bind SOURCES. If SESSION_DATA_DIR
+        // is configured INSIDE the working dir (a custom data dir under a RW-bound
+        // project), the project's readWrite rule would otherwise cover the whole
+        // tree and let the sandboxed CLI tamper with the manifest (→ trick teardown
+        // into deleting arbitrary host paths) or the empty sources. Deny the tree
+        // as a MANDATORY rule (user paths can't override); the outbox is re-granted
+        // readWrite via ctx.outbox as a deeper carve-out (the compiler masks the
+        // tree with a tmpfs that hosts the nested outbox bind, then remounts it RO —
+        // manifest/empties stay unreadable AND unwritable in-sandbox). bwrap reads
+        // ro-bind SOURCES from the host FS, so the empty masks still work even though
+        // the child can't see them.
+        if (process.platform === 'linux') {
+            mandatoryDenyPaths.push(join(canonical(dataDir), 'sandboxes', cfg.sessionId));
         }
-        if (!dataDir) {
-            const msg = 'Sandbox ENABLED but SESSION_DATA_DIR is unset — aborting spawn to avoid an unsandboxed run';
-            log(msg);
-            throw new Error(msg);
+        readIsolationOriginCapabilityFile = process.platform === 'darwin'
+            ? managedOriginCapabilityPath(dataDir, cfg.sessionId)
+            : null;
+        // The macOS child reads the per-session rotating capability directly.
+        // Materialize it before the policy's existence filter, and make the exact
+        // file a mandatory read-only carve-out that user rules cannot shadow.
+        if (readIsolationOriginCapabilityFile) {
+            publishSandboxRelayCapability({ failClosed: true });
+            mandatoryReadOnlyPaths.push(readIsolationOriginCapabilityFile);
         }
-        try {
-            if (willReattachPersistent) {
-                // Daemon-restart reattach to a persistent (tmux/herdr/zellij) pane whose
-                // bwrap'd CLI is STILL ALIVE. backend.spawn() ignores bin/args here and
-                // just re-attaches, and the live CLI is bound to its own namespace-pinned
-                // overlay — so we must NOT unmount/remount (prepareSandbox would leave a
-                // duplicate host-side overlay the CLI isn't using). We only re-wire the
-                // outbox watcher (so the live CLI's `botmux send` keeps being serviced)
-                // and the cleanup ref (so close/exit reclaims the residue). No re-prep.
-                const att = attachSandboxOutbox({ sessionId: cfg.sessionId, dataDir });
-                if (att) {
-                    if (sandboxStopWatcher) {
-                        try {
-                            sandboxStopWatcher();
-                        }
-                        catch { /* */ }
-                    }
-                    if (sandboxCleanup) {
-                        try {
-                            sandboxCleanup();
+        if (credentialBoundaryActive) {
+            const credentialRules = buildCredentialIsolationRules({
+                homeDir: sandboxHome,
+                botmuxHome: canonical(configuredBotmuxHome),
+                defaultBotmuxHome: canonical(defaultBotmuxHome),
+            });
+            mandatoryDenyPaths.push(...credentialRules.denyPaths.map(canonical));
+            mandatoryDenyRegexes.push(...credentialRules.denyRegexes);
+            // Materialize every existing atomic sidecar as a concrete Linux mask.
+            // Seatbelt additionally keeps the regexes above for files created later.
+            for (const root of [...new Set([defaultBotmuxHome, configuredBotmuxHome])]) {
+                try {
+                    for (const name of readdirSync(root)) {
+                        if (isCredentialIsolationReservedBasename(name)) {
+                            mandatoryDenyPaths.push(canonical(join(root, name)));
                         }
-                        catch { /* */ }
                     }
-                    sandboxCleanup = att.cleanup;
-                    sandboxRelayOutbox = att.outbox;
-                    sandboxStopWatcher = startOutboxWatcher(att.outbox, childEnv, cfg.sessionId, { authorize: authorizeManagedSend });
-                    publishSandboxRelayCapability();
-                    log(`Sandbox REATTACH (${cfg.cliId}): live pane CLI kept, re-wired outbox=${att.outbox} (no remount)`);
                 }
-                else {
-                    // No sandbox tree on disk for a session we're reattaching to: the
-                    // pane's CLI may be unsandboxed (sandbox enabled after it spawned). Do
-                    // NOT remount under a live CLI; just continue the reattach as-is.
-                    log(`Sandbox REATTACH (${cfg.cliId}): no on-disk sandbox tree — reattaching live pane without re-prep`);
+                catch { /* absent authority root */ }
+            }
+        }
+        if (mcpRuntimeManifest) {
+            mandatoryDenyPaths.push(...sessionMcpRuntimeHostOnlyPaths(mcpRuntimeManifest, config.session.dataDir).map(canonical));
+        }
+        if (process.platform === 'darwin') {
+            const gatewaySocketRoot = canonical(sessionMcpGatewayHost ? dirname(sessionMcpGatewayHost.socketDir) : tmpdir());
+            mandatoryDenyRegexes.push(sessionMcpGatewayPathRegex(gatewaySocketRoot));
+            if (sessionMcpGatewayHost) {
+                mandatoryReadOnlyPaths.push(canonical(sessionMcpGatewayHost.socketDir));
+            }
+        }
+        const policy = buildFsPolicy({
+            platform: process.platform,
+            homeDir: sandboxHome,
+            botmuxHome: canonical(dirname(dataDir)),
+            sessionDataDir: canonical(dataDir),
+            workingDir: canonical(cfg.workingDir),
+            currentAppId: cfg.larkAppId,
+            sessionId: cfg.sessionId,
+            botHome: canonical(ownBotHome),
+            redirectedCliData: willRedirectCliData,
+            cliDataPaths: willRedirectCliData ? undefined : keepExisting([
+                cliAdapter.claudeDataDir,
+                claudeDataDir ? `${sandboxHome}/.claude.json` : undefined,
+                claudeDataDir ? `${sandboxHome}/.claude.json.lock` : undefined,
+                claudeDataDir ? `${sandboxHome}/.claude.lock` : undefined,
+                claudeDataDir ? `${sandboxHome}/.local/state/claude` : undefined,
+            ]),
+            authPaths: keepExisting([...(cliAdapter.authPaths ?? [])]),
+            execPaths: keepExisting([...execDirs, ...execCarve]),
+            readonlyRoots: keepExisting([
+                ...(cfg.skillReadonlyRoots ?? []),
+                ...piInitialPromptReadonlyRoots,
+            ]),
+            botmuxInstallRoot,
+            outbox,
+            extraWritePaths: keepExisting([process.env.TMPDIR]),
+            userPaths,
+            mandatoryDenyPaths,
+            mandatoryDenyRegexes,
+            mandatoryReadOnlyPaths,
+            net: cfg.sandboxNetwork !== false,
+            // Claude Code saves ~/.claude.json atomically via a PID/random-suffixed
+            // sibling — only relevant when the data dir is NOT redirected to BOT_HOME.
+            writeRegexes: process.platform === 'darwin' && !willRedirectCliData && claudeDataDir
+                ? [`^${sandboxHome.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/\\.claude\\.json\\.tmp\\.[^/]+$`]
+                : [],
+        });
+        // Existence-filter only the ALLOW rules (baseline entries are candidates,
+        // not guarantees): a non-existent allow path has nothing to expose, and
+        // bwrap cannot bind a non-existent SOURCE. DENY rules are kept regardless —
+        // they must guard a path created later in the session (Seatbelt keeps the
+        // literal rule; bwrap masks with a tmpfs whose mountpoint the mount creates).
+        policy.rules = policy.rules.filter(r => {
+            if (r.access === 'deny')
+                return true;
+            try {
+                return existsSync(r.path);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (process.platform === 'darwin') {
+            if (!locateOnPath('sandbox-exec')) {
+                throw new Error(`[file-sandbox] refusing to start session ${cfg.sessionId}: sandbox-exec not found`);
+            }
+            const profileDir = join(dataDir, 'read-isolation');
+            mkdirSync(profileDir, { recursive: true });
+            const profilePath = join(profileDir, `${cfg.sessionId}.sb`);
+            writeFileSync(profilePath, compileToSeatbelt(policy), { mode: 0o600 });
+            seatbeltProfilePath = profilePath;
+            spawnArgs = ['-f', profilePath, spawnBin, ...spawnArgs];
+            spawnBin = 'sandbox-exec';
+            log(`[file-sandbox] wrapping ${cliAdapter.id} in Seatbelt (fs-policy, ${policy.rules.length} rules): sandbox-exec -f ${profilePath}`);
+        }
+        else if (willReattachPersistent) {
+            // Daemon-restart reattach to a live bwrap'd pane: backend.spawn() ignores
+            // bin/args and just re-attaches. Only re-wire the outbox watcher (so the
+            // live CLI's `botmux send` keeps being serviced) + the cleanup ref. The
+            // direct model has NO mounts — cleanup is a plain rm at close/exit.
+            const att = attachSandboxOutbox({ sessionId: cfg.sessionId, dataDir });
+            if (att) {
+                if (sandboxStopWatcher) {
+                    try {
+                        sandboxStopWatcher();
+                    }
+                    catch { /* */ }
                 }
+                sandboxCleanup = att.cleanup;
+                sandboxRelayOutbox = att.outbox;
+                sandboxStopWatcher = startOutboxWatcher(att.outbox, childEnv, cfg.sessionId, { authorize: authorizeManagedSend });
+                publishSandboxRelayCapability();
+                log(`Sandbox REATTACH (${cfg.cliId}): live pane CLI kept, re-wired outbox=${att.outbox}`);
             }
             else {
-                const sbx = prepareSandbox({
-                    enabled: sandboxOn,
-                    cliId: cfg.cliId,
-                    sessionId: cfg.sessionId,
-                    sourceWorkingDir: cfg.workingDir,
-                    dataDir,
-                    cliBin: cliAdapter.resolvedBin,
-                    cliArgs: args,
-                    // Read-isolation masks (Linux) fold into the same plan: hide the cross-bot
-                    // sensitive set, keep the own BOT_HOME real+writable (authPaths), and re-
-                    // expose the own attachments bucket read-only after the masks (readonlyRoots).
-                    hidePaths: [...(cfg.sandboxHidePaths ?? []), ...(readIsoLinuxMasks?.hidePaths ?? [])],
-                    authPaths: [...(cliAdapter.authPaths ?? [])],
-                    // BOTMUX_HOME is credential-masked wholesale. Re-open only this
-                    // bot's daemon-derived private CLI home after that parent mask, then
-                    // re-mask its send credential so an untrusted receiver cannot bypass
-                    // the host-authorized relay with a direct Lark API call.
-                    trustedWritablePaths: readIsoLinuxMasks?.ownReadWritePaths ?? [],
-                    finalHidePaths: readIsoLinuxMasks
-                        ? [sendCredFilePath(dataDir, cfg.larkAppId)]
-                        : [],
-                    extraExecPaths: cliAdapter.sandboxExtraExecPaths?.(),
-                    readonlyRoots: [
-                        ...(cfg.skillReadonlyRoots ?? []),
-                        ...piInitialPromptReadonlyRoots,
-                        ...(readIsoLinuxMasks?.ownReadOnlyPaths ?? []),
-                    ],
-                    mcpGatewaySocketPath: sessionMcpGatewayHost?.socketPath,
-                    trustedBotmuxCommandPaths: [defaultGatewayEntry().command],
-                    userReadonlyPaths: cfg.sandboxReadonlyPaths ?? [],
-                    net: cfg.sandboxNetwork !== false,
-                });
-                if (sbx) {
-                    spawnBin = sbx.bin;
-                    spawnArgs = sbx.args;
-                    // In the overlay model the child still chdirs to projectMount (via bwrap
-                    // --chdir), so spawnCwd stays the real workingDir; the overlay merged dir
-                    // is bound there. sbx.workDir is the UPPER changeset (for landing), NOT a cwd.
-                    Object.assign(childEnv, sbx.env);
-                    if (sandboxStopWatcher) {
-                        try {
-                            sandboxStopWatcher();
-                        }
-                        catch { /* */ }
-                    }
-                    if (sandboxCleanup) {
-                        try {
-                            sandboxCleanup();
-                        }
-                        catch { /* */ }
-                    }
-                    sandboxCleanup = sbx.cleanup;
-                    sandboxRelayOutbox = sbx.outbox;
-                    // session-id is FORCED here so a relayed send can't target another session.
-                    sandboxStopWatcher = startOutboxWatcher(sbx.outbox, childEnv, cfg.sessionId, { authorize: authorizeManagedSend });
-                    publishSandboxRelayCapability();
-                    log(`Sandbox ON (${cfg.cliId}): upper=${sbx.workDir} outbox=${sbx.outbox}`);
+                log(`Sandbox REATTACH (${cfg.cliId}): no on-disk sandbox tree — reattaching live pane as-is`);
+            }
+        }
+        else {
+            const sbx = prepareDirectSandbox({
+                sessionId: cfg.sessionId,
+                dataDir,
+                policy,
+                chdir: canonical(cfg.workingDir),
+                home: sandboxHome,
+                cliBin: cliAdapter.resolvedBin,
+                cliArgs: args,
+                trustedBotmuxCommandPaths: [defaultGatewayEntry().command],
+                mcpGatewaySocketPath: sessionMcpGatewayHost?.socketPath,
+            });
+            if (!sbx) {
+                // FAIL-SAFE: never silently run unsandboxed.
+                const msg = 'sandbox requested but could not be established (bwrap missing or setup failed) — aborting spawn';
+                log(msg);
+                throw new Error(msg);
+            }
+            spawnBin = sbx.bin;
+            spawnArgs = sbx.args;
+            Object.assign(childEnv, sbx.env);
+            if (sandboxStopWatcher) {
+                try {
+                    sandboxStopWatcher();
                 }
-                else {
-                    // Sandbox was requested but prepareSandbox returned null (a required
-                    // overlay mount failed, or non-Linux). Fail safe: do NOT silently run
-                    // unsandboxed — surface a hard error so the session doesn't leak.
-                    log(`Sandbox ENABLED but prepare returned null (mount failed / unsupported) — aborting spawn to avoid an unsandboxed run`);
-                    throw new Error('sandbox requested but could not be established');
+                catch { /* */ }
+            }
+            if (sandboxCleanup) {
+                try {
+                    sandboxCleanup();
                 }
+                catch { /* */ }
             }
+            sandboxCleanup = sbx.cleanup;
+            sandboxRelayOutbox = sbx.outbox;
+            // session-id is FORCED here so a relayed send can't target another session.
+            sandboxStopWatcher = startOutboxWatcher(sbx.outbox, childEnv, cfg.sessionId, { authorize: authorizeManagedSend });
+            publishSandboxRelayCapability();
+            log(`Sandbox ON (${cfg.cliId}, fs-policy ${policy.rules.length} rules): outbox=${sbx.outbox}`);
         }
-        catch (err) {
-            log(`Sandbox prepare failed (${err.message}) — aborting (sandbox is a hard requirement when enabled)`);
-            throw err;
+    }
+    // Fresh sandboxed spawn on a persistent backend: stamp the pane with this
+    // daemon's boot id so a later reattach can be trusted (see the stale-pane
+    // guard above). pty needs no marker (never reattached).
+    if (appliedIsolationCapabilities.length > 0 && persistentSessionName && !willReattachPersistent) {
+        try {
+            const markerDir = join(isolationRuntimeDataDir, 'read-isolation');
+            mkdirSync(markerDir, { recursive: true });
+            writeFileSync(join(markerDir, `${cfg.sessionId}.boot`), isolationPaneMarkerContent(cfg.daemonBootId ?? '', appliedIsolationCapabilities), { mode: 0o600 });
         }
+        catch { /* non-fatal: worst case a same-lifetime reattach cold-spawns instead */ }
     }
     // 通用启动前缀（wrapperCli）：把启动命令重写成 `<wrapperCli> <CLI 参数>`（首 token 当
     // bin 走 PATH 解析），无需 wrapper 脚本、跨系统。aiden x claude 形态会剥掉 aiden 拒收的
     // --settings（见 buildWrappedLaunch）。与文件沙盒互斥：沙盒已把命令重写成 bwrap，叠加
-    // 前缀会破坏隔离，故 sandboxOn 时跳过并告警（网关 + oncall 沙盒本就不是合理组合）。
+    // 前缀会破坏隔离，故沙盒开启时跳过并告警（网关 + oncall 沙盒本就不是合理组合）。
     // CJADK_INTERACTIVE is a cjadk-only knob we set on the cjadk wrapper branch
     // below. Strip any value inherited from the daemon's own env first so a
     // daemon launched under `cjadk feishu` (which exports it) can't leak it via
@@ -7466,8 +7680,8 @@ async function spawnCli(cfg, opts = {}) {
     // keeps the behaviour intentional rather than ambient. (Codex review note.)
     delete childEnv.CJADK_INTERACTIVE;
     if (cfg.wrapperCli && cfg.wrapperCli.trim()) {
-        if (sandboxOn) {
-            log(`wrapperCli="${cfg.wrapperCli}" ignored: file sandbox enabled and takes precedence (cannot combine launch prefix with bwrap)`);
+        if (sandboxRequested) {
+            log(`wrapperCli="${cfg.wrapperCli}" ignored: file sandbox enabled and takes precedence (cannot combine launch prefix with the sandbox wrapper)`);
         }
         else {
             const launch = buildWrappedLaunch(cfg.wrapperCli, spawnArgs, (b) => locateOnPath(b) ?? b, {
@@ -7660,7 +7874,7 @@ async function spawnCli(cfg, opts = {}) {
             baseBin: reproduceBaseBin,
             baseArgs: reproduceBaseArgs,
             wrapperCli: cfg.wrapperCli,
-            sandboxOn,
+            sandboxOn: sandboxRequested,
             binResolver: (b) => locateOnPath(b) ?? b,
             ttadkModel: cfg.model,
         });
@@ -7726,7 +7940,7 @@ async function spawnCli(cfg, opts = {}) {
     // MARKER inference is unaffected (the launcher-pid marker is still a valid
     // ancestor of an in-CLI `botmux send`, and the env fallback covers it too).
     const startWrapperRealPidResolve = (launcherPid) => {
-        if (!cfg.wrapperCli || !cfg.wrapperCli.trim() || sandboxOn || !claudeDataDir)
+        if (!cfg.wrapperCli || !cfg.wrapperCli.trim() || sandboxRequested || !claudeDataDir)
             return;
         const targetCliId = cfg.cliId;
         scheduleWrapperRealCliPid(launcherPid, {
@@ -7948,7 +8162,7 @@ async function spawnCli(cfg, opts = {}) {
     const readyHookAvailable = effectiveReadyHookInstall
         ? hasInstalledSessionReadyHook(effectiveReadyHookInstall)
         : true; // Hermes emits BOTMUX_READY_COMMAND directly instead of a config hook.
-    const isolatedReadyTransportRequired = sandboxOn || willReadIsolate;
+    const isolatedReadyTransportRequired = sandboxRequested || credentialBoundaryActive;
     const readyPortAvailable = !isolatedReadyTransportRequired
         || parseDaemonIpcPort(childEnv.BOTMUX_DAEMON_IPC_PORT) !== undefined;
     const readyCapabilityAvailable = !isolatedReadyTransportRequired
@@ -8045,6 +8259,16 @@ async function spawnCli(cfg, opts = {}) {
     // prompt-ready — without this hook a follow-up arriving mid-task would sit
     // in pendingMessages forever once the task finishes.
     backend.onTaskDone?.(() => {
+        // Generation fence (matches the onAgentStatus above and the onExit below):
+        // a stale RiffBackend's `fetchAndEmitOutput(...).finally(taskDoneCb)` can
+        // resolve AFTER destroySession()/kill() during a restart (neither clears
+        // taskDoneCb nor awaits the in-flight fetch). If that late callback reached
+        // markPromptReady() while a replacement is spawning, it would ride through
+        // the global restart gate and emit a premature `restart_result: succeeded`,
+        // swallowing the replacement's true terminal outcome. Only the current
+        // backend generation may re-arm prompt-ready.
+        if (backend !== observedBackend)
+            return;
         log(`${cliName()} task finished — re-arming prompt-ready for queued follow-ups`);
         markPromptReady();
     });
@@ -8083,22 +8307,7 @@ async function spawnCli(cfg, opts = {}) {
             // before exiting while fs.watch/the 1s poller is still queued. Drain it
             // synchronously before claiming `cli_exit`; otherwise ambiguous wins the
             // deduper and needlessly replays a turn that actually completed.
-            if (bridgeJsonlPath) {
-                try {
-                    bridgeDrainAndMaybeEmit();
-                }
-                catch (err) {
-                    log(`Bridge exit drain failed: ${err.message}`);
-                }
-            }
-            if (codexBridgeFallbackActive()) {
-                try {
-                    codexBridgeDrainAndMaybeEmit({ signalIdle: false });
-                }
-                catch (err) {
-                    log(`Codex bridge exit drain failed: ${err.message}`);
-                }
-            }
+            drainReliableTerminalBeforeInterrupt();
             // Race-safe with transcript final / submit-failure: the worker-local
             // terminal deduper lets exactly one status win for this attempt.
             emitTurnTerminal(exitedTurnId, 'ambiguous', 'cli_exit', exitedDispatchAttempt);
@@ -8140,6 +8349,17 @@ async function spawnCli(cfg, opts = {}) {
         isPromptReady = false;
         currentBotmuxTurnId = undefined;
         currentBotmuxDispatchAttempt = undefined;
+        if (!intentionalRestart && activeRestartAttemptId) {
+            send({
+                type: 'restart_result',
+                attemptId: activeRestartAttemptId,
+                status: 'failed',
+                category: 'runner_exited',
+            });
+            activeRestartAttemptId = undefined;
+        }
+        if (!intentionalRestart)
+            freshnessInputQueue.onReplacementFailed();
         if (intentionalRestart) {
             log('Suppressed claude_exit for intentional in-worker restart');
         }
@@ -8242,8 +8462,8 @@ function killCli(opts = {}) {
     promptReadyDetectedDuringSettle = false;
     readyPatternSeenDuringHold = false;
     awaitingPostSessionStartPromptEvidence = false;
-    stopScreenAnalyzer();
     stopStuckDetector();
+    tuiPromptBlocking = false;
     stopScreenUpdates();
     backend?.kill();
     backend = null;
@@ -8261,10 +8481,10 @@ function killCli(opts = {}) {
         cliPidMarker = null;
     }
     completeManagedTurnOriginRevocation(sandboxRelayCapability, currentBotmuxTurnId, currentBotmuxDispatchAttempt);
-    // Stop the sandbox outbox watcher, then unmount the overlays + remove the
-    // per-session sandbox tree. In the overlay model the upper layer (the
-    // changeset) must be landed BEFORE close — `/land` runs while the session is
-    // still active, so by cleanup time anything worth keeping is already applied.
+    // Stop the sandbox outbox watcher, then reclaim the deny-mask mountpoints +
+    // remove the per-session sandbox tree. In the fs-policy model the CLI writes
+    // the project DIRECTLY at real host paths (no upper changeset to land), so by
+    // close time everything worth keeping is already on disk.
     if (sandboxStopWatcher) {
         try {
             sandboxStopWatcher();
@@ -8277,6 +8497,9 @@ function killCli(opts = {}) {
     currentBotmuxTurnId = undefined;
     currentBotmuxDispatchAttempt = undefined;
     currentVcMeetingImTurnOrigin = undefined;
+    submittedCodexAppReplyTurnIds.clear();
+    pendingCodexAppSteerAckIds.clear();
+    acknowledgedCodexAppSteers.clear();
     if (sandboxCleanup) {
         try {
             sandboxCleanup();
@@ -8316,6 +8539,7 @@ async function restartCliProcess(reason, opts = {}) {
     // of firing idle/task-done callbacks. Inputs accepted in that interval must
     // remain queued until a replacement backend has been installed.
     cliRestartInProgress = true;
+    replacementSpawnInProgress = false;
     rawInputRestartGate = true;
     // The Node worker stays alive through this restart, so the daemon will see
     // neither claude_exit nor worker-exit. Explicitly revoke the old turn's
@@ -8325,9 +8549,13 @@ async function restartCliProcess(reason, opts = {}) {
     revokeManagedTurnOriginForRestart();
     log(`Restart requested (${reason})`);
     // Tier-2 guard: 2nd consecutive in-worker restart forces FRESH. Tier-1
-    // adapter probing is still re-run on every spawn.
-    consecutiveInWorkerRestarts++;
-    log(`Restart count: ${consecutiveInWorkerRestarts} (>=2 forces FRESH)`);
+    // adapter probing is still re-run on every spawn. skipRestartBudget（角色
+    // 切换的 cwd-move respawn）不计入：那是用户主动迁移不是崩溃恢复，计进去
+    // 会让「切角色 + 一次无关重启」无故触发强制 FRESH 丢上下文。
+    if (!opts.skipRestartBudget) {
+        consecutiveInWorkerRestarts++;
+        log(`Restart count: ${consecutiveInWorkerRestarts} (>=2 forces FRESH)`);
+    }
     const restart = async () => {
         try {
             tmuxRestartTimer = null;
@@ -8357,12 +8585,13 @@ async function restartCliProcess(reason, opts = {}) {
             killCli({ preservePending: opts.preservePending });
             awaitingFirstPrompt = true;
             setTimeout(async () => {
+                let spawnedWorkingDir;
                 if (lastInitConfig) {
                     startScreenUpdates();
-                    startScreenAnalyzer();
                     startStuckDetector();
                     try {
                         const restartCfg = { ...lastInitConfig, resume: true, prompt: '', cliSessionId: rpcThreadId ?? lastInitConfig.cliSessionId };
+                        spawnedWorkingDir = restartCfg.workingDir;
                         // Re-engage RPC so the new --remote pane binds to the CURRENT app-server
                         // (a fresh port), not the dead prior one. engageCodexRpc only sets
                         // remote* on success, else spawnCli falls back to paste.
@@ -8373,27 +8602,64 @@ async function restartCliProcess(reason, opts = {}) {
                             rpcPluginGenerationPrepared = true;
                             await engageCodexRpc(restartCfg);
                         }
+                        replacementSpawnInProgress = true;
                         await spawnCli(restartCfg, { pluginGenerationPrepared: rpcPluginGenerationPrepared });
                         await prepareCodexNativeTitleGeneration(restartCfg, codexRpcEngine);
+                        replacementSpawnInProgress = false;
                         if (codexRpcEngine)
                             armRpcStartupDialogDismiss();
                     }
                     catch (err) {
+                        replacementSpawnInProgress = false;
                         cliRestartInProgress = false;
                         await sendFatalWorkerErrorAndExit(err);
                         return;
                     }
                 }
                 cliRestartInProgress = false;
+                replacementSpawnInProgress = false;
+                // Follow-up decision (pure, unit-tested in restart-followup-policy.ts):
+                //  - cwd-move: a role-switch restart landed after restartCfg was
+                //    snapshotted → CLI came up in the old cwd while daemon repinned to
+                //    the new one. Respawn to converge (budget skipped only if the
+                //    backend is still alive; a dead one keeps the crash evidence).
+                //  - replacement-recovery: the freshly-spawned CLI exited inside the
+                //    window cliRestartInProgress still covers (spawnCli +
+                //    prepareCodexNativeTitleGeneration). onExit nulled `backend`
+                //    synchronously, so `!backend` is the ground-truth recovery signal —
+                //    NOT a merged daemon auto-restart (a restart message carries no
+                //    trustworthy source, so a healthy duplicate /restart during the
+                //    window must NOT be misread as a crash and force a budget-burning
+                //    second restart). Recover now or the session strands at
+                //    backend=null needing a manual /restart. Genuine crash recovery →
+                //    COUNTS toward tier-2 FRESH.
+                const followup = decideRestartFollowup({
+                    spawnedWorkingDir,
+                    currentWorkingDir: lastInitConfig?.workingDir,
+                    backendAlive: !!backend,
+                });
+                if (followup.kind !== 'none') {
+                    const reason = followup.kind === 'cwd-move'
+                        ? `cwd-move follow-up respawn → ${lastInitConfig?.workingDir}`
+                        : 'replacement-exit follow-up restart (replacement exited during in-flight restart)';
+                    log(reason);
+                    void restartCliProcess(reason, { preservePending: true, skipRestartBudget: followup.skipRestartBudget });
+                    return;
+                }
                 // Riff marks itself prompt-ready inside spawnCli(); that early flush is
                 // intentionally held by the restart gate above. Release its raw-input
                 // fence now; other backends keep it until their later markPromptReady().
                 if (effectiveBackendType === 'riff' && isPromptReady)
                     releaseRawInputRestartGate();
-                void flushPending();
+                // A local replacement process can exist before its TUI input box does.
+                // Only re-kick a prompt that became ready while the restart fence was
+                // still armed; otherwise markPromptReady() owns the first flush.
+                if (isPromptReady)
+                    void flushPending();
             }, 500);
         }
         catch (err) {
+            replacementSpawnInProgress = false;
             cliRestartInProgress = false;
             try {
                 await sendFatalWorkerErrorAndExit(err);
@@ -8516,6 +8782,14 @@ function startWebServer(host, preferredPort) {
                 const startAttach = (cols, rows) => {
                     if (cp)
                         return;
+                    // Why: a prior web resize may leave the shared tmux window in manual mode.
+                    // `largest` restores the shared default without letting a smaller/newer
+                    // viewer resize every other attached client.
+                    spawnSync('tmux', ['set-option', '-t', tmuxTarget, 'window-size', 'largest'], {
+                        stdio: 'ignore',
+                        env: tmuxEnv(),
+                        timeout: 3000,
+                    });
                     // Defense in depth: view-capability clients attach through tmux's
                     // own read-only mode as well as the WebSocket input gate below.
                     cp = pty.spawn('tmux', [
@@ -9609,6 +9883,15 @@ async function sendFatalWorkerErrorAndExit(err, turnId = currentBotmuxTurnId, di
     if (fatalWorkerErrorPending)
         return;
     fatalWorkerErrorPending = true;
+    if (activeRestartAttemptId) {
+        await sendAndFlush({
+            type: 'restart_result',
+            attemptId: activeRestartAttemptId,
+            status: 'failed',
+            category: 'spawn_failed',
+        });
+        activeRestartAttemptId = undefined;
+    }
     await sendAndFlush({
         type: 'error',
         message: err instanceof Error ? err.message : String(err),
@@ -9632,6 +9915,7 @@ process.on('message', async (raw) => {
             if (lastInitConfig)
                 return; // already initialized
             lastInitConfig = msg;
+            activeRestartAttemptId = msg.restartAttemptId;
             sessionId = msg.sessionId;
             refreshTerminalViewToken();
             refreshTerminalWriteToken();
@@ -9677,7 +9961,6 @@ process.on('message', async (raw) => {
                 if (!isWorkflowWorker()) {
                     port = await startWebServer(config.web.workerHost, msg.webPort);
                     startScreenUpdates();
-                    startScreenAnalyzer();
                     startStuckDetector();
                 }
                 else {
@@ -9845,12 +10128,11 @@ process.on('message', async (raw) => {
             if (!backend && crashDiagnosticStopped && lastInitConfig && !lastInitConfig.adoptMode) {
                 log('Message received after crash-loop stop; retrying CLI start');
                 destroyCrashDiagnosticTerminal('retry after message');
-                stopScreenAnalyzer();
                 stopStuckDetector();
+                tuiPromptBlocking = false;
                 stopScreenUpdates();
                 awaitingFirstPrompt = true;
                 startScreenUpdates();
-                startScreenAnalyzer();
                 startStuckDetector();
                 try {
                     const restartCfg = { ...lastInitConfig, resume: true, prompt: '' };
@@ -9993,9 +10275,18 @@ process.on('message', async (raw) => {
             // barrier（shouldDeferUserFlush——/cd 未落地前任何用户输入都不得写入，
             // 否则 passthrough 会执行在旧 cwd 的 CLI 里）时入队。注入排空后由
             // flushPendingInjections 的 finally 补踢 flushPending 送达。
+            // 第四个例外是启动稳定窗口：detectBareShellLaunch() 采到裸 shell 时会
+            // await settleLaunchComm() 最长 2s 等 wrapper 完成 `exec <cli>`——这段
+            // await 让出事件循环，而 IPC handler 不串行（见 raw-input-followup-
+            // atomicity.test.ts），若此刻放行 passthrough 就会打进尚未 exec 的临时
+            // shell。bareShellCheckInProgress 覆盖"检查进行中"、bareShellLaunchBlocked
+            // 覆盖"已确认裸 shell 启动失败"两种状态,一并入队。裸 shell 确认失败后
+            // 这些 pending 不会再被 flush（与 pendingMessages 同款处理），符合预期。
             if (cliRestartInProgress || rawInputRestartGate || sessionRenameInFlight
-                || injectionFlushing || shouldDeferUserFlush(pendingInjections)) {
-                pendingRawInputs.push(msg);
+                || shouldHoldCodexRunnerInput(codexRunnerFreshness)
+                || injectionFlushing || shouldDeferUserFlush(pendingInjections)
+                || bareShellCheckInProgress || bareShellLaunchBlocked) {
+                freshnessInputQueue.enqueueRaw(msg);
                 log(`Deferred passthrough slash command until CLI input gate settles: ${msg.content}`);
             }
             else {
@@ -10030,7 +10321,58 @@ process.on('message', async (raw) => {
             break;
         }
         case 'restart': {
-            await restartCliProcess('daemon request', { preservePending: true });
+            // 角色切换的 cwd-move respawn：respawn 用 {...lastInitConfig, resume:true}，
+            // 先收敛 workingDir 才能让 CLI 在新目录重启（新 cwd 的 CLAUDE.md/记忆索引
+            // 开场注入）。旧桶 transcript 由 resume 预检的 syncClaudeResumeTargetToCwd
+            // （COPY 最新 <sid>.jsonl 进新 cwd 桶，已在 master）接住，上下文不丢。
+            if (msg.updateWorkingDir && lastInitConfig) {
+                lastInitConfig.workingDir = msg.updateWorkingDir;
+            }
+            // restart 合并：已有一轮 restart 在飞（teardown 进行中，或 tmux jitter
+            // 定时器未触发）时不叠加第二轮——叠加会 clearTimeout 吃掉首轮 teardown、
+            // 把重启预算无故烧到 tier-2 强制 FRESH（丢上下文），非 tmux 路径还会
+            // 双 spawn。workingDir 已收敛进 lastInitConfig，pending 的 spawn 展开
+            // {...lastInitConfig} 时自然拿到新目录。
+            //
+            // 这里**只 break、不记任何 flag**：restart 消息不带可信来源，无法区分
+            // 「replacement 崩溃触发的 auto-restart」与「用户重复点了一次 restart」。
+            // replacement 真退出时 onExit 已同步把 backend 置 null，续体用 !backend 即可
+            // 补 recovery（见 decideRestartFollowup）；健康的重复 restart 就该被合并掉，
+            // 记 flag 反而会逼健康进程再重启一轮、烧预算丢 --resume（正是合并要防的）。
+            if (cliRestartInProgress || tmuxRestartTimer) {
+                log(`Restart request merged into in-flight restart${msg.updateWorkingDir ? ` (workingDir → ${msg.updateWorkingDir})` : ''}`);
+                break;
+            }
+            activeRestartAttemptId = msg.attemptId;
+            codexRunnerFreshness = 'restarting_fresh';
+            // restart 杀死 CLI，在飞的 durable turn 随之死亡。对被杀的那次投递，主动发一个
+            // 'ambiguous' 终端回执：CLI 被中途杀掉，副作用到底发没发是**真的无法证明**
+            // （故不能报 'cancelled'），交由 daemon 的重试策略即时对账。不发的话 receipt 会
+            // 悬着，等 daemon 租约到期走 expire_durable_turn 的「无法证明 → 扣 ACK → 超时
+            // fencing teardown」慢路径（还会把刚 respawn 的新 CLI 二次 teardown）。
+            // emitTurnTerminal 自带释放（复位 durableTurnInFlight、退休 inflight input、
+            // 撤销 turn-origin relay、丢弃 bridge 尝试）并对后续 CLI-exit 终端去重；它排的
+            // flushPending 微任务会因下面 restartCliProcess 同步置位 cliRestartInProgress 而空跑。
+            // 结算被 restart 打断的在飞 durable turn（编排见 settleDurableTurnForRestart，
+            // 已单测）：drain 已落盘可靠终态让「刚好在 kill 前完成、watcher 未消费」的 turn
+            // 以 completed 抢占 deduper → 复检仍在飞才补发 ambiguous（否则无条件 ambiguous
+            // 会误标已完成投递 → 同 key 可重派 → 副作用两次）→ 兜底释放 latch 免卡 respawn。
+            // emitTurnTerminal 自带释放（复位 durableTurnInFlight、退休 inflight input、撤销
+            // turn-origin relay、丢弃 bridge 尝试）；它排的 flushPending 微任务会因下面
+            // restartCliProcess 同步置位 cliRestartInProgress 而空跑。
+            settleDurableTurnForRestart({
+                hasInFlightTurn: durableTurnInFlight,
+                hasCurrentTurnId: !!currentBotmuxTurnId,
+                drain: () => drainReliableTerminalBeforeInterrupt(),
+                isStillInFlight: () => durableTurnInFlight,
+                emitAmbiguous: () => emitTurnTerminal(currentBotmuxTurnId, 'ambiguous', undefined, currentBotmuxDispatchAttempt),
+                release: () => { durableTurnInFlight = false; inflightInputs.onTurnComplete(); },
+            });
+            await restartCliProcess(msg.updateWorkingDir ? `cwd-move respawn → ${msg.updateWorkingDir}` : 'daemon request', 
+            // cwd-move 是用户主动的目录迁移、不是崩溃恢复，不计入 tier-2 强制
+            // FRESH 的重启预算；respawn 真失败仍有 claude_exit → daemon
+            // auto-restart 那条裸 restart 的计数兜底。
+            { preservePending: true, skipRestartBudget: !!msg.updateWorkingDir });
             break;
         }
         case 'expire_durable_turn': {
@@ -10156,12 +10498,10 @@ process.on('message', async (raw) => {
             break;
         }
         case 'inject_command': {
-            // 会话内 /cd 移动后，worker 内部 respawn（claude_exit 自动重启 / IM /restart /
-            // dashboard restart）必须收敛到新目录，而不是陈旧的 lastInitConfig.workingDir。
-            if (msg.updateWorkingDir && lastInitConfig) {
-                lastInitConfig.workingDir = msg.updateWorkingDir;
-            }
-            pendingInjections.push({ command: msg.command, barrier: !!msg.updateWorkingDir });
+            // 唯一发送方是 /slash 路由的白名单 TUI 命令注入。cwd 移动不再走注入
+            // （角色切换已改为 restart+updateWorkingDir 的 respawn），这里不接受
+            // 任何 workingDir 改写——那会绕过 cd 路由的角色库硬校验。
+            pendingInjections.push({ command: msg.command, barrier: false });
             void flushPendingInjections();
             break;
         }
@@ -10294,10 +10634,11 @@ process.on('message', async (raw) => {
             catch { /* best-effort */ }
             backend = null;
             isPromptReady = false;
-            // Suspend INTENDS to resume later: preserve the sandbox overlay mount + the
-            // upper changeset across the suspension (on resume, prepareSandbox re-mounts
-            // over the SAME upper). So we stop the outbox watcher (no live CLI to serve)
-            // but DO NOT run sandboxCleanup (which would unmount + rm the changeset). We
+            // Suspend INTENDS to resume later: keep the per-session sandbox tree (the
+            // outbox + pre-created deny-mask mountpoints) intact across the suspension
+            // (on resume, prepareDirectSandbox re-binds over the SAME tree). So we stop
+            // the outbox watcher (no live CLI to serve) but DO NOT run sandboxCleanup
+            // (which would reclaim the mask mountpoints + rm the tree). We
             // also disarm the exit-time teardown so process.exit(0) below can't reclaim
             // it. (Crash/SIGKILL of a suspended-but-active session is still backstopped
             // by the daemon's periodic sandbox reconciler.)
@@ -10308,7 +10649,7 @@ process.on('message', async (raw) => {
                 catch { /* */ }
                 sandboxStopWatcher = null;
             }
-            sandboxCleanup = null; // drop the ref WITHOUT calling it (keep the mount)
+            sandboxCleanup = null; // drop the ref WITHOUT calling it (keep the tree)
             sandboxTeardownDone = true; // make the process.on('exit') hook a no-op
             cleanup();
             process.exit(0);
@@ -10384,15 +10725,15 @@ setInterval(() => {
     }
 }, 30_000).unref();
 // ─── Sandbox crash-time teardown ─────────────────────────────────────────────
-// killCli() (which unmounts the overlays + rm's the per-session tree) only runs
-// from the SIGTERM/SIGINT/disconnect/watchdog handlers and the close/suspend IPC
-// cases. An UNCAUGHT exception or unhandled rejection kills the process WITHOUT
-// any of those firing, so without this hook a crashed sandboxed worker would
-// leak BOTH overlay mounts (mount-table growth) + its upper/work dirs (disk leak)
-// per crash. We run a minimal, synchronous, best-effort sandbox teardown here so
-// the overlay/dir residue is reclaimed even on an abnormal exit. (SIGKILL still
-// can't be trapped — the daemon-side sweep + the periodic reconciler below are
-// the backstop for that.)
+// killCli() (which reclaims the deny-mask mountpoints + rm's the per-session
+// tree) only runs from the SIGTERM/SIGINT/disconnect/watchdog handlers and the
+// close/suspend IPC cases. An UNCAUGHT exception or unhandled rejection kills
+// the process WITHOUT any of those firing, so without this hook a crashed
+// sandboxed worker would leak its pre-created host mask mountpoints (empty dirs/
+// files) + the per-session tree (disk leak) per crash. We run a minimal,
+// synchronous, best-effort sandbox teardown here so that residue is reclaimed
+// even on an abnormal exit. (SIGKILL still can't be trapped — the daemon-side
+// sweep + the periodic reconciler below are the backstop for that.)
 function teardownSandboxBestEffort() {
     if (sandboxTeardownDone)
         return;