@yolo-labs/yolobridge 0.28.0 → 0.30.0

package/dist/api-client.js

@@ -199,20 +199,6 @@ export async function openStream(cfg, workspaceId, attachmentId) {
  * report fails is still a perfectly good daemon; the tile simply falls back to
  * the cloud relay, which is slower and works.
  */
-export async function reportLocalEndpoint(cfg, workspaceId, attachmentId, url, secret) {
-    const fetchImpl = cfg.fetchImpl ?? fetch;
-    try {
-        const res = await fetchImpl(`${base(cfg)}/v1/workspaces/${workspaceId}/yolobridge/attach/${attachmentId}/local-endpoint`, {
-            method: 'POST',
-            headers: { ...authHeaders(cfg), 'Content-Type': 'application/json' },
-            body: JSON.stringify({ url, secret }),
-        });
-        return res.ok;
-    }
-    catch {
-        return false;
-    }
-}
 export async function postHeartbeat(cfg, workspaceId, attachmentId) {
     const body = await postEvent(cfg, workspaceId, { attachmentId, type: 'heartbeat' });
     return Boolean(body?.recorded);

package/dist/attach-cmd.js

@@ -900,20 +900,6 @@ export async function runAttachDaemon(deps) {
                                             return;
                                         }
                                         await apiClient.postHeartbeat(scopedCfg(), workspaceId, attachmentId);
-                                        // ⚠️ RE-REPORTED ON EVERY BEAT, not once at startup. The
-                                        // server holds this in memory with a TTL, so it is lost
-                                        // on a restart or a failover — and the correct recovery
-                                        // is the daemon simply saying it again a few seconds
-                                        // later, not the server persisting a secret. Best-effort:
-                                        // a failed report costs the tile its fast path, nothing
-                                        // more.
-                                        // Read LAZILY: the shell server starts inside
-                                        // `onAttached`, after these deps were built, so a
-                                        // snapshot taken at construction would always be empty.
-                                        const local = deps.localEndpoint?.();
-                                        if (local) {
-                                            await apiClient.reportLocalEndpoint(scopedCfg(), workspaceId, attachmentId, local.url, local.secret);
-                                        }
                                     }, (err) => {
                                         // The heartbeat hits the SAME boundary as the stream open
                                         // and gets the SAME 403, so it needs the same answer: a
@@ -926,19 +912,6 @@ export async function runAttachDaemon(deps) {
                                             detail: `heartbeat error: ${err instanceof Error ? err.message : String(err)}`,
                                         });
                                     }, undefined, deps.timers);
-                                    // ⚠️ REPORT THE LOCAL ENDPOINT IMMEDIATELY TOO, not only on
-                                    // the interval. Waiting ~10s means a tile opened in that
-                                    // window gets a 404 and silently downgrades to the ~200ms
-                                    // relay, while a perfectly good local server is already
-                                    // listening — and it would stay downgraded for that whole
-                                    // session. Same reasoning as the immediate heartbeat below.
-                                    // (codex P2.)
-                                    {
-                                        const local = deps.localEndpoint?.();
-                                        if (local) {
-                                            apiClient.reportLocalEndpoint(scopedCfg(), workspaceId, attachmentId, local.url, local.secret).catch(() => { });
-                                        }
-                                    }
                                     // Send one immediately so status isn't stale for the first ~10s.
                                     apiClient.postHeartbeat(scopedCfg(), workspaceId, attachmentId).catch((err) => {
                                         if (noteCredentialRejection(err))

package/dist/cli.js

@@ -35,24 +35,13 @@ import { runShare, runDeliver } from './share-cmd.js';
 import { runAllow } from './approved-paths.js';
 import { runDetach } from './detach-cmd.js';
 import { getStatus, formatStatus } from './status-cmd.js';
+import { resolveAgentBinary } from './resolve-agent-binary.js';
 import { startLocalAgent, stopLocalAgent, DEFAULT_AGENT_BIN } from './local-agent.js';
 import { runListWorkspaces, formatWorkspacesTable } from './workspaces-cmd.js';
 import { startMcpProxy, mcpUrl, SECRET_ENV_VAR } from './mcp-proxy.js';
-import { startLocalShellServer } from './local-shell-server.js';
 import { buildAgentMcpArgs } from './agent-mcp-args.js';
 const DEFAULT_API_URL = 'https://api.yolo.studio';
-const DEFAULT_WEBAPP_ORIGIN = 'https://yolo.studio';
 const DEFAULT_AUTH_URL = 'https://auth.yololabs.ai';
-/**
- * The ONE browser origin allowed to reach the local terminal server.
- *
- * ⚠️ Never a wildcard: this authorises reaching a shell on the operator's
- * machine, so it is a single exact origin. Overridable only for local
- * development against a different webapp host.
- */
-function webappOrigin() {
-    return process.env.YOLOBRIDGE_WEBAPP_ORIGIN || DEFAULT_WEBAPP_ORIGIN;
-}
 function apiUrl() {
     return process.env.YOLOBRIDGE_API_URL || DEFAULT_API_URL;
 }
@@ -338,14 +327,6 @@ async function cmdAttach(args) {
         cliVersion: readOwnVersion(),
     });
     let mcpProxyHandle;
-    /**
-     * Serves terminals on 127.0.0.1 for the tile's "open terminal".
-     *
-     * ⚠️ SEPARATE FROM THE AGENT PTY. `startLocalAgent` owns the one agent
-     * session; this owns any shells the operator opens from the workspace. They
-     * share a lifetime — both die with the attach — and nothing else.
-     */
-    let shellServerHandle;
     // argv fragment pointing the spawned agent at the local MCP proxy, or
     // `[]` when MCP isn't wired in — see `agent-mcp-args.ts`. Nothing else is
     // tracked for cleanup any more: as of 2026-08-26 `attach` writes NOTHING
@@ -356,12 +337,6 @@ async function cmdAttach(args) {
     let result;
     try {
         result = await runAttachFromDisk({
-            // Read lazily on each heartbeat — the shell server starts in
-            // `onAttached`, after this object is built, so a value here would
-            // always be undefined.
-            localEndpoint: () => (shellServerHandle
-                ? { url: shellServerHandle.url, secret: shellServerHandle.secret }
-                : undefined),
             workspaceId,
             commonApiBaseUrl: apiUrl(),
             hostLabel: attachHostInfo.hostLabel,
@@ -388,22 +363,6 @@ async function cmdAttach(args) {
                 // prompt. MCP access is an enhancement on a tile that already works
                 // without it; the local agent spawning is not optional.
                 try {
-                    // The local terminal server. Started BEFORE the agent, like the MCP
-                    // proxy, so the endpoint exists by the time the tile could ask for
-                    // it. A failure here must not stop the attach: the agent and its
-                    // tile are the point, a local terminal is an extra.
-                    try {
-                        shellServerHandle = await startLocalShellServer({ allowedOrigin: webappOrigin() });
-                        // ⚠️ THE URL, NEVER THE SECRET. This line lands in the operator's
-                        // scrollback, which is exactly where things get copied into bug
-                        // reports and pasted into chats. The secret authorises spawning a
-                        // shell on this machine; it reaches the tile over the authenticated
-                        // workspace channel and is printed nowhere.
-                        process.stdout.write(`yolo-bridge: local terminals ready at ${shellServerHandle.url} (127.0.0.1 only)\n`);
-                    }
-                    catch (err) {
-                        process.stdout.write(`yolo-bridge: local terminals unavailable (${err instanceof Error ? err.message : String(err)}) — the attach continues without them.\n`);
-                    }
                     mcpProxyHandle = await startMcpProxy({
                         apiUrl: apiUrl(),
                         getAccessToken,
@@ -507,6 +466,24 @@ async function cmdAttach(args) {
                     // Say where Ctrl+C goes BEFORE the agent takes over the screen.
                     // Without this the operator presses it expecting to quit, nothing
                     // happens, and there is no way to discover why.
+                    // ⚠️ RESOLVE THE BINARY BEFORE SPAWNING IT, so a failure can be
+                    // EXPLAINED. node-pty reports an unspawnable binary as the bare
+                    // string `posix_spawnp failed.` — no binary name, no PATH, no
+                    // remedy — which on macOS reached an operator as "failed to start
+                    // the local agent (posix_spawnp failed.)" and told them nothing
+                    // they could act on. Worse, the one fact they could see (`claude`
+                    // works when typed) argued that nothing was wrong, because a shell
+                    // alias or function resolves interactively and cannot be spawned.
+                    // This does not change WHETHER the attach fails — only whether the
+                    // operator can tell why.
+                    const resolvedBinary = resolveAgentBinary(agentBin ?? DEFAULT_AGENT_BIN, process.env);
+                    if (!resolvedBinary.ok) {
+                        process.stdout.write(`yolo-bridge: cannot start the agent — ${resolvedBinary.message}\n`);
+                        process.stdout.write('yolo-bridge: detaching...\n');
+                        stopRequested = true;
+                        await runDetach({ commonApiBaseUrl: apiUrl() }).catch(() => undefined);
+                        return;
+                    }
                     process.stdout.write('yolo-bridge: Ctrl+C goes to the agent · Ctrl-P Ctrl-Q to detach\n');
                     startLocalAgent({
                         agentBin,
@@ -579,17 +556,6 @@ async function cmdAttach(args) {
         // or a reboot, and every skipped run left a file that broke the
         // operator's own standalone `claude` in that directory. Nothing written
         // is nothing to clean up.
-        // Same "nothing left running detached" rule as the MCP proxy: a shell the
-        // operator opened from the workspace must not outlive the attach that
-        // served it. `close()` kills every session it owns.
-        if (shellServerHandle) {
-            try {
-                await shellServerHandle.close();
-            }
-            catch (err) {
-                process.stdout.write(`yolo-bridge: local terminal shutdown failed (${err instanceof Error ? err.message : String(err)}).\n`);
-            }
-        }
         if (mcpProxyHandle) {
             try {
                 await mcpProxyHandle.stop();

package/dist/resolve-agent-binary.js

@@ -0,0 +1,105 @@
+/**
+ * Can the agent binary actually be spawned, and if not, WHY?
+ *
+ * ⚠️ THE FAILURE THIS EXISTS FOR. node-pty reports an unspawnable binary as
+ * the literal string `posix_spawnp failed.` — no binary name, no PATH, no
+ * errno, no remedy. On macOS that surfaced as:
+ *
+ *     yolo-bridge: failed to start the local agent (posix_spawnp failed.), detaching...
+ *
+ * which is true, useless, and indistinguishable from half a dozen unrelated
+ * causes. The operator cannot tell whether the agent is missing, installed but
+ * not executable, or whether `attach` even looked in the right place — and the
+ * one thing they CAN see (`claude` works when they type it) argues that
+ * nothing is wrong.
+ *
+ * ⚠️ THE MACOS TRAP THIS NAMES EXPLICITLY. `claude` working in the operator's
+ * terminal does NOT mean there is a binary to spawn: a shell alias or function
+ * from `.zshrc` resolves interactively and does not exist as a file, so
+ * `posix_spawnp` cannot find it however correct the PATH looks. A message that
+ * only says "not found" invites the reply "but it IS installed", so this says
+ * where it looked and offers the escape hatch.
+ *
+ * Resolution mirrors `posix_spawnp`: a name containing a separator is a path,
+ * anything else is searched across PATH in order.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const DEFAULT_FS = fs;
+function isExecutableFile(p, io) {
+    try {
+        if (!io.statSync(p).isFile())
+            return 'no';
+    }
+    catch {
+        return 'no';
+    }
+    try {
+        io.accessSync(p, io.constants.X_OK);
+        return 'yes';
+    }
+    catch {
+        return 'not-executable';
+    }
+}
+/**
+ * Where `bin` would be spawned from, or a sentence explaining why it cannot be.
+ *
+ * The message is the whole point: it is what the operator reads instead of
+ * `posix_spawnp failed.`, so it names the binary, says where the search
+ * looked, and gives the two ways out.
+ */
+export function resolveAgentBinary(bin, env = process.env, io = DEFAULT_FS) {
+    const escapeHatch = `Point yolo-bridge at it explicitly with \`--agent /full/path/to/${bin}\` `
+        + `(or set YOLOBRIDGE_AGENT_BIN).`;
+    // An explicit path is taken at its word — no PATH search, same as execve.
+    if (bin.includes(path.sep) || bin.includes('/')) {
+        const abs = path.resolve(bin);
+        const state = isExecutableFile(abs, io);
+        if (state === 'yes')
+            return { ok: true, path: abs };
+        if (state === 'not-executable') {
+            return {
+                ok: false,
+                reason: 'not-executable',
+                message: `The agent at ${abs} exists but is not executable. \`chmod +x ${abs}\` and re-attach.`,
+            };
+        }
+        return { ok: false, reason: 'not-found', message: `No agent binary at ${abs}. ${escapeHatch}` };
+    }
+    const rawPath = env.PATH ?? '';
+    if (!rawPath.trim()) {
+        return {
+            ok: false,
+            reason: 'no-path',
+            message: `Cannot look for \`${bin}\`: PATH is empty in this process. ${escapeHatch}`,
+        };
+    }
+    const dirs = rawPath.split(path.delimiter).filter(Boolean);
+    let sawNonExecutable;
+    for (const dir of dirs) {
+        const candidate = path.join(dir, bin);
+        const state = isExecutableFile(candidate, io);
+        if (state === 'yes')
+            return { ok: true, path: candidate };
+        if (state === 'not-executable' && !sawNonExecutable)
+            sawNonExecutable = candidate;
+    }
+    if (sawNonExecutable) {
+        return {
+            ok: false,
+            reason: 'not-executable',
+            message: `Found \`${bin}\` at ${sawNonExecutable}, but it is not executable. `
+                + `\`chmod +x ${sawNonExecutable}\` and re-attach.`,
+        };
+    }
+    return {
+        ok: false,
+        reason: 'not-found',
+        message: `\`${bin}\` is not on this process's PATH (searched ${dirs.length} `
+            + `${dirs.length === 1 ? 'directory' : 'directories'}).\n`
+            + `  ⚠️ If \`${bin}\` works when you type it, it may be a shell alias or function rather than\n`
+            + `     a real binary — those cannot be spawned. Check with: type -a ${bin}\n`
+            + `  ${escapeHatch}`,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-labs/yolobridge",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "YoloBridge \u2014 local coding-agent daemon that attaches a user's own Claude Code/Codex session to a YOLO Studio workspace as a first-class tile (docs/YOLOBRIDGE_PLAN.md, build-order Phase 5).",
   "license": "MIT",
   "type": "module",

package/dist/local-shell-server.js

@@ -1,476 +0,0 @@
-/**
- * A terminal on the operator's OWN machine, served over loopback.
- *
- * This is what "open terminal" in a YoloBridge tile connects to. The browser
- * talks to `127.0.0.1` directly, so a keystroke never leaves the machine that
- * is rendering it.
- *
- * WHY NOT THE CLOUD RELAY
- * -----------------------
- * The obvious implementation routes keystrokes browser → common-api → daemon.
- * Measured from a real operator machine that is ~200ms of echo latency, to type
- * into a shell running on the same laptop as the browser. SSH on a LAN is under
- * 5ms; 200ms is where characters visibly trail your fingers. Measured over this
- * path on that same machine: **p50 6.9ms, p95 8.0ms**, and that figure includes
- * bash actually executing the command, so the transport itself is a fraction of
- * it.
- *
- * ⚠️ THIS IS NOT THE AGENT'S PTY. `local-agent.ts` owns exactly one PTY — the
- * agent `attach` spawned — and Decision Q3 ("one tile per attach") keeps it a
- * singleton. This module spawns SEPARATE shells and is a Map, because "give me
- * a terminal" is a different request from "show me the agent". Mixing them
- * would mean every glance at a running agent shares a keyboard with it.
- *
- * WHY THREE BROWSER MECHANISMS ARE HANDLED, not one — each fails differently,
- * and getting any of them wrong looks identical to "browsers refuse loopback":
- *
- *   1. MIXED CONTENT — an https page loading http:// is normally blocked;
- *      loopback is exempt as a potentially-trustworthy origin.
- *   2. CORS — cross-origin, so an explicit allow-origin. Never `*`: that would
- *      let any page on the internet reach a shell on this machine.
- *   3. PRIVATE NETWORK ACCESS — Chrome preflights public→private and requires
- *      `Access-Control-Allow-Private-Network: true` in response.
- *
- * Verified against Chrome 140 at default security settings (spike, 2026-08-28):
- * a page on https://yolo.studio reached this successfully. Firefox 153 was
- * INCONCLUSIVE headless — the fetch hung rather than being refused, most likely
- * its Local Network Access prompt with nobody present to answer it. Which is
- * why the client must treat "no answer" as a timeout and fall back, never wait
- * forever.
- *
- * ⚠️ THE BACKLOG DOES NOT RECONSTRUCT A TUI SCREEN — AND NOTHING CURRENTLY
- * NEEDS IT TO. Worth stating precisely, because the obvious next step here is
- * speculative work.
- *
- * The backlog is a byte TAIL cut at a parser-safe boundary. It cannot rebuild a
- * full-screen TUI that painted its layout once and then emitted more than
- * `BACKLOG_CHARS` of cursor-addressed updates: a viewer joining mid-session
- * would get the updates without the screen they address. The cloud path solved
- * that properly — `local-agent.ts` keeps an `@xterm/headless` mirror and serves
- * a serialized screen plus a mode `prologue` — and that dependency is already
- * here, so doing the same looks like the natural next slice.
- *
- * IT IS NOT, because no client reconnects. `openLocalTerminal` establishes the
- * stream exactly once; a stream that ends marks the session DEAD rather than
- * retrying, and the tile never reuses a session id — every mount opens a fresh
- * shell. So the replay only ever covers output produced between `/open` and
- * `/stream`, a window of milliseconds inside a single connection, where a byte
- * tail is exactly right.
- *
- * ⚠️ WHAT WOULD MAKE IT MATTER: adding session RESUMPTION — a tile that
- * reattaches to its shell across a remount, a dropped stream, or a page
- * refresh. That is a real feature and a reasonable one to want. The headless
- * mirror is a prerequisite FOR IT, not an improvement on its own; building the
- * mirror first would be solving the second half of a problem nobody has yet.
- *
- * SECURITY, deliberately narrow because this hands out shells:
- *   · bound to 127.0.0.1 ONLY — never 0.0.0.0, so it is off the local network
- *     entirely (verified: a connect to the machine's own LAN IP is refused at
- *     the TCP level, not merely firewalled);
- *   · a random secret per daemon run, compared in constant time;
- *   · one explicit allowed origin;
- *   · sessions are capped and idle-reaped, so a forgotten tab cannot leave
- *     shells accumulating forever;
- *   · PTY bytes are NEVER logged. They are the operator's live screen and
- *     include whatever they type, passwords included.
- */
-import * as http from 'node:http';
-import { randomBytes, timingSafeEqual } from 'node:crypto';
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
-/** How much recent output a late-joining viewer replays. */
-export const BACKLOG_CHARS = 64 * 1024;
-/** Shells with no viewer for this long are killed. */
-export const IDLE_REAP_MS = 5 * 60_000;
-/** Hard cap on concurrent shells from one daemon. */
-export const MAX_SESSIONS = 8;
-/** Largest single input payload accepted. */
-export const MAX_INPUT_CHARS = 8192;
-/**
- * Trim the replay buffer to a point a terminal can safely resume from.
- *
- * ⚠️ A NAIVE `slice(-N)` CORRUPTS THE SCREEN, and so does guessing. The backlog
- * is a raw PTY byte stream: an arbitrary cut can land inside a CSI, OSC or DCS
- * sequence, and a viewer that resumes there does not get a slightly-wrong
- * screen — it takes escape fragments as literal text, or applies half a mode
- * change, and stays wrong forever.
- *
- * ⚠️ AND LOOKING *FORWARD* FOR AN ESCAPE IS NOT ENOUGH — the first version of
- * this did exactly that and was wrong twice over: the introducer that put the
- * stream mid-sequence may sit BEFORE the cut where a forward scan cannot see
- * it, and a newline does not terminate an OSC string, so "cut at the next
- * newline" can land inside one. (codex P2.)
- *
- * So the parser state is actually tracked. `groundCutAt` walks a minimal VT
- * state machine and returns the first offset at or after `from` where the
- * stream is in GROUND state — no partial sequence, no partial surrogate.
- *
- * This is correct to scan from index 0 because of an invariant this function
- * maintains: **the backlog always begins in ground state**. Every trim cuts to
- * a ground offset, so the next scan starts from one.
- */
-function groundCutAt(buf, from) {
-    let state = 'ground';
-    let i = 0;
-    // Walk to `from`, tracking state; then keep walking until ground.
-    while (i < buf.length) {
-        if (i >= from && state === 'ground') {
-            const code = buf.charCodeAt(i);
-            // Never resume on the low half of a surrogate pair.
-            if (!(code >= 0xdc00 && code <= 0xdfff))
-                return i;
-        }
-        const ch = buf[i];
-        const code = buf.charCodeAt(i);
-        switch (state) {
-            case 'ground':
-                if (code === 0x1b)
-                    state = 'esc';
-                break;
-            case 'esc':
-                // `[` opens a CSI; `]`, `P`, `X`, `^`, `_` open string-terminated
-                // sequences (OSC/DCS/SOS/PM/APC).
-                if (ch === '[')
-                    state = 'csi';
-                else if (ch === ']' || ch === 'P' || ch === 'X' || ch === '^' || ch === '_')
-                    state = 'str';
-                // ⚠️ INTERMEDIATE BYTES (0x20-0x2F) DO NOT END THE SEQUENCE. `ESC ( B`
-                // — a charset designation — is three bytes, and treating `(` as the
-                // end marks the boundary before `B` as ground. Trimming there replays
-                // a bare `B` as ordinary text and silently drops the charset switch,
-                // which is precisely the "parser-safe boundary" this function promises
-                // not to do. Per ECMA-48, stay in escape until a FINAL byte
-                // (0x30-0x7E). (codex P2.)
-                else if (code >= 0x20 && code <= 0x2f) { /* intermediate — still escaping */ }
-                else
-                    state = 'ground';
-                break;
-            case 'csi':
-                // Parameters and intermediates, terminated by a final byte 0x40-0x7E.
-                if (code >= 0x40 && code <= 0x7e)
-                    state = 'ground';
-                break;
-            case 'str':
-                // BEL, or ST (ESC \). A newline does NOT end these — which is exactly
-                // what the previous newline shortcut got wrong.
-                if (code === 0x07)
-                    state = 'ground';
-                else if (code === 0x1b && buf[i + 1] === '\\') {
-                    state = 'ground';
-                    i += 1;
-                }
-                break;
-        }
-        i += 1;
-    }
-    return buf.length;
-}
-/**
- * Drop the oldest bytes, cutting only at a resumable boundary.
- *
- * The cut only ever moves FORWARD, so it can never resurrect bytes that were
- * already meant to be gone.
- */
-export function trimBacklog(buf, limit = BACKLOG_CHARS) {
-    if (buf.length <= limit)
-        return buf;
-    return buf.slice(groundCutAt(buf, buf.length - limit));
-}
-function defaultSpawn() {
-    const pty = require('node-pty');
-    return ({ cols, rows }) => pty.spawn(process.env.SHELL || (process.platform === 'win32' ? 'powershell.exe' : '/bin/bash'), [], { name: 'xterm-256color', cols, rows, cwd: process.env.HOME, env: process.env });
-}
-/**
- * Constant-time secret comparison that cannot throw on a length mismatch.
- *
- * `timingSafeEqual` throws when the buffers differ in length, and a thrown
- * comparison is both a crash and a length oracle. The length check short-
- * circuits first, which leaks only the length — already visible from the URL.
- */
-export function secretMatches(given, expected) {
-    if (typeof given !== 'string')
-        return false;
-    const a = Buffer.from(given);
-    const b = Buffer.from(expected);
-    if (a.length !== b.length)
-        return false;
-    return timingSafeEqual(a, b);
-}
-export async function startLocalShellServer(opts) {
-    const allowedOrigin = opts.allowedOrigin;
-    const spawnShell = opts.spawnShell ?? defaultSpawn();
-    const now = opts.now ?? Date.now;
-    const idleReapMs = opts.idleReapMs ?? IDLE_REAP_MS;
-    const maxSessions = opts.maxSessions ?? MAX_SESSIONS;
-    const secret = randomBytes(24).toString('hex');
-    const sessions = new Map();
-    const killSession = (s) => {
-        // ⚠️ RE-ENTRANT. `kill()` may fire `onExit` SYNCHRONOUSLY — the interface
-        // permits it and real PTYs do it — which calls straight back in here.
-        // Without this guard the second entry kills again, recursing until the
-        // stack blows. Checked BEFORE the flag is set, not after. (codex P2.)
-        if (s.exited)
-            return;
-        s.exited = true;
-        for (const v of s.viewers) {
-            try {
-                v.res.end();
-            }
-            catch { /* already gone */ }
-        }
-        s.viewers.clear();
-        try {
-            s.pty.kill();
-        }
-        catch { /* already dead */ }
-        sessions.delete(s.id);
-    };
-    /**
-     * Send one chunk to one viewer, dropping rather than queueing when it is
-     * behind. See `Viewer` for why.
-     *
-     * The loss is REPORTED when the socket recovers — a viewer that silently
-     * skipped output would render a screen that is wrong with no indication,
-     * which is worse than a visible gap. Same discipline as the cloud path's
-     * `droppedBytes`.
-     */
-    const writeToViewer = (session, v, data) => {
-        if (v.saturated) {
-            v.dropped += data.length;
-            return;
-        }
-        let ok = false;
-        try {
-            ok = v.res.write(`data: ${JSON.stringify(data)}\n\n`);
-        }
-        catch {
-            return;
-        }
-        if (ok)
-            return;
-        v.saturated = true;
-        v.res.once('drain', () => {
-            v.saturated = false;
-            if (v.dropped > 0) {
-                const n = v.dropped;
-                v.dropped = 0;
-                // Marked inline, where the gap actually happened.
-                try {
-                    v.res.write(`data: ${JSON.stringify(`\r\n\u001b[33m── ${n} bytes skipped — viewer fell behind ──\u001b[0m\r\n`)}\n\n`);
-                }
-                catch { /* gone */ }
-            }
-            // Re-seed from the retained tail so the screen is coherent again rather
-            // than resuming mid-stream after a hole.
-            try {
-                v.res.write(`data: ${JSON.stringify(session.backlog)}\n\n`);
-            }
-            catch { /* gone */ }
-        });
-    };
-    const reaper = setInterval(() => {
-        const t = now();
-        for (const s of [...sessions.values()]) {
-            // ⚠️ Only reap shells nobody is watching. A viewer that is merely quiet
-            // is still a viewer — killing on output-silence would take out an idle
-            // shell the operator is about to type into.
-            if (s.viewers.size === 0 && t - s.lastViewerAtMs > idleReapMs)
-                killSession(s);
-        }
-    }, Math.max(1000, Math.floor(idleReapMs / 4)));
-    reaper.unref?.();
-    /** CORS + Private Network Access. See this file's header for why all three. */
-    const applyCors = (req, res) => {
-        if (req.headers.origin === allowedOrigin) {
-            res.setHeader('Access-Control-Allow-Origin', allowedOrigin);
-            res.setHeader('Vary', 'Origin');
-        }
-        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
-        if (req.headers['access-control-request-private-network']) {
-            res.setHeader('Access-Control-Allow-Private-Network', 'true');
-        }
-    };
-    const server = http.createServer((req, res) => {
-        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
-        applyCors(req, res);
-        if (req.method === 'OPTIONS') {
-            res.writeHead(204);
-            res.end();
-            return;
-        }
-        // Liveness probe. Deliberately UNAUTHENTICATED and content-free: it exists
-        // so a viewer can discover whether this machine is the one running the
-        // daemon before it has any reason to hold a secret. It reveals only that
-        // something is listening, which the TCP connect already revealed.
-        if (url.pathname === '/health') {
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ ok: true, service: 'yolo-bridge-local-shell' }));
-            return;
-        }
-        if (!secretMatches(url.searchParams.get('secret'), secret)) {
-            res.writeHead(403, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'forbidden' }));
-            return;
-        }
-        if (url.pathname === '/open' && req.method === 'POST') {
-            if (sessions.size >= maxSessions) {
-                res.writeHead(429, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: `at most ${maxSessions} local terminals` }));
-                return;
-            }
-            const cols = Math.max(20, Math.min(500, Number(url.searchParams.get('cols')) || 100));
-            const rows = Math.max(5, Math.min(200, Number(url.searchParams.get('rows')) || 30));
-            const id = randomBytes(9).toString('hex');
-            let pty;
-            try {
-                pty = spawnShell({ cols, rows });
-            }
-            catch (err) {
-                // ⚠️ A THROW HERE WOULD KILL THE WHOLE DAEMON. This runs inside the
-                // HTTP request callback, so an unhandled exception takes the process
-                // down — and with it the agent PTY and every other live terminal —
-                // because one `$SHELL` pointed at a missing binary. Report it and
-                // leave everything else running. (codex P2.)
-                res.writeHead(500, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({
-                    error: 'could not start a shell',
-                    detail: err instanceof Error ? err.message : String(err),
-                }));
-                return;
-            }
-            const session = { id, pty, backlog: '', viewers: new Set(), lastViewerAtMs: now(), exited: false };
-            // ⚠️ REGISTER FIRST, SUBSCRIBE SECOND. A short-lived shell can fire
-            // `onExit` the instant the callback is attached — before `sessions.set`
-            // would have run. `killSession` would then delete nothing, and the
-            // already-dead session would be inserted afterwards, unreachable (404 on
-            // every request) yet still holding a slot against the session cap, and
-            // unremovable because `killSession` returns early once `exited` is set.
-            // A slow leak of the one resource that is capped. (codex P1.)
-            sessions.set(id, session);
-            pty.onData((data) => {
-                // ⚠️ NEVER LOG THIS. It is the operator's live screen.
-                session.backlog = trimBacklog(session.backlog + data);
-                for (const viewer of session.viewers)
-                    writeToViewer(session, viewer, data);
-            });
-            pty.onExit(() => { killSession(session); });
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ sessionId: id, cols, rows }));
-            return;
-        }
-        const session = sessions.get(url.searchParams.get('session') ?? '');
-        if (!session || session.exited) {
-            res.writeHead(404, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'no such session' }));
-            return;
-        }
-        if (url.pathname === '/stream') {
-            res.writeHead(200, {
-                'Content-Type': 'text/event-stream',
-                'Cache-Control': 'no-cache',
-                Connection: 'keep-alive',
-            });
-            // ⚠️ FLUSH THE HEADERS IMMEDIATELY. Node holds them until the first
-            // write, so a stream opened on a shell that has not printed anything yet
-            // never sends its response head at all — and the client's `fetch` hangs
-            // waiting for it, indefinitely. A fresh shell is exactly that case.
-            //
-            // An SSE comment is the standard way to do this: legal, ignored by
-            // EventSource, and it doubles as a "connected" signal the client can use
-            // to distinguish "attached and quiet" from "never got there".
-            res.write(': connected\n\n');
-            // Replay next, so a reconnecting viewer sees the screen rather than
-            // waiting for the next keypress to produce output.
-            if (session.backlog)
-                res.write(`data: ${JSON.stringify(session.backlog)}\n\n`);
-            const viewer = { res, saturated: false, dropped: 0 };
-            session.viewers.add(viewer);
-            session.lastViewerAtMs = now();
-            req.on('close', () => {
-                session.viewers.delete(viewer);
-                session.lastViewerAtMs = now();
-            });
-            return;
-        }
-        if (url.pathname === '/input' && req.method === 'POST') {
-            // ⚠️ COLLECT BYTES, DECODE ONCE. `body += chunk` decodes each Buffer
-            // independently, so a multibyte character split across a TCP chunk
-            // boundary becomes two replacement characters — silently corrupting
-            // pasted or typed Unicode, depending on how the network happened to
-            // fragment it. (codex P2.)
-            const chunks = [];
-            let size = 0;
-            req.on('data', (c) => {
-                size += c.length;
-                // Bounded before parsing: an unbounded body is a memory DoS on a
-                // process that owns the operator's shells.
-                if (size > MAX_INPUT_CHARS * 4) {
-                    req.destroy();
-                    return;
-                }
-                chunks.push(c);
-            });
-            req.on('end', () => {
-                try {
-                    const data = JSON.parse(Buffer.concat(chunks).toString('utf-8'))?.data;
-                    if (typeof data === 'string' && data.length <= MAX_INPUT_CHARS)
-                        session.pty.write(data);
-                }
-                catch { /* malformed body is not worth an error page */ }
-                res.writeHead(204);
-                res.end();
-            });
-            return;
-        }
-        if (url.pathname === '/resize' && req.method === 'POST') {
-            const cols = Number(url.searchParams.get('cols'));
-            const rows = Number(url.searchParams.get('rows'));
-            if (Number.isFinite(cols) && Number.isFinite(rows)) {
-                try {
-                    session.pty.resize(Math.max(20, Math.min(500, cols)), Math.max(5, Math.min(200, rows)));
-                }
-                catch { /* raced exit */ }
-            }
-            res.writeHead(204);
-            res.end();
-            return;
-        }
-        if (url.pathname === '/close' && req.method === 'POST') {
-            killSession(session);
-            res.writeHead(204);
-            res.end();
-            return;
-        }
-        res.writeHead(404);
-        res.end();
-    });
-    await new Promise((resolve, reject) => {
-        server.once('error', reject);
-        // ⚠️ 127.0.0.1 EXPLICITLY. Omitting the host, or using '0.0.0.0', would put
-        // a shell on the local network.
-        server.listen(0, '127.0.0.1', () => resolve());
-    });
-    const addr = server.address();
-    const port = addr.port;
-    return {
-        url: `http://127.0.0.1:${port}`,
-        port,
-        host: addr.address,
-        secret,
-        get sessionCount() { return sessions.size; },
-        async close() {
-            clearInterval(reaper);
-            for (const s of [...sessions.values()])
-                killSession(s);
-            await new Promise((resolve) => {
-                server.close(() => resolve());
-                // ⚠️ REQUIRED, not belt-and-braces. `server.close()` waits for open
-                // connections, and an SSE stream never ends on its own — that is the
-                // whole point of it. Without this, closing the daemon with a terminal
-                // open hangs forever instead of exiting.
-                server.closeAllConnections?.();
-            });
-        },
-    };
-}