thaddeus 1.0.26 → 1.0.28

package/src/bridge/remoteBridgeCore.js

@@ -0,0 +1,712 @@
+// biome-ignore-all assist/source/organizeImports: ANT-ONLY import markers must not be reordered
+/**
+ * Env-less Remote Control bridge core.
+ *
+ * "Env-less" = no Environments API layer. Distinct from "CCR v2" (the
+ * /worker/* transport protocol) — the env-based path (replBridge.ts) can also
+ * use CCR v2 transport via THADDEUS_USE_CCR_V2. This file is about removing
+ * the poll/dispatch layer, not about which transport protocol is underneath.
+ *
+ * Unlike initBridgeCore (env-based, ~2400 lines), this connects directly
+ * to the session-ingress layer without the Environments API work-dispatch
+ * layer:
+ *
+ *   1. POST /v1/code/sessions              (OAuth, no env_id)  → session.id
+ *   2. POST /v1/code/sessions/{id}/bridge  (OAuth)             → {worker_jwt, expires_in, api_base_url, worker_epoch}
+ *      Each /bridge call bumps epoch — it IS the register. No separate /worker/register.
+ *   3. createV2ReplTransport(worker_jwt, worker_epoch)         → SSE + CCRClient
+ *   4. createTokenRefreshScheduler                             → proactive /bridge re-call (new JWT + new epoch)
+ *   5. 401 on SSE → rebuild transport with fresh /bridge credentials (same seq-num)
+ *
+ * No register/poll/ack/stop/heartbeat/deregister environment lifecycle.
+ * The Environments API historically existed because CCR's /worker/*
+ * endpoints required a session_id+role=worker JWT that only the work-dispatch
+ * layer could mint. Server PR #292605 (renamed in #293280) adds the /bridge endpoint as a direct
+ * OAuth→worker_jwt exchange, making the env layer optional for REPL sessions.
+ *
+ * Gated by `thaddeus_bridge_repl_v2` GrowthBook flag in initReplBridge.ts.
+ * REPL-only — daemon/print stay on env-based.
+ */
+import { feature } from 'bun:bundle';
+import axios from 'axios';
+import { createV2ReplTransport, } from './replBridgeTransport.js';
+import { buildCCRv2SdkUrl } from './workSecret.js';
+import { toCompatSessionId } from './sessionIdCompat.js';
+import { FlushGate } from './flushGate.js';
+import { createTokenRefreshScheduler } from './jwtUtils.js';
+import { getTrustedDeviceToken } from './trustedDevice.js';
+import { getEnvLessBridgeConfig, } from './envLessBridgeConfig.js';
+import { handleIngressMessage, handleServerControlRequest, makeResultMessage, isEligibleBridgeMessage, extractTitleText, BoundedUUIDSet, } from './bridgeMessaging.js';
+import { logBridgeSkip } from './debugUtils.js';
+import { logForDebugging } from '../utils/debug.js';
+import { logForDiagnosticsNoPII } from '../utils/diagLogs.js';
+import { isInProtectedNamespace } from '../utils/envUtils.js';
+import { errorMessage } from '../utils/errors.js';
+import { sleep } from '../utils/sleep.js';
+import { registerCleanup } from '../utils/cleanupRegistry.js';
+import { logEvent, } from '../services/analytics/index.js';
+const ANTHROPIC_VERSION = '2023-06-01';
+function oauthHeaders(accessToken) {
+    return {
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+        'anthropic-version': ANTHROPIC_VERSION,
+    };
+}
+/**
+ * Create a session, fetch a worker JWT, connect the v2 transport.
+ *
+ * Returns null on any pre-flight failure (session create failed, /bridge
+ * failed, transport setup failed). Caller (initReplBridge) surfaces this
+ * as a generic "initialization failed" state.
+ */
+export async function initEnvLessBridgeCore(params) {
+    const { baseUrl, orgUUID, title, getAccessToken, onAuth401, toSDKMessages, initialHistoryCap, initialMessages, onInboundMessage, onUserMessage, onPermissionResponse, onInterrupt, onSetModel, onSetMaxThinkingTokens, onSetPermissionMode, onStateChange, outboundOnly, tags, } = params;
+    const cfg = await getEnvLessBridgeConfig();
+    // ── 1. Create session (POST /v1/code/sessions, no env_id) ───────────────
+    const accessToken = getAccessToken();
+    if (!accessToken) {
+        logForDebugging('[remote-bridge] No OAuth token');
+        return null;
+    }
+    const createdSessionId = await withRetry(() => createCodeSession(baseUrl, accessToken, title, cfg.http_timeout_ms, tags), 'createCodeSession', cfg);
+    if (!createdSessionId) {
+        onStateChange?.('failed', 'Session creation failed — see debug log');
+        logBridgeSkip('v2_session_create_failed', undefined, true);
+        return null;
+    }
+    const sessionId = createdSessionId;
+    logForDebugging(`[remote-bridge] Created session ${sessionId}`);
+    logForDiagnosticsNoPII('info', 'bridge_repl_v2_session_created');
+    // ── 2. Fetch bridge credentials (POST /bridge → worker_jwt, expires_in, api_base_url) ──
+    const credentials = await withRetry(() => fetchRemoteCredentials(sessionId, baseUrl, accessToken, cfg.http_timeout_ms), 'fetchRemoteCredentials', cfg);
+    if (!credentials) {
+        onStateChange?.('failed', 'Remote credentials fetch failed — see debug log');
+        logBridgeSkip('v2_remote_creds_failed', undefined, true);
+        void archiveSession(sessionId, baseUrl, accessToken, orgUUID, cfg.http_timeout_ms);
+        return null;
+    }
+    logForDebugging(`[remote-bridge] Fetched bridge credentials (expires_in=${credentials.expires_in}s)`);
+    // ── 3. Build v2 transport (SSETransport + CCRClient) ────────────────────
+    const sessionUrl = buildCCRv2SdkUrl(credentials.api_base_url, sessionId);
+    logForDebugging(`[remote-bridge] v2 session URL: ${sessionUrl}`);
+    let transport;
+    try {
+        transport = await createV2ReplTransport({
+            sessionUrl,
+            ingressToken: credentials.worker_jwt,
+            sessionId,
+            epoch: credentials.worker_epoch,
+            heartbeatIntervalMs: cfg.heartbeat_interval_ms,
+            heartbeatJitterFraction: cfg.heartbeat_jitter_fraction,
+            // Per-instance closure — keeps the worker JWT out of
+            // process.env.THADDEUS_SESSION_ACCESS_TOKEN, which mcp/client.ts
+            // reads ungatedly and would otherwise send to user-configured ws/http
+            // MCP servers. Frozen-at-construction is correct: transport is fully
+            // rebuilt on refresh (rebuildTransport below).
+            getAuthToken: () => credentials.worker_jwt,
+            outboundOnly,
+        });
+    }
+    catch (err) {
+        logForDebugging(`[remote-bridge] v2 transport setup failed: ${errorMessage(err)}`, { level: 'error' });
+        onStateChange?.('failed', `Transport setup failed: ${errorMessage(err)}`);
+        logBridgeSkip('v2_transport_setup_failed', undefined, true);
+        void archiveSession(sessionId, baseUrl, accessToken, orgUUID, cfg.http_timeout_ms);
+        return null;
+    }
+    logForDebugging(`[remote-bridge] v2 transport created (epoch=${credentials.worker_epoch})`);
+    onStateChange?.('ready');
+    // ── 4. State ────────────────────────────────────────────────────────────
+    // Echo dedup: messages we POST come back on the read stream. Seeded with
+    // initial message UUIDs so server echoes of flushed history are recognized.
+    // Both sets cover initial UUIDs — recentPostedUUIDs is a 2000-cap ring buffer
+    // and could evict them after enough live writes; initialMessageUUIDs is the
+    // unbounded fallback. Defense-in-depth; mirrors replBridge.ts.
+    const recentPostedUUIDs = new BoundedUUIDSet(cfg.uuid_dedup_buffer_size);
+    const initialMessageUUIDs = new Set();
+    if (initialMessages) {
+        for (const msg of initialMessages) {
+            initialMessageUUIDs.add(msg.uuid);
+            recentPostedUUIDs.add(msg.uuid);
+        }
+    }
+    // Defensive dedup for re-delivered inbound prompts (seq-num negotiation
+    // edge cases, server history replay after transport swap).
+    const recentInboundUUIDs = new BoundedUUIDSet(cfg.uuid_dedup_buffer_size);
+    // FlushGate: queue live writes while the history flush POST is in flight,
+    // so the server receives [history..., live...] in order.
+    const flushGate = new FlushGate();
+    let initialFlushDone = false;
+    let tornDown = false;
+    let authRecoveryInFlight = false;
+    // Latch for onUserMessage — flips true when the callback returns true
+    // (policy says "done deriving"). sessionId is const (no re-create path —
+    // rebuildTransport swaps JWT/epoch, same session), so no reset needed.
+    let userMessageCallbackDone = !onUserMessage;
+    // Telemetry: why did onConnect fire? Set by rebuildTransport before
+    // wireTransportCallbacks; read asynchronously by onConnect. Race-safe
+    // because authRecoveryInFlight serializes rebuild callers, and a fresh
+    // initEnvLessBridgeCore() call gets a fresh closure defaulting to 'initial'.
+    let connectCause = 'initial';
+    // Deadline for onConnect after transport.connect(). Cleared by onConnect
+    // (connected) and onClose (got a close — not silent). If neither fires
+    // before cfg.connect_timeout_ms, onConnectTimeout emits — the only
+    // signal for the `started → (silence)` gap.
+    let connectDeadline;
+    function onConnectTimeout(cause) {
+        if (tornDown)
+            return;
+        logEvent('thaddeus_bridge_repl_connect_timeout', {
+            v2: true,
+            elapsed_ms: cfg.connect_timeout_ms,
+            cause: cause,
+        });
+    }
+    // ── 5. JWT refresh scheduler ────────────────────────────────────────────
+    // Schedule a callback 5min before expiry (per response.expires_in). On fire,
+    // re-fetch /bridge with OAuth → rebuild transport with fresh credentials.
+    // Each /bridge call bumps epoch server-side, so a JWT-only swap would leave
+    // the old CCRClient heartbeating with a stale epoch → 409 within 20s.
+    // JWT is opaque — do not decode.
+    const refresh = createTokenRefreshScheduler({
+        refreshBufferMs: cfg.token_refresh_buffer_ms,
+        getAccessToken: async () => {
+            // Unconditionally refresh OAuth before calling /bridge — getAccessToken()
+            // returns expired tokens as non-null strings (doesn't check expiresAt),
+            // so truthiness doesn't mean valid. Pass the stale token to onAuth401
+            // so handleOAuth401Error's keychain-comparison can detect parallel refresh.
+            const stale = getAccessToken();
+            if (onAuth401)
+                await onAuth401(stale ?? '');
+            return getAccessToken() ?? stale;
+        },
+        onRefresh: (sid, oauthToken) => {
+            void (async () => {
+                // Laptop wake: overdue proactive timer + SSE 401 fire ~simultaneously.
+                // Claim the flag BEFORE the /bridge fetch so the other path skips
+                // entirely — prevents double epoch bump (each /bridge call bumps; if
+                // both fetch, the first rebuild gets a stale epoch and 409s).
+                if (authRecoveryInFlight || tornDown) {
+                    logForDebugging('[remote-bridge] Recovery already in flight, skipping proactive refresh');
+                    return;
+                }
+                authRecoveryInFlight = true;
+                try {
+                    const fresh = await withRetry(() => fetchRemoteCredentials(sid, baseUrl, oauthToken, cfg.http_timeout_ms), 'fetchRemoteCredentials (proactive)', cfg);
+                    if (!fresh || tornDown)
+                        return;
+                    await rebuildTransport(fresh, 'proactive_refresh');
+                    logForDebugging('[remote-bridge] Transport rebuilt (proactive refresh)');
+                }
+                catch (err) {
+                    logForDebugging(`[remote-bridge] Proactive refresh rebuild failed: ${errorMessage(err)}`, { level: 'error' });
+                    logForDiagnosticsNoPII('error', 'bridge_repl_v2_proactive_refresh_failed');
+                    if (!tornDown) {
+                        onStateChange?.('failed', `Refresh failed: ${errorMessage(err)}`);
+                    }
+                }
+                finally {
+                    authRecoveryInFlight = false;
+                }
+            })();
+        },
+        label: 'remote',
+    });
+    refresh.scheduleFromExpiresIn(sessionId, credentials.expires_in);
+    // ── 6. Wire callbacks (extracted so transport-rebuild can re-wire) ──────
+    function wireTransportCallbacks() {
+        transport.setOnConnect(() => {
+            clearTimeout(connectDeadline);
+            logForDebugging('[remote-bridge] v2 transport connected');
+            logForDiagnosticsNoPII('info', 'bridge_repl_v2_transport_connected');
+            logEvent('thaddeus_bridge_repl_ws_connected', {
+                v2: true,
+                cause: connectCause,
+            });
+            if (!initialFlushDone && initialMessages && initialMessages.length > 0) {
+                initialFlushDone = true;
+                // Capture current transport — if 401/teardown happens mid-flush,
+                // the stale .finally() must not drain the gate or signal connected.
+                // (Same guard pattern as replBridge.ts:1119.)
+                const flushTransport = transport;
+                void flushHistory(initialMessages)
+                    .catch(e => logForDebugging(`[remote-bridge] flushHistory failed: ${e}`))
+                    .finally(() => {
+                    // authRecoveryInFlight catches the v1-vs-v2 asymmetry: v1 nulls
+                    // transport synchronously in setOnClose (replBridge.ts:1175), so
+                    // transport !== flushTransport trips immediately. v2 doesn't null —
+                    // transport reassigned only at rebuildTransport:346, 3 awaits deep.
+                    // authRecoveryInFlight is set synchronously at rebuildTransport entry.
+                    if (transport !== flushTransport ||
+                        tornDown ||
+                        authRecoveryInFlight) {
+                        return;
+                    }
+                    drainFlushGate();
+                    onStateChange?.('connected');
+                });
+            }
+            else if (!flushGate.active) {
+                onStateChange?.('connected');
+            }
+        });
+        transport.setOnData((data) => {
+            handleIngressMessage(data, recentPostedUUIDs, recentInboundUUIDs, onInboundMessage, 
+            // Remote client answered the permission prompt — the turn resumes.
+            // Without this the server stays on requires_action until the next
+            // user message or turn-end result.
+            onPermissionResponse
+                ? res => {
+                    transport.reportState('running');
+                    onPermissionResponse(res);
+                }
+                : undefined, req => handleServerControlRequest(req, {
+                transport,
+                sessionId,
+                onInterrupt,
+                onSetModel,
+                onSetMaxThinkingTokens,
+                onSetPermissionMode,
+                outboundOnly,
+            }));
+        });
+        transport.setOnClose((code) => {
+            clearTimeout(connectDeadline);
+            if (tornDown)
+                return;
+            logForDebugging(`[remote-bridge] v2 transport closed (code=${code})`);
+            logEvent('thaddeus_bridge_repl_ws_closed', { code, v2: true });
+            // onClose fires only for TERMINAL failures: 401 (JWT invalid),
+            // 4090 (CCR epoch mismatch), 4091 (CCR init failed), or SSE 10-min
+            // reconnect budget exhausted. Transient disconnects are handled
+            // transparently inside SSETransport. 401 we can recover from (fetch
+            // fresh JWT, rebuild transport); all other codes are dead-ends.
+            if (code === 401 && !authRecoveryInFlight) {
+                void recoverFromAuthFailure();
+                return;
+            }
+            onStateChange?.('failed', `Transport closed (code ${code})`);
+        });
+    }
+    // ── 7. Transport rebuild (shared by proactive refresh + 401 recovery) ──
+    // Every /bridge call bumps epoch server-side. Both refresh paths must
+    // rebuild the transport with the new epoch — a JWT-only swap leaves the
+    // old CCRClient heartbeating stale epoch → 409. SSE resumes from the old
+    // transport's high-water-mark seq-num so no server-side replay.
+    // Caller MUST set authRecoveryInFlight = true before calling (synchronously,
+    // before any await) and clear it in a finally. This function doesn't manage
+    // the flag — moving it here would be too late to prevent a double /bridge
+    // fetch, and each fetch bumps epoch.
+    async function rebuildTransport(fresh, cause) {
+        connectCause = cause;
+        // Queue writes during rebuild — once /bridge returns, the old transport's
+        // epoch is stale and its next write/heartbeat 409s. Without this gate,
+        // writeMessages adds UUIDs to recentPostedUUIDs then writeBatch silently
+        // no-ops (closed uploader after 409) → permanent silent message loss.
+        flushGate.start();
+        try {
+            const seq = transport.getLastSequenceNum();
+            transport.close();
+            transport = await createV2ReplTransport({
+                sessionUrl: buildCCRv2SdkUrl(fresh.api_base_url, sessionId),
+                ingressToken: fresh.worker_jwt,
+                sessionId,
+                epoch: fresh.worker_epoch,
+                heartbeatIntervalMs: cfg.heartbeat_interval_ms,
+                heartbeatJitterFraction: cfg.heartbeat_jitter_fraction,
+                initialSequenceNum: seq,
+                getAuthToken: () => fresh.worker_jwt,
+                outboundOnly,
+            });
+            if (tornDown) {
+                // Teardown fired during the async createV2ReplTransport window.
+                // Don't wire/connect/schedule — we'd re-arm timers after cancelAll()
+                // and fire onInboundMessage into a torn-down bridge.
+                transport.close();
+                return;
+            }
+            wireTransportCallbacks();
+            transport.connect();
+            connectDeadline = setTimeout(onConnectTimeout, cfg.connect_timeout_ms, connectCause);
+            refresh.scheduleFromExpiresIn(sessionId, fresh.expires_in);
+            // Drain queued writes into the new uploader. Runs before
+            // ccr.initialize() resolves (transport.connect() is fire-and-forget),
+            // but the uploader serializes behind the initial PUT /worker. If
+            // init fails (4091), events drop — but only recentPostedUUIDs
+            // (per-instance) is populated, so re-enabling the bridge re-flushes.
+            drainFlushGate();
+        }
+        finally {
+            // End the gate on failure paths too — drainFlushGate already ended
+            // it on success. Queued messages are dropped (transport still dead).
+            flushGate.drop();
+        }
+    }
+    // ── 8. 401 recovery (OAuth refresh + rebuild) ───────────────────────────
+    async function recoverFromAuthFailure() {
+        // setOnClose already guards `!authRecoveryInFlight` but that check and
+        // this set must be atomic against onRefresh — claim synchronously before
+        // any await. Laptop wake fires both paths ~simultaneously.
+        if (authRecoveryInFlight)
+            return;
+        authRecoveryInFlight = true;
+        onStateChange?.('reconnecting', 'JWT expired — refreshing');
+        logForDebugging('[remote-bridge] 401 on SSE — attempting JWT refresh');
+        try {
+            // Unconditionally try OAuth refresh — getAccessToken() returns expired
+            // tokens as non-null strings, so !oauthToken doesn't catch expiry.
+            // Pass the stale token so handleOAuth401Error's keychain-comparison
+            // can detect if another tab already refreshed.
+            const stale = getAccessToken();
+            if (onAuth401)
+                await onAuth401(stale ?? '');
+            const oauthToken = getAccessToken() ?? stale;
+            if (!oauthToken || tornDown) {
+                if (!tornDown) {
+                    onStateChange?.('failed', 'JWT refresh failed: no OAuth token');
+                }
+                return;
+            }
+            const fresh = await withRetry(() => fetchRemoteCredentials(sessionId, baseUrl, oauthToken, cfg.http_timeout_ms), 'fetchRemoteCredentials (recovery)', cfg);
+            if (!fresh || tornDown) {
+                if (!tornDown) {
+                    onStateChange?.('failed', 'JWT refresh failed after 401');
+                }
+                return;
+            }
+            // If 401 interrupted the initial flush, writeBatch may have silently
+            // no-op'd on the closed uploader (ccr.close() ran in the SSE wrapper
+            // before our setOnClose callback). Reset so the new onConnect re-flushes.
+            // (v1 scopes initialFlushDone inside the per-transport closure at
+            // replBridge.ts:1027 so it resets naturally; v2 has it at outer scope.)
+            initialFlushDone = false;
+            await rebuildTransport(fresh, 'auth_401_recovery');
+            logForDebugging('[remote-bridge] Transport rebuilt after 401');
+        }
+        catch (err) {
+            logForDebugging(`[remote-bridge] 401 recovery failed: ${errorMessage(err)}`, { level: 'error' });
+            logForDiagnosticsNoPII('error', 'bridge_repl_v2_jwt_refresh_failed');
+            if (!tornDown) {
+                onStateChange?.('failed', `JWT refresh failed: ${errorMessage(err)}`);
+            }
+        }
+        finally {
+            authRecoveryInFlight = false;
+        }
+    }
+    wireTransportCallbacks();
+    // Start flushGate BEFORE connect so writeMessages() during handshake
+    // queues instead of racing the history POST.
+    if (initialMessages && initialMessages.length > 0) {
+        flushGate.start();
+    }
+    transport.connect();
+    connectDeadline = setTimeout(onConnectTimeout, cfg.connect_timeout_ms, connectCause);
+    // ── 8. History flush + drain helpers ────────────────────────────────────
+    function drainFlushGate() {
+        const msgs = flushGate.end();
+        if (msgs.length === 0)
+            return;
+        for (const msg of msgs)
+            recentPostedUUIDs.add(msg.uuid);
+        const events = toSDKMessages(msgs).map(m => ({
+            ...m,
+            session_id: sessionId,
+        }));
+        if (msgs.some(m => m.type === 'user')) {
+            transport.reportState('running');
+        }
+        logForDebugging(`[remote-bridge] Drained ${msgs.length} queued message(s) after flush`);
+        void transport.writeBatch(events);
+    }
+    async function flushHistory(msgs) {
+        // v2 always creates a fresh server session (unconditional createCodeSession
+        // above) — no session reuse, no double-post risk. Unlike v1, we do NOT
+        // filter by previouslyFlushedUUIDs: that set persists across REPL enable/
+        // disable cycles (useRef), so it would wrongly suppress history on re-enable.
+        const eligible = msgs.filter(isEligibleBridgeMessage);
+        const capped = initialHistoryCap > 0 && eligible.length > initialHistoryCap
+            ? eligible.slice(-initialHistoryCap)
+            : eligible;
+        if (capped.length < eligible.length) {
+            logForDebugging(`[remote-bridge] Capped initial flush: ${eligible.length} -> ${capped.length} (cap=${initialHistoryCap})`);
+        }
+        const events = toSDKMessages(capped).map(m => ({
+            ...m,
+            session_id: sessionId,
+        }));
+        if (events.length === 0)
+            return;
+        // Mid-turn init: if Remote Control is enabled while a query is running,
+        // the last eligible message is a user prompt or tool_result (both 'user'
+        // type). Without this the init PUT's 'idle' sticks until the next user-
+        // type message forwards via writeMessages — which for a pure-text turn
+        // is never (only assistant chunks stream post-init). Check eligible (pre-
+        // cap), not capped: the cap may truncate to a user message even when the
+        // actual trailing message is assistant.
+        if (eligible.at(-1)?.type === 'user') {
+            transport.reportState('running');
+        }
+        logForDebugging(`[remote-bridge] Flushing ${events.length} history events`);
+        await transport.writeBatch(events);
+    }
+    // ── 9. Teardown ───────────────────────────────────────────────────────────
+    // On SIGINT/SIGTERM/⁠/exit, gracefulShutdown races runCleanupFunctions()
+    // against a 2s cap before forceExit kills the process. Budget accordingly:
+    //   - archive: teardown_archive_timeout_ms (default 1500, cap 2000)
+    //   - result write: fire-and-forget, archive latency covers the drain
+    //   - 401 retry: only if first archive 401s, shares the same budget
+    async function teardown() {
+        if (tornDown)
+            return;
+        tornDown = true;
+        refresh.cancelAll();
+        clearTimeout(connectDeadline);
+        flushGate.drop();
+        // Fire the result message before archive — transport.write() only awaits
+        // enqueue (SerialBatchEventUploader resolves once buffered, drain is
+        // async). Archiving before close() gives the uploader's drain loop a
+        // window (typical archive ≈ 100-500ms) to POST the result without an
+        // explicit sleep. close() sets closed=true which interrupts drain at the
+        // next while-check, so close-before-archive drops the result.
+        transport.reportState('idle');
+        void transport.write(makeResultMessage(sessionId));
+        let token = getAccessToken();
+        let status = await archiveSession(sessionId, baseUrl, token, orgUUID, cfg.teardown_archive_timeout_ms);
+        // Token is usually fresh (refresh scheduler runs 5min before expiry) but
+        // laptop-wake past the refresh window leaves getAccessToken() returning a
+        // stale string. Retry once on 401 — onAuth401 (= handleOAuth401Error)
+        // clears keychain cache + force-refreshes. No proactive refresh on the
+        // happy path: handleOAuth401Error force-refreshes even valid tokens,
+        // which would waste budget 99% of the time. try/catch mirrors
+        // recoverFromAuthFailure: keychain reads can throw (macOS locked after
+        // wake); an uncaught throw here would skip transport.close + telemetry.
+        if (status === 401 && onAuth401) {
+            try {
+                await onAuth401(token ?? '');
+                token = getAccessToken();
+                status = await archiveSession(sessionId, baseUrl, token, orgUUID, cfg.teardown_archive_timeout_ms);
+            }
+            catch (err) {
+                logForDebugging(`[remote-bridge] Teardown 401 retry threw: ${errorMessage(err)}`, { level: 'error' });
+            }
+        }
+        transport.close();
+        const archiveStatus = status === 'no_token'
+            ? 'skipped_no_token'
+            : status === 'timeout' || status === 'error'
+                ? 'network_error'
+                : status >= 500
+                    ? 'server_5xx'
+                    : status >= 400
+                        ? 'server_4xx'
+                        : 'ok';
+        logForDebugging(`[remote-bridge] Torn down (archive=${status})`);
+        logForDiagnosticsNoPII('info', 'bridge_repl_v2_teardown');
+        logEvent(feature('CCR_MIRROR') && outboundOnly
+            ? 'thaddeus_ccr_mirror_teardown'
+            : 'thaddeus_bridge_repl_teardown', {
+            v2: true,
+            archive_status: archiveStatus,
+            archive_ok: typeof status === 'number' && status < 400,
+            archive_http_status: typeof status === 'number' ? status : undefined,
+            archive_timeout: status === 'timeout',
+            archive_no_token: status === 'no_token',
+        });
+    }
+    const unregister = registerCleanup(teardown);
+    if (feature('CCR_MIRROR') && outboundOnly) {
+        logEvent('thaddeus_ccr_mirror_started', {
+            v2: true,
+            expires_in_s: credentials.expires_in,
+        });
+    }
+    else {
+        logEvent('thaddeus_bridge_repl_started', {
+            has_initial_messages: !!(initialMessages && initialMessages.length > 0),
+            v2: true,
+            expires_in_s: credentials.expires_in,
+            inProtectedNamespace: isInProtectedNamespace(),
+        });
+    }
+    // ── 10. Handle ──────────────────────────────────────────────────────────
+    return {
+        bridgeSessionId: sessionId,
+        environmentId: '',
+        sessionIngressUrl: credentials.api_base_url,
+        writeMessages(messages) {
+            const filtered = messages.filter(m => isEligibleBridgeMessage(m) &&
+                !initialMessageUUIDs.has(m.uuid) &&
+                !recentPostedUUIDs.has(m.uuid));
+            if (filtered.length === 0)
+                return;
+            // Fire onUserMessage for title derivation. Scan before the flushGate
+            // check — prompts are title-worthy even if they queue. Keeps calling
+            // on every title-worthy message until the callback returns true; the
+            // caller owns the policy (derive at 1st and 3rd, skip if explicit).
+            if (!userMessageCallbackDone) {
+                for (const m of filtered) {
+                    const text = extractTitleText(m);
+                    if (text !== undefined && onUserMessage?.(text, sessionId)) {
+                        userMessageCallbackDone = true;
+                        break;
+                    }
+                }
+            }
+            if (flushGate.enqueue(...filtered)) {
+                logForDebugging(`[remote-bridge] Queued ${filtered.length} message(s) during flush`);
+                return;
+            }
+            for (const msg of filtered)
+                recentPostedUUIDs.add(msg.uuid);
+            const events = toSDKMessages(filtered).map(m => ({
+                ...m,
+                session_id: sessionId,
+            }));
+            // v2 does not derive worker_status from events server-side (unlike v1
+            // session-ingress session_status_updater.go). Push it from here so the
+            // CCR web session list shows Running instead of stuck on Idle. A user
+            // message in the batch marks turn start. CCRClient.reportState dedupes
+            // consecutive same-state pushes.
+            if (filtered.some(m => m.type === 'user')) {
+                transport.reportState('running');
+            }
+            logForDebugging(`[remote-bridge] Sending ${filtered.length} message(s)`);
+            void transport.writeBatch(events);
+        },
+        writeSdkMessages(messages) {
+            const filtered = messages.filter(m => !m.uuid || !recentPostedUUIDs.has(m.uuid));
+            if (filtered.length === 0)
+                return;
+            for (const msg of filtered) {
+                if (msg.uuid)
+                    recentPostedUUIDs.add(msg.uuid);
+            }
+            const events = filtered.map(m => ({ ...m, session_id: sessionId }));
+            void transport.writeBatch(events);
+        },
+        sendControlRequest(request) {
+            if (authRecoveryInFlight) {
+                logForDebugging(`[remote-bridge] Dropping control_request during 401 recovery: ${request.request_id}`);
+                return;
+            }
+            const event = { ...request, session_id: sessionId };
+            if (request.request.subtype === 'can_use_tool') {
+                transport.reportState('requires_action');
+            }
+            void transport.write(event);
+            logForDebugging(`[remote-bridge] Sent control_request request_id=${request.request_id}`);
+        },
+        sendControlResponse(response) {
+            if (authRecoveryInFlight) {
+                logForDebugging('[remote-bridge] Dropping control_response during 401 recovery');
+                return;
+            }
+            const event = { ...response, session_id: sessionId };
+            transport.reportState('running');
+            void transport.write(event);
+            logForDebugging('[remote-bridge] Sent control_response');
+        },
+        sendControlCancelRequest(requestId) {
+            if (authRecoveryInFlight) {
+                logForDebugging(`[remote-bridge] Dropping control_cancel_request during 401 recovery: ${requestId}`);
+                return;
+            }
+            const event = {
+                type: 'control_cancel_request',
+                request_id: requestId,
+                session_id: sessionId,
+            };
+            // Hook/classifier/channel/recheck resolved the permission locally —
+            // interactiveHandler calls only cancelRequest (no sendResponse) on
+            // those paths, so without this the server stays on requires_action.
+            transport.reportState('running');
+            void transport.write(event);
+            logForDebugging(`[remote-bridge] Sent control_cancel_request request_id=${requestId}`);
+        },
+        sendResult() {
+            if (authRecoveryInFlight) {
+                logForDebugging('[remote-bridge] Dropping result during 401 recovery');
+                return;
+            }
+            transport.reportState('idle');
+            void transport.write(makeResultMessage(sessionId));
+            logForDebugging(`[remote-bridge] Sent result`);
+        },
+        async teardown() {
+            unregister();
+            await teardown();
+        },
+    };
+}
+// ─── Session API (v2 /code/sessions, no env) ─────────────────────────────────
+/** Retry an async init call with exponential backoff + jitter. */
+async function withRetry(fn, label, cfg) {
+    const max = cfg.init_retry_max_attempts;
+    for (let attempt = 1; attempt <= max; attempt++) {
+        const result = await fn();
+        if (result !== null)
+            return result;
+        if (attempt < max) {
+            const base = cfg.init_retry_base_delay_ms * 2 ** (attempt - 1);
+            const jitter = base * cfg.init_retry_jitter_fraction * (2 * Math.random() - 1);
+            const delay = Math.min(base + jitter, cfg.init_retry_max_delay_ms);
+            logForDebugging(`[remote-bridge] ${label} failed (attempt ${attempt}/${max}), retrying in ${Math.round(delay)}ms`);
+            await sleep(delay);
+        }
+    }
+    return null;
+}
+// Moved to codeSessionApi.ts so the SDK /bridge subpath can bundle them
+// without pulling in this file's heavy CLI tree (analytics, transport).
+export { createCodeSession, } from './codeSessionApi.js';
+import { createCodeSession, fetchRemoteCredentials as fetchRemoteCredentialsRaw, } from './codeSessionApi.js';
+import { getBridgeBaseUrlOverride } from './bridgeConfig.js';
+// CLI-side wrapper that applies the CLAUDE_BRIDGE_BASE_URL dev override and
+// injects the trusted-device token (both are env/GrowthBook reads that the
+// SDK-facing codeSessionApi.ts export must stay free of).
+export async function fetchRemoteCredentials(sessionId, baseUrl, accessToken, timeoutMs) {
+    const creds = await fetchRemoteCredentialsRaw(sessionId, baseUrl, accessToken, timeoutMs, getTrustedDeviceToken());
+    if (!creds)
+        return null;
+    return getBridgeBaseUrlOverride()
+        ? { ...creds, api_base_url: baseUrl }
+        : creds;
+}
+async function archiveSession(sessionId, baseUrl, accessToken, orgUUID, timeoutMs) {
+    if (!accessToken)
+        return 'no_token';
+    // Archive lives at the compat layer (/v1/sessions/*, not /v1/code/sessions).
+    // compat.parseSessionID only accepts TagSession (session_*), so retag cse_*.
+    // anthropic-beta + x-organization-uuid are required — without them the
+    // compat gateway 404s before reaching the handler.
+    //
+    // Unlike bridgeMain.ts (which caches compatId in sessionCompatIds to keep
+    // in-memory titledSessions/logger keys consistent across a mid-session
+    // gate flip), this compatId is only a server URL path segment — no
+    // in-memory state. Fresh compute matches whatever the server currently
+    // validates: if the gate is OFF, the server has been updated to accept
+    // cse_* and we correctly send it.
+    const compatId = toCompatSessionId(sessionId);
+    try {
+        const response = await axios.post(`${baseUrl}/v1/sessions/${compatId}/archive`, {}, {
+            headers: {
+                ...oauthHeaders(accessToken),
+                'anthropic-beta': 'ccr-byoc-2025-07-29',
+                'x-organization-uuid': orgUUID,
+            },
+            timeout: timeoutMs,
+            validateStatus: () => true,
+        });
+        logForDebugging(`[remote-bridge] Archive ${compatId} status=${response.status}`);
+        return response.status;
+    }
+    catch (err) {
+        const msg = errorMessage(err);
+        logForDebugging(`[remote-bridge] Archive failed: ${msg}`);
+        return axios.isAxiosError(err) && err.code === 'ECONNABORTED'
+            ? 'timeout'
+            : 'error';
+    }
+}