nexting-cc-bridge 0.8.3

package/dist/bridge.js

@@ -0,0 +1,931 @@
+import WebSocket from "ws";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { spawn as nodeSpawn } from "node:child_process";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { startLocalShell } from "./local-shell.js";
+import { createHub } from "./hub.js";
+import { startHubServer } from "./hub-server.js";
+/** Build a proxy agent from env, if any. A direct China→US WSS gets reset by the
+ * network (ETIMEDOUT) and the bridge's own DNS intermittently fails (ENOTFOUND);
+ * routing the socket through the local proxy (Clash etc.) fixes both — the bridge
+ * dials 127.0.0.1 and the proxy resolves + tunnels to the server. */
+export function proxyAgentFromEnv() {
+    const url = process.env.NEXTING_CC_PROXY ||
+        process.env.HTTPS_PROXY ||
+        process.env.https_proxy ||
+        process.env.ALL_PROXY ||
+        process.env.all_proxy;
+    return url ? new HttpsProxyAgent(url) : undefined;
+}
+import { createClaudeAdapter, resolveClaudeBin, } from "./engine/claude-adapter.js";
+import { createCodexAdapter, resolveCodexBin } from "./engine/codex-adapter.js";
+export { resolveClaudeBin, resolveCodexBin };
+import { discoverSessions, discoverCodexSessions, readFullTranscript, listDir, } from "./scanner.js";
+import { listSkills } from "./skills-scanner.js";
+import { readFilePreview } from "./file-preview.js";
+import { listCodexPrompts } from "./codex-prompts.js";
+import { createCodexThreadSource, CODEX_PROBE_CWD, } from "./codex-thread-source.js";
+import { createAttachManager } from "./attach-manager.js";
+import { createWatchManager } from "./watch-manager.js";
+import { createTurnProbe } from "./turn-probe.js";
+import { createPromptDetector } from "./prompt-detector.js";
+import { parseCodexTranscript, findCodexSessionFile, readCodexTranscript, } from "./codex-transcript.js";
+import { createBridgeMediaUploader, hydrateTranscriptMedia, } from "./media-hydrator.js";
+import { cloudHttpBaseFromWsUrl } from "./mcp-config.js";
+import { SessionKeyStore } from "./e2e/key-store.js";
+import { EnvelopeCodec } from "./e2e/codec.js";
+import { keychainIdentityStore } from "./e2e/keychain-identity.js";
+export const VERSION = "0.8.3";
+/** Real spawn of an engine child process (bidirectional pipes). */
+const realSpawn = (command, args, opts) => nodeSpawn(command, args, {
+    cwd: opts.cwd,
+    stdio: ["pipe", "pipe", "pipe"],
+});
+export function buildSnapshot(sessions) {
+    return { type: "cc_snapshot", sessions };
+}
+/** Stamp `controllable:true` on sessions the local shell owns. Pure for testing. */
+export function stampControllable(sessions, controllable) {
+    return sessions.map((s) => ({
+        ...s,
+        controllable: controllable.has(s.sessionId),
+    }));
+}
+const CODEX_STATE_FILES = new Set([
+    "state_5.sqlite",
+    "state_5.sqlite-wal",
+    "state_5.sqlite-shm",
+    "session_index.jsonl",
+    ".codex-global-state.json",
+]);
+/** Top-level Codex App files that can change the visible sidebar title/list
+ * without a session JSONL write. `fs.watch` can omit filename on macOS, so
+ * null is treated as relevant and let the snapshot diff decide. */
+export function isCodexStateFileChange(filename) {
+    if (filename == null)
+        return true;
+    const raw = String(filename);
+    if (raw.includes("/") || raw.includes("\\"))
+        return false;
+    return CODEX_STATE_FILES.has(path.basename(raw));
+}
+/** Pure-ish message handler: reacts to cloud frames. Unit-tested. */
+export function makeBridgeHandler(deps) {
+    return async (msg) => {
+        if (msg.type === "cc_session_complete") {
+            const sessionId = msg.sessionId;
+            const result = msg.result;
+            if (sessionId && result && deps.onSessionComplete) {
+                try {
+                    await deps.onSessionComplete(sessionId, result);
+                }
+                catch (e) {
+                    // Silently drop completion errors — completion is fire-and-forget.
+                }
+            }
+            return;
+        }
+        if (msg.type === "cc_get_transcript") {
+            const sessionId = msg.sessionId;
+            const requestId = msg.requestId;
+            // Incremental slice: fromIndex>0 returns only entries[fromIndex..] plus
+            // `total`, so reconciliation costs a few KB instead of the whole session
+            // (full-transcript storms congested the bridge's uplink — 2026-06-10).
+            const fromIndex = Math.max(0, Number(msg.fromIndex) || 0);
+            const entries = await deps.readTranscript(sessionId);
+            const total = entries?.length ?? 0;
+            const from = Math.min(fromIndex, total);
+            deps.send({
+                type: "cc_transcript_result",
+                requestId,
+                sessionId,
+                entries: entries ? entries.slice(from) : [],
+                startIndex: from,
+                total,
+                notFound: entries === null,
+            });
+        }
+        if (msg.type === "cc_list_dir") {
+            const requestId = msg.requestId;
+            const reqPath = msg.path;
+            const listing = await deps.listDir(reqPath);
+            deps.send({
+                type: "cc_dir_result",
+                requestId,
+                path: listing.path,
+                parent: listing.parent,
+                entries: listing.entries,
+                error: listing.error,
+            });
+            return;
+        }
+        if (msg.type === "cc_read_file") {
+            const requestId = msg.requestId;
+            const reqPath = msg.path;
+            const cwd = msg.cwd;
+            const maxBytes = Number(msg.maxBytes);
+            const preview = reqPath
+                ? await (deps.readFilePreview ?? readFilePreview)({
+                    path: reqPath,
+                    cwd,
+                    maxBytes: Number.isFinite(maxBytes) ? maxBytes : undefined,
+                })
+                : {
+                    path: "",
+                    resolvedPath: "",
+                    name: "",
+                    kind: "unsupported",
+                    mimeType: "application/octet-stream",
+                    sizeBytes: 0,
+                    mtimeMs: 0,
+                    truncated: false,
+                    error: "missing_path",
+                };
+            deps.send({
+                type: "cc_file_result",
+                requestId,
+                ...preview,
+            });
+            return;
+        }
+        // cc_watch_start/stop are the cloud's subscription-gate frames (sent on the
+        // first/last SSE subscriber) — aliases of the phone's explicit cc_watch /
+        // cc_unwatch. Both drive the same watch manager.
+        if (msg.type === "cc_watch" || msg.type === "cc_watch_start") {
+            const sessionId = msg.sessionId;
+            if (typeof sessionId === "string" && sessionId) {
+                await deps.watch?.(sessionId);
+                deps.reemitTurn?.(sessionId);
+            }
+            return;
+        }
+        if (msg.type === "cc_unwatch" || msg.type === "cc_watch_stop") {
+            const sessionId = msg.sessionId;
+            if (typeof sessionId === "string" && sessionId)
+                deps.unwatch?.(sessionId);
+            return;
+        }
+        if (msg.type === "cc_list_skills") {
+            const requestId = msg.requestId;
+            const cwd = msg.cwd;
+            const listing = await deps.listSkills(cwd);
+            deps.send({
+                type: "cc_skills_result",
+                requestId,
+                skills: listing.skills,
+                commands: listing.commands,
+                error: listing.error,
+            });
+            return;
+        }
+        if (msg.type === "cc_refresh_sessions") {
+            const requestId = msg.requestId;
+            if (typeof requestId === "string" && requestId) {
+                await deps.refreshSessions?.(requestId);
+            }
+            return;
+        }
+        // heartbeat_ack and anything else: ignore.
+    };
+}
+export function startBridge(opts) {
+    const log = opts.onLog ?? ((l) => console.log(`[cc-bridge] ${l}`));
+    const interval = opts.snapshotIntervalMs ?? 15000;
+    let ws = null;
+    // E2E transport seam: an EnvelopeCodec wraps outbound content frames and
+    // unwraps inbound encrypted frames. When e2eEnabled is false (the default),
+    // both encryptOutbound and decryptInbound are identity functions — zero
+    // behavior change for existing deployments.
+    const e2eEnabled = opts.e2eEnabled === true;
+    const keyStore = new SessionKeyStore(keychainIdentityStore());
+    const codec = new EnvelopeCodec(keyStore, () => e2eEnabled);
+    // Track which sessionIds have already had their CEK uploaded to the cloud so
+    // we only POST /session-keys once per session (re-upload on peer-set change
+    // is a future follow-up — see TODO below).
+    const cekUploadedSessions = new Set();
+    /**
+     * Upload wrapped CEKs for any sessions not yet registered with the cloud.
+     * Best-effort: never throws or crashes the bridge.
+     *
+     * TODO(e2e follow-up): re-upload when the peer set changes (e.g. a new phone
+     * logs in after sessions already exist). Currently a session's CEK is only
+     * uploaded once; new devices that join later will not have a wrapped copy
+     * until the session rotates or the bridge restarts.
+     */
+    async function uploadNewSessionCeks(sessions) {
+        if (!e2eEnabled || !opts.bridgeId)
+            return;
+        const newIds = sessions
+            .map((s) => s.sessionId)
+            .filter((id) => !cekUploadedSessions.has(id));
+        if (newIds.length === 0)
+            return;
+        const cloudBase = cloudHttpBaseFromWsUrl(opts.url);
+        const enginePath = engine === "codex" ? "codex" : "cc";
+        // Fetch peer device public keys (phones / other bridges registered to this account).
+        let peers = [];
+        try {
+            const res = await fetch(`${cloudBase}/api/v1/${enginePath}/peer-keys?exclude=${encodeURIComponent(opts.bridgeId)}`, {
+                headers: { authorization: `Bearer ${opts.token}` },
+            });
+            if (res.ok) {
+                const body = (await res.json());
+                peers = body.peers ?? [];
+            }
+            else {
+                log(`e2e peer-keys fetch failed (${res.status}) — skipping CEK upload for ${newIds.length} session(s)`);
+                return;
+            }
+        }
+        catch (err) {
+            log(`e2e peer-keys fetch error: ${err.message}`);
+            return;
+        }
+        if (peers.length === 0) {
+            // No peers yet — mark sessions as uploaded (CEK still generated & cached
+            // by keyStore.cekFor so outbound encryption works immediately). When a peer
+            // registers later they get the CEK via their own device-keys lookup path.
+            for (const id of newIds)
+                cekUploadedSessions.add(id);
+            return;
+        }
+        // Upload CEKs for each new session.
+        for (const sessionId of newIds) {
+            try {
+                // wrapForDevices also creates the CEK if it doesn't exist yet.
+                const wrapped = keyStore.wrapForDevices(sessionId, peers.map((p) => p.publicKey));
+                // zip: wrapForDevices returns {deviceKey: pubB64, wrappedCek} — map back to deviceId.
+                const pubToDeviceId = new Map(peers.map((p) => [p.publicKey, p.deviceId]));
+                const keys = wrapped.map((w) => ({
+                    deviceId: pubToDeviceId.get(w.deviceKey) ?? w.deviceKey,
+                    wrappedCek: w.wrappedCek,
+                }));
+                const res = await fetch(`${cloudBase}/api/v1/${enginePath}/session-keys`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        authorization: `Bearer ${opts.token}`,
+                    },
+                    body: JSON.stringify({ sessionId, keys }),
+                });
+                if (res.ok) {
+                    cekUploadedSessions.add(sessionId);
+                    log(`e2e CEK uploaded for session ${sessionId} (${peers.length} peer(s))`);
+                }
+                else {
+                    const body = await res.text().catch(() => "");
+                    log(`e2e session-keys POST failed (${res.status}): ${body}`);
+                }
+            }
+            catch (err) {
+                log(`e2e CEK upload error for ${sessionId}: ${err.message}`);
+            }
+        }
+    }
+    // Single outbound seam: ALL content/data frames flow through sendFrame so
+    // the codec can encrypt them. Terminal frames (cc_term_*) and cc_hello pass
+    // through as well — codec returns them unchanged (default case in switch).
+    // Send only when the socket is actually OPEN. A frame fired while the socket
+    // is CONNECTING / mid-reconnect (mirror PTY output, a queued cloud frame, the
+    // heartbeat) would otherwise throw "WebSocket is not open: readyState 0" and
+    // crash the whole bridge process — which launchd restarts straight back into
+    // the same CONNECTING window, i.e. a crash loop that reads as a real outage on
+    // the phone. Dropping the frame is correct: snapshots/watches reconcile on the
+    // next OPEN, and the cloud relay is best-effort for these ephemeral frames.
+    function sendFrame(m) {
+        const f = codec.encryptOutbound(m);
+        if (ws?.readyState === WebSocket.OPEN)
+            ws.send(JSON.stringify(f));
+    }
+    const safeSend = (m) => sendFrame(m);
+    let snapTimer = null;
+    let hbTimer = null;
+    // Last time the cloud acked our heartbeat. The watchdog in hbTimer terminates a
+    // zombie (half-open) connection when this goes stale — the TCP "close" that
+    // would normally trigger reconnect never fires on sleep/wake, NAT/firewall
+    // silent drops, or a hung TUN dataplane.
+    let lastHeartbeatAck = Date.now();
+    let lastJson = "";
+    let stopped = false;
+    let backoff = 1000;
+    let shellStarted = false; // local shell is started once, survives reconnects
+    let rl = null;
+    let mirrorStarted = false; // pty mirror is started once, survives reconnects
+    let mirrorRef = null;
+    let mirrorTermId = "";
+    // Hub daemon: multiplexes many local shells onto this one cloud connection.
+    let hub = null;
+    let hubServer = null;
+    // Engine-aware transcript source: a codex bridge reads/tails rollout files
+    // under ~/.codex/sessions (its own line format); claude reads project jsonl.
+    const engine = opts.engine ?? "claude";
+    const isCodex = engine === "codex";
+    const rawReadTranscriptFn = isCodex
+        ? readCodexTranscript
+        : readFullTranscript;
+    const mediaUploader = createBridgeMediaUploader({
+        bridgeUrl: opts.url,
+        token: opts.token,
+        engine,
+        e2eEnabled,
+        cekProvider: (sessionId) => {
+            if (!e2eEnabled)
+                return null;
+            // cekFor is get-or-create; only return a CEK if one already exists for
+            // this session (it will have been created by uploadNewSessionCeks when the
+            // snapshot was pushed). Calling cekFor here unconditionally would create a
+            // dangling CEK that was never uploaded to the cloud, making the phone
+            // unable to decrypt.  hasCek guards that: if the session hasn't gone
+            // through the CEK-upload flow yet, upload unencrypted.
+            return keyStore.hasCek(sessionId) ? keyStore.cekFor(sessionId) : null;
+        },
+    });
+    async function hydrateMedia(entries, sessionId) {
+        try {
+            return await hydrateTranscriptMedia(entries, mediaUploader, sessionId);
+        }
+        catch (err) {
+            log(`media hydration failed: ${err.message}`);
+            return entries;
+        }
+    }
+    const readTranscriptFn = async (sessionId) => {
+        const entries = await rawReadTranscriptFn(sessionId);
+        return entries ? hydrateMedia(entries, sessionId) : null;
+    };
+    const adapterFactory = engine === "codex" ? createCodexAdapter : createClaudeAdapter;
+    // PTY turn-activity probe: watches wrapper-run terminals' output for the
+    // engine TUI's "running marker" (e.g. "esc to interrupt") and emits
+    // cc_event{kind:"term_turn", payload:{running}} transitions. Critically it
+    // covers the Esc-before-output abort the session jsonl NEVER records —
+    // running:false after 8s of marker silence stops the phone's spinner.
+    const turnProbe = createTurnProbe({
+        markers: adapterFactory().runningMarkers,
+        emit: (m) => sendFrame(m),
+    });
+    const promptDetector = createPromptDetector({
+        emit: (m) => sendFrame(m),
+    });
+    function injectTermInput(termId, data) {
+        if (hub && hub.activeTermIds().includes(termId)) {
+            hub.handleCloud({ type: "cc_term_input", termId, data });
+        }
+        else if (termId === mirrorTermId) {
+            mirrorRef?.writeInput(data);
+        }
+    }
+    // Transcript push: followers survive WS reconnects. A frame fired while the
+    // link is down is dropped — but the send reports that (returns false) so a
+    // transcript_append rolls back its tail state and the next poke re-emits it
+    // (transcript-watcher.ts); the phone also self-heals via the per-frame `total`
+    // cursor and the watch_ok{entryCount} heartbeat on the next re-watch.
+    const watchMgr = createWatchManager((m) => {
+        if (ws?.readyState === WebSocket.OPEN) {
+            sendFrame(m);
+            return true;
+        }
+        return false;
+    }, {
+        log,
+        findFile: isCodex ? findCodexSessionFile : undefined,
+        parse: isCodex ? parseCodexTranscript : undefined,
+        transform: hydrateMedia,
+    });
+    let handler;
+    // §4.3: a binding revocation (a `*_bridge_revoked` frame OR a 4012 close) is
+    // TERMINAL — stop reconnecting, print the pinned message, and let the CLI clear
+    // the local token + bridgeId. Idempotent (frame and 4012 close often both fire).
+    const revokedFrameType = engine === "codex" ? "codex_bridge_revoked" : "cc_bridge_revoked";
+    const updateFrameType = engine === "codex" ? "codex_update" : "cc_update";
+    let terminalRevokeHandled = false;
+    function handleTerminalRevoke() {
+        if (terminalRevokeHandled)
+            return;
+        terminalRevokeHandled = true;
+        stopped = true; // suppress reconnect backoff in ws.on("close")
+        log("This Mac was removed from your Nexting account. Re-run the installer to reconnect.");
+        try {
+            opts.onTerminalRevoke?.();
+        }
+        catch {
+            /* clearing config is best-effort */
+        }
+    }
+    const proxyAgent = proxyAgentFromEnv();
+    // v2 remote-control: owns live engine children for attached sessions.
+    const bin = engine === "codex" ? resolveCodexBin() : resolveClaudeBin();
+    log(`${engine} binary: ${bin}`);
+    if (proxyAgent)
+        log(`proxying WS via ${process.env.HTTPS_PROXY ?? process.env.ALL_PROXY ?? "env proxy"}`);
+    // Device-tool MCP proxy wiring: every spawned engine child gets a per-session
+    // `pinclaw-device` MCP server pointed at the cloud, authenticated with the
+    // bridge's own pbt agent-bus token (the cloud `verifyBusToken`s it back to this
+    // userId; the /cc/* vs /codex/* route + cx:-scope select the engine). The cloud
+    // HTTP base is derived from the WS connect url. No token → no device tools
+    // (omit mcp), but the bridge always has a token to even connect, so this is set.
+    const mcpWiring = opts.token
+        ? { cloudUrl: cloudHttpBaseFromWsUrl(opts.url), busToken: opts.token }
+        : undefined;
+    // Engine children inherit this process's env PLUS opts.engineEnv (proxy/locale
+    // the launchd daemon doesn't have but the user's terminal claude relies on).
+    const engineSpawn = opts.engineEnv && Object.keys(opts.engineEnv).length
+        ? (command, args, o) => nodeSpawn(command, args, {
+            cwd: o.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, ...opts.engineEnv },
+        })
+        : realSpawn;
+    // Egress audit: spell out exactly where a phone-spawned engine child's API
+    // traffic exits. Mixing the user's account across a residential-proxy exit
+    // (terminal) and a direct region-blocked exit (a mis-configured bridge) is an
+    // account-ban risk, so this MUST be loud and verifiable. A set `https_proxy`
+    // also fails CLOSED (a dead proxy errors the request; it never silently falls
+    // back to direct).
+    {
+        const ep = opts.engineEnv ?? {};
+        const proxy = ep.https_proxy || ep.HTTPS_PROXY || ep.all_proxy || ep.ALL_PROXY;
+        if (proxy) {
+            const redacted = String(proxy).replace(/\/\/[^@/]*@/, "//***@");
+            log(`engine egress: PROXIED via ${redacted}${ep.TZ ? ` TZ=${ep.TZ}` : ""} — mirrors the terminal; fails closed`);
+        }
+        else {
+            log(`engine egress: DIRECT (no engineEnv proxy). Region-blocked APIs (e.g. Anthropic from CN) will 403; set config.engineEnv to mirror your terminal's exit`);
+        }
+    }
+    const attachMgr = createAttachManager({
+        send: safeSend,
+        spawn: engineSpawn,
+        adapterFactory,
+        engine,
+        mcp: mcpWiring,
+    });
+    if (opts.hub) {
+        hub = createHub({
+            // Guard readyState: a shell can register while the cloud WS is still
+            // CONNECTING / mid-reconnect; ws.send() throws if not OPEN. Drop here and
+            // rely on resyncToCloud() (on open) to re-announce every term.
+            onCloudSend: (m) => {
+                // Feed the turn probe BEFORE the readyState guard — probe state must
+                // keep tracking pty output even while the cloud link is down.
+                if (m.type === "cc_term_hello") {
+                    turnProbe.noteTermHello(String(m.termId), typeof m.sessionId === "string" ? m.sessionId : undefined);
+                }
+                else if (m.type === "cc_term_output") {
+                    turnProbe.noteOutput(String(m.termId), String(m.data ?? ""));
+                    promptDetector.noteOutput(String(m.termId), String(m.data ?? ""));
+                }
+                else if (m.type === "cc_term_bye") {
+                    turnProbe.noteTermBye(String(m.termId));
+                    promptDetector.noteTermBye(String(m.termId));
+                }
+                sendFrame(m);
+            },
+        });
+        hubServer = startHubServer(hub, opts.hub.socketPath, log);
+    }
+    // Codex session lists come from the long-lived read-only thread/list child
+    // (origin/openIn/appChat/titles); on any failure it returns null and we fall
+    // back to the disk scan so the snapshot never goes dark.
+    const codexThreadSource = isCodex ? createCodexThreadSource({ log }) : null;
+    async function discoverForEngine() {
+        if (engine !== "codex")
+            return discoverSessions();
+        const viaRpc = await codexThreadSource?.listSessions();
+        if (viaRpc)
+            return viaRpc;
+        // Disk-scan fallback: apply the same probe-session filter.
+        return (await discoverCodexSessions()).filter((s) => s.cwd !== CODEX_PROBE_CWD);
+    }
+    // Near-realtime snapshots: watch the engine's session-file root so a session
+    // created/updated in a terminal reaches the cloud (and the phone's list)
+    // within ~2s instead of waiting for the 15s sweep. pushSnapshot's
+    // diff-skip-unchanged makes spurious fs events free; FS_MIN_GAP_MS caps the
+    // disk-scan rate while a session is streaming output.
+    const FS_DEBOUNCE_MS = 1500;
+    const FS_MIN_GAP_MS = 5000;
+    const sessionsRoot = isCodex
+        ? path.join(os.homedir(), ".codex", "sessions")
+        : path.join(os.homedir(), ".claude", "projects");
+    let fsWatcher = null;
+    let codexStateWatcher = null;
+    let fsDebounce = null;
+    let codexStateDebounce = null;
+    let lastFsPush = 0;
+    try {
+        fsWatcher = fs.watch(sessionsRoot, { recursive: true }, (_ev, filename) => {
+            if (filename && !String(filename).endsWith(".jsonl"))
+                return;
+            if (fsDebounce)
+                clearTimeout(fsDebounce);
+            const wait = Math.max(FS_DEBOUNCE_MS, FS_MIN_GAP_MS - (Date.now() - lastFsPush));
+            fsDebounce = setTimeout(() => {
+                fsDebounce = null;
+                lastFsPush = Date.now();
+                pushSnapshot();
+            }, wait);
+        });
+        log(`watching ${sessionsRoot} for session changes`);
+    }
+    catch (e) {
+        // Root missing (engine never run) → the 15s sweep still covers us.
+        log(`session-root watch unavailable: ${e.message}`);
+    }
+    if (isCodex) {
+        try {
+            const codexRoot = path.join(os.homedir(), ".codex");
+            codexStateWatcher = fs.watch(codexRoot, (_ev, filename) => {
+                if (!isCodexStateFileChange(filename))
+                    return;
+                if (codexStateDebounce)
+                    clearTimeout(codexStateDebounce);
+                codexStateDebounce = setTimeout(() => {
+                    codexStateDebounce = null;
+                    pushSnapshot();
+                }, 900);
+            });
+            log(`watching ${codexRoot} for Codex sidebar state changes`);
+        }
+        catch (e) {
+            log(`codex-state watch unavailable: ${e.message}`);
+        }
+    }
+    async function pushSnapshot(force = false, requestId) {
+        if (ws?.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            const discovered = await discoverForEngine();
+            const sessions = stampControllable(discovered, new Set(attachMgr.controllableIds()));
+            const frame = buildSnapshot(sessions);
+            if (requestId)
+                frame.requestId = requestId;
+            const json = JSON.stringify(frame);
+            if (!force && json === lastJson)
+                return; // skip unchanged
+            if (!requestId)
+                lastJson = json;
+            sendFrame(frame);
+            const running = sessions.filter((s) => s.status === "running").length;
+            log(`snapshot pushed: ${sessions.length} sessions (${running} running)`);
+            // E2E: upload wrapped CEKs for any sessions the cloud hasn't seen yet.
+            // Fire-and-forget: errors are logged inside, never bubble up here.
+            uploadNewSessionCeks(sessions).catch(() => { });
+        }
+        catch (e) {
+            log(`snapshot error: ${e.message}`);
+        }
+    }
+    handler = makeBridgeHandler({
+        send: safeSend,
+        readTranscript: (id) => readTranscriptFn(id),
+        listDir: (p) => listDir(p),
+        readFilePreview: (input) => readFilePreview(input),
+        // Codex uses the same skills protocol shape: prompts are commands and
+        // SKILL.md files are skills, with cwd scoping project-local skills.
+        listSkills: (c) => isCodex ? listCodexPrompts(undefined, { cwd: c }) : listSkills(c),
+        refreshSessions: (requestId) => pushSnapshot(true, requestId),
+        watch: (id) => watchMgr.watch(id),
+        unwatch: (id) => watchMgr.unwatch(id),
+        reemitTurn: (id) => turnProbe.reemitForSession(id),
+        onSessionComplete: async (sessionId, result) => {
+            // Forward session completion to the cloud via the cloud message path.
+            sendFrame({ type: "cc_completion", sessionId, result });
+        },
+    });
+    // §China-resilience: build the ordered dial-target list and escalate through it
+    // on consecutive failures. Hosts first (normal DNS / a CF-proxied ingress),
+    // then raw-IP fallbacks for the primary host with SNI+Host pinned so TLS still
+    // validates against the real cert. `dialAttempt` advances on each close and
+    // resets to 0 on a successful open, so a recovered DNS path is always retried
+    // first next cycle.
+    const primaryHost = (() => {
+        try {
+            return new URL(opts.url).hostname;
+        }
+        catch {
+            return "";
+        }
+    })();
+    const endpoints = opts.endpoints && opts.endpoints.length ? opts.endpoints : [opts.url];
+    const fallbackIps = (opts.fallbackIps ?? []).filter(Boolean);
+    let dialAttempt = 0;
+    function dialTargets() {
+        const out = [];
+        const base = proxyAgent
+            ? { agent: proxyAgent }
+            : {};
+        for (const ep of endpoints) {
+            out.push({
+                label: ep,
+                wsUrl: `${ep}?token=${encodeURIComponent(opts.token)}`,
+                wsOpts: base,
+            });
+        }
+        for (const ip of fallbackIps) {
+            let ipUrl = "";
+            try {
+                const u = new URL(opts.url);
+                u.host = ip;
+                ipUrl = u.toString();
+            }
+            catch {
+                continue;
+            }
+            out.push({
+                label: `${ip} (SNI ${primaryHost})`,
+                wsUrl: `${ipUrl}?token=${encodeURIComponent(opts.token)}`,
+                // Dial the IP directly but present the real hostname for SNI + Host so the
+                // TLS cert validates and the cloud's vhost routing still matches.
+                wsOpts: {
+                    ...base,
+                    servername: primaryHost,
+                    headers: { Host: primaryHost },
+                },
+            });
+        }
+        return out;
+    }
+    function connect() {
+        if (stopped)
+            return;
+        const targets = dialTargets();
+        const target = targets[Math.min(dialAttempt, targets.length - 1)];
+        ws = new WebSocket(target.wsUrl, target.wsOpts);
+        ws.on("open", async () => {
+            backoff = 1000;
+            dialAttempt = 0; // recovered — prefer the primary DNS/CF path next cycle
+            lastHeartbeatAck = Date.now();
+            const peerIp = (ws?._socket
+                ?.remoteAddress ?? "").replace(/^::ffff:/, "");
+            if (peerIp) {
+                try {
+                    opts.onConnectedIp?.(peerIp);
+                }
+                catch {
+                    /* persistence is best-effort */
+                }
+            }
+            log(`connected to ${target.label}${peerIp ? ` [${peerIp}]` : ""}`);
+            ws.send(JSON.stringify({
+                type: "cc_hello",
+                host: os.hostname(),
+                machineName: os.hostname(),
+                version: VERSION,
+                engine,
+                ...(opts.bridgeId ? { bridgeId: opts.bridgeId } : {}),
+                ...(e2eEnabled
+                    ? {
+                        e2ePublicKey: keyStore.publicKeyB64(),
+                        e2eDeviceId: opts.bridgeId ?? "",
+                    }
+                    : {}),
+            }));
+            // Publish device public key to cloud so the phone can fetch it for E2E
+            // key agreement. Best-effort: a failed publish must NOT crash the bridge.
+            if (e2eEnabled && opts.bridgeId) {
+                const cloudBase = cloudHttpBaseFromWsUrl(opts.url);
+                const enginePath = engine === "codex" ? "codex" : "cc";
+                fetch(`${cloudBase}/api/v1/${enginePath}/device-keys`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        authorization: `Bearer ${opts.token}`,
+                    },
+                    body: JSON.stringify({
+                        deviceId: opts.bridgeId,
+                        deviceKind: "bridge",
+                        publicKey: keyStore.publicKeyB64(),
+                        label: os.hostname(),
+                    }),
+                }).catch((err) => {
+                    log(`e2e device-key publish failed: ${err.message}`);
+                });
+            }
+            pushSnapshot(true);
+            // Re-announce hub terminals so any that registered while the cloud link was
+            // down/connecting are (re)created cloud-side.
+            hub?.resyncToCloud();
+            snapTimer = setInterval(() => pushSnapshot(), interval);
+            hbTimer = setInterval(() => {
+                // Zombie/half-open detection: the cloud acks every heartbeat
+                // (heartbeat_ack). No ack for >45s ≈ a dead link — force-close it so
+                // ws.on("close") runs the reconnect. Without this the bridge sits
+                // "connected" but dead until manually restarted (sleep/wake, NAT silent
+                // drop, hung TUN dataplane — the TCP close never fires). Tightened from
+                // 70s→45s (heartbeat 30s→20s) so a half-dead link recovers within ~45s
+                // instead of leaving the phone red/un-sendable for over a minute. The
+                // cloud also runs its own ws-level ping/pong now, so both ends detect a
+                // dead socket symmetrically.
+                if (Date.now() - lastHeartbeatAck > 45000) {
+                    log("heartbeat ack timeout — terminating dead connection to reconnect");
+                    try {
+                        ws?.terminate();
+                    }
+                    catch {
+                        /* close handler will reconnect */
+                    }
+                    return;
+                }
+                safeSend({ type: "heartbeat" });
+            }, 20000);
+            // Start the phone-controllable local terminal shell once (the `run` command).
+            if (opts.localShell && !shellStarted) {
+                shellStarted = true;
+                const shell = startLocalShell({
+                    attachMgr,
+                    sessionId: opts.localShell.sessionId,
+                    cwd: opts.localShell.cwd,
+                    write: (s) => process.stdout.write(s),
+                });
+                rl = readline.createInterface({ input: process.stdin });
+                rl.on("line", (l) => shell.onLine(l));
+                log(`local shell attached (session=${opts.localShell.sessionId})`);
+                // Refresh the snapshot so the new controllable session is visible immediately.
+                pushSnapshot(true);
+            }
+            // Start the pty terminal mirror once (the `mirror` command).
+            if (opts.mirror && !mirrorStarted) {
+                mirrorStarted = true;
+                // Dynamic import keeps the native node-pty dep out of non-mirror paths.
+                const { realSpawnPty } = await import("./pty-spawn.js");
+                const { createMirror } = await import("./pty-mirror.js");
+                const cwd = opts.mirror.cwd;
+                const termId = `${process.pid}-${cwd.replace(/[^a-zA-Z0-9]/g, "-")}`;
+                mirrorTermId = termId;
+                const cols = process.stdout.columns || 80;
+                const rows = process.stdout.rows || 24;
+                sendFrame({
+                    type: "cc_term_hello",
+                    termId,
+                    cwd,
+                    title: opts.mirror.command.split("/").pop() ?? "claude",
+                    cols,
+                    rows,
+                });
+                mirrorRef = createMirror({
+                    spawnPty: realSpawnPty,
+                    command: opts.mirror.command,
+                    args: opts.mirror.args,
+                    cwd,
+                    cols,
+                    rows,
+                    onLocal: (d) => process.stdout.write(d),
+                    onOutput: (d) => {
+                        const data = Buffer.from(d, "utf8").toString("base64");
+                        promptDetector.noteOutput(termId, data);
+                        safeSend({ type: "cc_term_output", termId, data });
+                    },
+                    onExit: () => {
+                        promptDetector.noteTermBye(termId);
+                        safeSend({ type: "cc_term_bye", termId });
+                        process.exit(0);
+                    },
+                });
+                if (process.stdin.isTTY)
+                    process.stdin.setRawMode(true);
+                process.stdin.on("data", (b) => mirrorRef?.writeInput(b.toString("utf8")));
+                process.stdout.on("resize", () => mirrorRef?.resize(process.stdout.columns || 80, process.stdout.rows || 24));
+                log(`mirror attached (term=${termId})`);
+            }
+        });
+        ws.on("message", (data) => {
+            let msg;
+            try {
+                msg = JSON.parse(data.toString());
+            }
+            catch {
+                return;
+            }
+            // Heartbeat liveness: the cloud acks every heartbeat. Recorded here (connect
+            // scope) so the zombie-connection watchdog in hbTimer can see it.
+            if (msg.type === "heartbeat_ack") {
+                lastHeartbeatAck = Date.now();
+                return;
+            }
+            // §4.3 TERMINAL: a binding-revoked frame stops reconnect + clears config.
+            // The cloud follows it with a 4012 close (handled in ws.on("close")).
+            if (msg.type === revokedFrameType) {
+                handleTerminalRevoke();
+                return;
+            }
+            // Cloud push-update signal: this bridge reported an old version on hello.
+            // Trigger a one-shot self-update + relaunch now (safe — nothing attached
+            // at connect time) so a published release lands on the next reconnect.
+            if (msg.type === updateFrameType) {
+                try {
+                    opts.onUpdateSignal?.();
+                }
+                catch {
+                    /* self-update is best-effort */
+                }
+                return;
+            }
+            // Hub daemon: route terminal down-frames to the right shell.
+            if (hub &&
+                (msg.type === "cc_term_input" ||
+                    msg.type === "cc_term_resize" ||
+                    msg.type === "cc_term_refresh")) {
+                hub.handleCloud(msg);
+                return;
+            }
+            // Single-mirror process: route down-frames to its pty.
+            if (msg.type === "cc_term_input" && msg.termId === mirrorTermId) {
+                mirrorRef?.writeInput(msg.data);
+                return;
+            }
+            if (msg.type === "cc_term_resize" && msg.termId === mirrorTermId) {
+                mirrorRef?.resize(msg.cols, msg.rows);
+                return;
+            }
+            if (msg.type === "cc_term_refresh" && msg.termId === mirrorTermId) {
+                mirrorRef?.refresh();
+                return;
+            }
+            if (msg.type === "cc_term_prompt_answer") {
+                const termId = String(msg.termId ?? "");
+                const seq = promptDetector.answer(termId, String(msg.promptId ?? ""), Number(msg.optionIndex));
+                if (seq) {
+                    for (const key of seq)
+                        injectTermInput(termId, key);
+                }
+                return;
+            }
+            // Single inbound seam: decrypt content fields of cc_send/cc_answer when
+            // the field IS an envelope and we hold the CEK. Passthrough for all other
+            // frame types and when E2E is off — safe for unencrypted phone clients.
+            msg = codec.decryptInbound(msg);
+            handler(msg);
+            attachMgr.handle(msg);
+        });
+        ws.on("close", (code) => {
+            // §4.3: 4012 binding_revoked is TERMINAL — no reconnect, clear config.
+            // (4003 invalid-token and transient/network closes still retry below.)
+            if (code === 4012)
+                handleTerminalRevoke();
+            cleanup();
+            if (stopped)
+                return;
+            // Escalate to the next dial target (next endpoint, then raw-IP fallbacks)
+            // so a persistent DNS/TLS failure on the primary host rotates onto a path
+            // that works. Reset to 0 happens on the next successful open.
+            dialAttempt++;
+            log(`disconnected — retrying in ${backoff}ms`);
+            setTimeout(connect, backoff);
+            // Cap at 10s (was 30s): after a transient outage the bridge should be back
+            // within ~10s of the network recovering, not up to 30s.
+            backoff = Math.min(backoff * 2, 10000);
+        });
+        ws.on("error", (e) => log(`ws error: ${e.message}`));
+    }
+    function cleanup() {
+        if (snapTimer)
+            clearInterval(snapTimer);
+        if (hbTimer)
+            clearInterval(hbTimer);
+        snapTimer = hbTimer = null;
+        // On a transient disconnect, kill only remote-attached children; the local
+        // shell (if any) survives so the user's terminal session isn't dropped.
+        attachMgr.stopRemote();
+        // Watch followers SURVIVE a transient disconnect (their emits are dropped
+        // while the link is down) — the cloud re-sends cc_watch_start on reconnect
+        // and the phone's watch_ok{entryCount} heartbeat reconciles any gap.
+    }
+    connect();
+    return {
+        stop: () => {
+            stopped = true;
+            // Cleanly deregister the mirror so it doesn't linger as a ghost terminal
+            // (covers Ctrl-C / SIGTERM exit, not just the claude child exiting).
+            if (mirrorTermId) {
+                try {
+                    sendFrame({ type: "cc_term_bye", termId: mirrorTermId });
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            mirrorRef?.stop();
+            cleanup();
+            attachMgr.stopAll(); // full teardown incl. the local shell on real exit
+            watchMgr.stopAll();
+            turnProbe.stop();
+            promptDetector.stop();
+            codexThreadSource?.stop();
+            if (fsDebounce)
+                clearTimeout(fsDebounce);
+            if (codexStateDebounce)
+                clearTimeout(codexStateDebounce);
+            fsWatcher?.close();
+            fsWatcher = null;
+            codexStateWatcher?.close();
+            codexStateWatcher = null;
+            hubServer?.close();
+            hubServer = null;
+            rl?.close();
+            rl = null;
+            ws?.close();
+        },
+    };
+}