@yolo-labs/yolobridge 0.1.0

package/dist/heartbeat.js

@@ -0,0 +1,31 @@
+/**
+ * Heartbeat scheduler: `POST /events {type:'heartbeat'}` every ~10s while
+ * attached (docs/YOLOBRIDGE_PLAN.md build-order step 5; matches Phase 4's
+ * 30s/90s `running`→`paused`→`stopped` staleness thresholds with margin —
+ * `common-api/src/services/yolobridge-service.ts`'s `deriveTileStatus`).
+ *
+ * Timer functions are injectable so tests drive the schedule manually
+ * (call the captured callback directly) instead of sleeping for real.
+ */
+export const defaultTimers = {
+    setInterval: (fn, ms) => setInterval(fn, ms),
+    clearInterval: (handle) => clearInterval(handle),
+};
+export const HEARTBEAT_INTERVAL_MS = 10_000;
+/**
+ * `send` is called once immediately is NOT done here — callers send an
+ * initial heartbeat themselves right after a successful `connected` frame
+ * so "attached but daemon never sent one" isn't a visible gap; this
+ * scheduler only owns the recurring tick. Errors thrown by `send` are
+ * swallowed with `onError` (a single failed heartbeat POST — e.g. a
+ * transient network blip — should not crash the daemon loop; the next
+ * tick just tries again).
+ */
+export function startHeartbeat(send, onError, intervalMs = HEARTBEAT_INTERVAL_MS, timers = defaultTimers) {
+    const handle = timers.setInterval(() => {
+        send().catch(onError);
+    }, intervalMs);
+    return {
+        stop: () => timers.clearInterval(handle),
+    };
+}

package/dist/local-agent.js

@@ -0,0 +1,437 @@
+/**
+ * Real local prompt-delivery and output-capture for `yolo-bridge attach`.
+ *
+ * docs/YOLOBRIDGE_PLAN.md's "⚠ Not yet functional" section settled the
+ * mechanism (2026-08-19): `node-pty` spawns a genuine PTY running the
+ * user's local coding agent (zero external binary dependency — already a
+ * proven pattern in this codebase, `containers/services/terminal-mux/server.js`
+ * depends on it too, just as an outer viewer around tmux rather than the
+ * core mechanism here). `@xterm/headless` mirrors the PTY's raw byte
+ * stream into a real screen-buffer model (the same engine xterm.js uses
+ * for rendering, without a DOM), giving `captureLocalAgentOutput` direct
+ * structured buffer access instead of text-scraping.
+ *
+ * Ownership model (this is the load-bearing change from the original
+ * "reach into an already-running session" framing): `startLocalAgent`
+ * SPAWNS the agent — yolo-bridge owns the PTY. The real process's stdin
+ * is piped into the PTY and the PTY's raw output is piped to the real
+ * process's stdout, so the human running `yolo-bridge attach` sees and
+ * can drive the exact same session that remote prompts land in — not a
+ * separate shadow copy.
+ *
+ * Module-level singleton: Decision Q3 in the plan is "one tile per
+ * attach" — there is only ever one local agent PTY per daemon process, so
+ * a singleton (rather than threading a handle through every call site) is
+ * a faithful match for that decision, and it's what keeps
+ * `deliverPromptToLocalAgent(prompt)` / `captureLocalAgentOutput()`
+ * exactly the same two free functions with the same signatures that
+ * attach-cmd.ts (and its test suite) already depend on and inject spies
+ * over — see attach-cmd.ts's `AttachDaemonDeps.deliverPrompt` /
+ * `.captureOutput`, defaulted to these two exports. Callers that already
+ * inject fakes for those two hooks (attach-cmd.test.ts) never touch this
+ * module at all, so nothing there needed to change.
+ */
+import { createRequire } from 'node:module';
+import * as pty from 'node-pty';
+// `@xterm/headless`'s published CJS bundle is a heavily minified/webpacked
+// single file — `cjs-module-lexer` (Node ESM's static CJS-named-export
+// detector) can't find `Terminal` on it, so a plain
+// `import { Terminal } from '@xterm/headless'` fails at runtime with
+// "Named export 'Terminal' not found" even though it type-checks fine
+// (the package's .d.ts declares named exports). `createRequire` sidesteps
+// static detection entirely and reads the real `module.exports` at
+// runtime, which does have `Terminal` on it.
+const require = createRequire(import.meta.url);
+const { Terminal } = require('@xterm/headless');
+/** Default agent binary: overridable via `--agent` (cli.ts) or this env var. */
+export const DEFAULT_AGENT_BIN = process.env.YOLOBRIDGE_AGENT_BIN || 'claude';
+const DEFAULT_COLS = 120;
+const DEFAULT_ROWS = 40;
+/** How recently the PTY must have produced output to be considered "busy". */
+const DEFAULT_BUSY_WINDOW_MS = 2_000;
+/**
+ * Readiness gate defaults — see `isReadyToReceiveInput`'s doc comment below
+ * for the reasoning (docs/YOLOBRIDGE_PLAN.md's "[P1] Blind prompt delivery"
+ * Codex finding). Distinct from `DEFAULT_BUSY_WINDOW_MS`: that one gates a
+ * UX-facing `busy` signal read_tile_output reports to callers (2s, tuned
+ * for "does this look like it's still thinking"); this one gates WRITE
+ * safety and only needs to rule out active mid-render, so it can be much
+ * shorter.
+ */
+const DEFAULT_READINESS_QUIET_MS = 200;
+/** Rows from the bottom of the viewport the cursor must sit within to
+ * count as "at the input line", once the terminal has scrolled at least
+ * once (see isReadyToReceiveInput). */
+const DEFAULT_CURSOR_BOTTOM_SLACK = 2;
+/** Bounded wait for readiness before proceeding anyway — see
+ * deliverPromptToLocalAgent's doc comment on why this doesn't refuse or
+ * hang indefinitely instead. */
+const DEFAULT_READINESS_TIMEOUT_MS = 5_000;
+const DEFAULT_READINESS_POLL_MS = 100;
+/**
+ * Delay between writing the prompt text and writing the Enter keystroke in
+ * `deliverPromptToLocalAgent` — see that function's doc comment. 150ms was
+ * enough to fix `codex` in manual testing with no observable added latency;
+ * not exposed as an option since it's a workaround for target-CLI input
+ * handling, not a tunable a caller should need to reason about.
+ */
+const PASTE_TO_ENTER_DELAY_MS = 150;
+/**
+ * Delay before Enter for a MULTILINE prompt specifically — see the
+ * "multiline delivery" section of `deliverPromptToLocalAgent`'s doc comment.
+ * Verified empirically (2026-08-22) against real `claude` (v2.1.240): 150ms
+ * and 300ms both left a 3-line prompt sitting unsent in the composer
+ * indefinitely (not a premature-split, a SILENT NEVER-SUBMITS); 800ms
+ * reliably submitted it. 1000ms is that empirical floor plus headroom, not a
+ * tuned-to-the-millisecond value — this only affects the already-rare
+ * multiline path, so the extra ~200ms over the verified-working 800ms is
+ * immaterial to UX. `codex` and `bash` submit correctly at the original
+ * 150ms already; using the longer delay for them too is harmless (just
+ * slower), so this applies unconditionally to every multiline delivery
+ * rather than trying to detect which target needs it.
+ */
+const MULTILINE_PASTE_TO_ENTER_DELAY_MS = 1_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+let current;
+function sanitizeEnv(env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (typeof v === 'string')
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * Explicit `cols`/`rows` win. Otherwise, when wiring to the real
+ * `process.stdout` (no injected sink — i.e. an actual interactive
+ * `attach` run, not a test double), inherit the real terminal's size if
+ * it reports one (a non-TTY stdout, e.g. piped/redirected, reports
+ * `undefined`). Falls back to the fixed default otherwise.
+ */
+function resolveCols(opts) {
+    if (opts.cols)
+        return opts.cols;
+    if (opts.stdout !== undefined)
+        return DEFAULT_COLS;
+    return process.stdout.columns || DEFAULT_COLS;
+}
+function resolveRows(opts) {
+    if (opts.rows)
+        return opts.rows;
+    if (opts.stdout !== undefined)
+        return DEFAULT_ROWS;
+    return process.stdout.rows || DEFAULT_ROWS;
+}
+/**
+ * Serializes the terminal's current buffer (scrollback + viewport) to
+ * plain text — no ANSI/SGR escape codes. Deliberately not using
+ * `@xterm/addon-serialize`: that addon's `serialize()` reconstructs a
+ * VT100-replayable stream (colors, cursor moves included) for re-feeding
+ * into another terminal, which is the wrong shape for `read_tile_output`
+ * — the consumer on the other end (an orchestrator tile, possibly an
+ * LLM) wants clean text, not escape sequences. Walking `buffer.active`
+ * directly and calling `translateToString` per line gives exactly that.
+ */
+export function serializeTerminalBuffer(term) {
+    const buffer = term.buffer.active;
+    const lines = [];
+    for (let i = 0; i < buffer.length; i++) {
+        const line = buffer.getLine(i);
+        lines.push(line ? line.translateToString(true) : '');
+    }
+    while (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines.join('\n');
+}
+/**
+ * Spawns the local coding agent under a real PTY and wires it up:
+ *   - PTY output -> headless Terminal (structured buffer for capture)
+ *   - PTY output -> the real process's stdout (live view for the human)
+ *   - the real process's stdin -> PTY (human keystrokes reach the agent)
+ *
+ * Idempotent in the sense that calling this while a previous session is
+ * still running stops it first — Decision Q3 (one tile per attach) means
+ * there is only ever one local agent per daemon process.
+ */
+export function startLocalAgent(opts = {}) {
+    if (current)
+        stopLocalAgent();
+    const agentBin = opts.agentBin ?? DEFAULT_AGENT_BIN;
+    const agentArgs = opts.agentArgs ?? [];
+    const cols = resolveCols(opts);
+    const rows = resolveRows(opts);
+    const spawnImpl = opts.spawnImpl ?? pty.spawn;
+    const busyWindowMs = opts.busyWindowMs ?? DEFAULT_BUSY_WINDOW_MS;
+    const readinessQuietMs = opts.readinessQuietMs ?? DEFAULT_READINESS_QUIET_MS;
+    const cursorBottomSlack = opts.cursorBottomSlack ?? DEFAULT_CURSOR_BOTTOM_SLACK;
+    const readinessTimeoutMs = opts.readinessTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS;
+    const readinessPollMs = opts.readinessPollMs ?? DEFAULT_READINESS_POLL_MS;
+    const outStream = opts.stdout ?? process.stdout;
+    // `'stdin' in opts` (not `opts.stdin ??`) so a test can pass `stdin: undefined`
+    // explicitly to disable stdin piping entirely, distinct from omitting the
+    // field (which defaults to wiring up the real `process.stdin`).
+    const inStream = 'stdin' in opts ? opts.stdin : process.stdin;
+    const ptyProcess = spawnImpl(agentBin, agentArgs, {
+        name: 'xterm-256color',
+        cols,
+        rows,
+        cwd: opts.cwd ?? process.cwd(),
+        env: sanitizeEnv(opts.env ?? process.env),
+    });
+    const term = new Terminal({ cols, rows, allowProposedApi: true });
+    const state = {
+        ptyProcess,
+        term,
+        lastOutputAt: Date.now(),
+        busyWindowMs,
+        readinessQuietMs,
+        cursorBottomSlack,
+        readinessTimeoutMs,
+        readinessPollMs,
+        writeChain: Promise.resolve(),
+        stdin: inStream,
+        rawModeEnabled: false,
+    };
+    current = state;
+    ptyProcess.onData((data) => {
+        state.lastOutputAt = Date.now();
+        outStream.write(data);
+        state.writeChain = state.writeChain.then(() => new Promise((resolve) => term.write(data, () => resolve())));
+    });
+    if (inStream && typeof inStream.on === 'function') {
+        const stdinListener = (data) => {
+            ptyProcess.write(typeof data === 'string' ? data : data.toString('utf-8'));
+        };
+        if (inStream.isTTY && typeof inStream.setRawMode === 'function') {
+            inStream.setRawMode(true);
+            state.rawModeEnabled = true;
+        }
+        inStream.resume?.();
+        inStream.setEncoding?.('utf-8');
+        inStream.on('data', stdinListener);
+        state.stdinListener = stdinListener;
+    }
+    ptyProcess.onExit(({ exitCode, signal }) => {
+        teardownStdio(state);
+        if (current === state)
+            current = undefined;
+        opts.onExit?.({ exitCode, signal });
+    });
+    return { stop: stopLocalAgent };
+}
+/**
+ * Real bug (found 2026-08-23 chasing a report that `attach` never fully
+ * exits on its own — "detaching..." prints, then the process just hangs
+ * until force-killed): `startLocalAgent` calls `inStream.resume?.()` to put
+ * `process.stdin` into flowing mode so keystrokes reach the PTY. A resumed
+ * stdin is a standing libuv handle that keeps Node's event loop alive
+ * regardless of `process.exitCode` — removing the `'data'` listener alone
+ * does NOT release it; only an explicit `pause()` does. This was missing
+ * here, so EVERY `attach` exit path (attach failure, the local agent dying
+ * on its own, a server-initiated detach, even a clean Ctrl+C) left stdin
+ * resumed and the process wedged. Reproduced against a real pty (`script
+ * -qec ... `, not a plain redirected stdin — `/dev/null`-as-stdin reaches
+ * EOF on its own and masked this): the process printed its final messages
+ * within ~1s but had to be force-killed at a 10s timeout every time,
+ * exit code 124. With `stdin.pause()` added below, the same repro exits
+ * cleanly on its own well under a second — no timeout/kill needed.
+ */
+function teardownStdio(state) {
+    const { stdin, stdinListener } = state;
+    if (stdin && stdinListener && typeof stdin.removeListener === 'function') {
+        stdin.removeListener('data', stdinListener);
+    }
+    if (state.rawModeEnabled && stdin?.isTTY && typeof stdin.setRawMode === 'function') {
+        stdin.setRawMode(false);
+    }
+    if (stdin && typeof stdin.pause === 'function') {
+        stdin.pause();
+    }
+}
+/**
+ * Stops the local agent session. Kills the PTY process (SIGTERM via
+ * node-pty's default `kill()`) and unwires stdio.
+ *
+ * Decision on detach lifecycle: `yolo-bridge attach` is what SPAWNED this
+ * process (see module header), so whatever ends the attach loop — local
+ * Ctrl+C, or a server-initiated `detached` frame — also ends the PTY
+ * session it owns. Nothing is left "running detached with no owner":
+ * cli.ts calls this unconditionally after `runAttachFromDisk` resolves,
+ * regardless of which of those two paths triggered the stop. If the
+ * agent process already exited on its own, this is a safe no-op (`current`
+ * is already cleared by the `onExit` handler above).
+ */
+export function stopLocalAgent() {
+    if (!current)
+        return;
+    const state = current;
+    current = undefined;
+    teardownStdio(state);
+    try {
+        state.ptyProcess.kill();
+    }
+    catch {
+        // already dead
+    }
+}
+/**
+ * Best-effort readiness check before `deliverPromptToLocalAgent` writes
+ * into the PTY — docs/YOLOBRIDGE_PLAN.md's "[P1] Blind prompt delivery can
+ * hit a permission dialog or partial input" Codex finding. Writing
+ * text+Enter with no regard for what's on screen could accidentally
+ * confirm a highlighted permission-dialog choice, or concatenate onto
+ * something the user was mid-typing.
+ *
+ * Mirrors the SHAPE of the pod side's own confidence-scored injection gate
+ * (`containers/services/terminal-mux/server.js`'s "marker + stability +
+ * cursor"), adapted to what this module actually has: direct structured
+ * `@xterm/headless` buffer access (no capture-pane text-scraping needed),
+ * but no per-agent marker set — building an equivalent of that file's
+ * `readiness-markers.js` for arbitrary local CLIs (claude, codex, and
+ * whatever `--agent` names) is out of scope for this fix, an acknowledged
+ * scope cut, not an oversight. No verify-after-inject retry either (the pod
+ * side's second defense layer, comparing before/after screen state once the
+ * text is written) — this check only gates BEFORE the write.
+ *
+ * Two signals:
+ *   - STABLE: no PTY output for `readinessQuietMs`. Rules out writing into
+ *     a screen that's still actively repainting — a streaming response, a
+ *     busy spinner, a dialog mid-animation. This is the primary signal and
+ *     directly addresses both halves of the finding: an active permission
+ *     dialog is normally still rendering (its highlight/spinner), and
+ *     "partial input" concern is really "is something being typed right
+ *     now" — both are "was there recent activity" questions.
+ *   - CURSOR AT THE INPUT LINE, but ONLY once the terminal has scrolled at
+ *     least once (`buffer.baseY > 0`): the cursor sits within
+ *     `cursorBottomSlack` rows of the viewport bottom. JUDGMENT CALL: this
+ *     is gated on `baseY` rather than being an unconditional requirement —
+ *     a short session whose content still fits in one screen (baseY === 0,
+ *     e.g. a freshly-spawned agent's first prompt, or the real-bash test
+ *     below) legitimately has its cursor wherever the last line landed,
+ *     which is often nowhere near the physical bottom row; requiring the
+ *     bonus signal there would stall every delivery to a short/compact
+ *     session for no real safety benefit. Once the terminal HAS scrolled,
+ *     though, a cursor that isn't near the bottom is a real signal we're
+ *     looking at scrolled-away history or a fixed-position dialog/pager
+ *     rather than the live input line — the pod side's own cursor check
+ *     has this exact same "assumes bottom" property, it just doesn't need
+ *     the `baseY` guard because tmux's `cursor_y`/`pane_height` are already
+ *     relative to the live pane, not a headless buffer that can start at
+ *     row 0 with nothing rendered yet.
+ */
+function isReadyToReceiveInput(state) {
+    const quietForMs = Date.now() - state.lastOutputAt;
+    if (quietForMs < state.readinessQuietMs)
+        return false;
+    const buffer = state.term.buffer.active;
+    if (buffer.baseY === 0)
+        return true;
+    const rows = state.term.rows;
+    return rows - 1 - buffer.cursorY <= state.cursorBottomSlack;
+}
+/**
+ * Polls `isReadyToReceiveInput` until it's true or `readinessTimeoutMs`
+ * elapses. Never rejects — a timeout just means the caller proceeds
+ * without the extra confidence (see `deliverPromptToLocalAgent`).
+ */
+async function waitForReadiness(state) {
+    const deadline = Date.now() + state.readinessTimeoutMs;
+    while (!isReadyToReceiveInput(state)) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        await sleep(Math.min(state.readinessPollMs, remaining));
+    }
+    return true;
+}
+/**
+ * Writes `prompt` into the owned PTY the same way the user's own
+ * keystrokes would land, followed by a carriage return so the target CLI
+ * actually submits it. `\r` (not `\n`) matches what a real terminal sends
+ * on Enter.
+ *
+ * **Waits (bounded) for `isReadyToReceiveInput` before writing anything.**
+ * JUDGMENT CALL on what happens if the terminal never settles within
+ * `readinessTimeoutMs`: this proceeds and writes anyway, rather than
+ * hanging indefinitely or silently refusing. A hard refusal would have no
+ * safe fallback — `yolobridge-service.ts`'s `publishPrompt` has a
+ * retry-on-RECONNECT loop (Decision Q5) for an OFFLINE daemon, but no
+ * retry-on-BUSY loop for a target that's merely slow to settle, so a
+ * refusal here would silently drop the prompt with no path to ever resend
+ * it. A timeout is therefore "proceed with reduced confidence, own the
+ * risk", not "give up" — the readiness check reduces the odds of a bad
+ * write, it does not (and, without the pod side's verify-after-inject
+ * layer, cannot) guarantee one never happens.
+ *
+ * **The text and the Enter are two SEPARATE writes, with a short delay
+ * between them — not one combined `${prompt}\r` write.** Verified
+ * empirically against real CLIs (2026-08-20, manual smoke test): a single
+ * combined write works for `bash` and `claude`, but silently fails to
+ * submit against `codex` — the text lands in its input box but Enter is
+ * never registered, so nothing is ever sent. Splitting into two writes
+ * with `PASTE_TO_ENTER_DELAY_MS` between them fixed `codex` with no
+ * regression on `claude`/`bash`. This mirrors the pod side's own proven
+ * two-step pattern (`containers/services/terminal-mux/server.js`:
+ * `tmux paste-buffer` followed by a SEPARATE `tmux send-keys Enter`, not
+ * one combined operation) — the same shape turned out to matter here too,
+ * not just there.
+ *
+ * If no session has been started yet (misuse, or a test that didn't call
+ * `startLocalAgent` first), lazily starts one with defaults rather than
+ * throwing — keeps this function's contract matching the original stub's
+ * "always succeeds, delivery is attempted" shape.
+ *
+ * **Multiline delivery (docs/YOLOBRIDGE_PLAN.md's "[P1] Send multiline
+ * prompts as a bracketed paste" Codex finding, fixed 2026-08-22).** A
+ * prompt containing embedded `\n` is wrapped in bracketed-paste markers
+ * (`\x1b[200~`/`\x1b[201~`) and waits `MULTILINE_PASTE_TO_ENTER_DELAY_MS`
+ * (not `PASTE_TO_ENTER_DELAY_MS`) before the Enter write. **The bracketed
+ * markers turned out NOT to be the load-bearing part of this fix** — real
+ * interop testing (spawning actual `claude`/`codex`/`bash` under `node-pty`,
+ * the same rigor as the codex-write-timing fix above) showed `codex`
+ * already correctly composes and submits a multiline prompt as ONE message
+ * at the original 150ms delay, no markers needed; `bash` is unaffected by
+ * markers either way (a multi-statement shell script legitimately runs each
+ * line once submitted — that's normal shell semantics, not a delivery bug,
+ * and `bash` is only this module's sanity-check fallback, not a primary
+ * agent target). The REAL bug was `claude` (v2.1.240): at the original
+ * 150ms delay, a multiline prompt was left sitting UNSENT in the composer
+ * indefinitely — not a premature partial-submit, a silent no-op that
+ * `send_to_tile` would have reported as `delivered: true` while the agent
+ * never saw it. Confirmed via the headless-buffer screen capture this
+ * module already uses for `read_tile_output`: 150ms/300ms (bracketed or
+ * not) left the 3-line prompt in the composer with no response ever
+ * starting; 800ms reliably submitted it and the model began responding.
+ * Bracketed-paste markers are kept anyway as cheap defense-in-depth (every
+ * target tested renders them correctly with no visible artifacts) for
+ * whatever agent binary is named next via `--agent` that wasn't tested
+ * here — but the delay is what actually closes the finding.
+ */
+export async function deliverPromptToLocalAgent(prompt) {
+    if (!current)
+        startLocalAgent();
+    const state = current;
+    await waitForReadiness(state);
+    const ptyProcess = state.ptyProcess;
+    const isMultiline = prompt.includes('\n');
+    ptyProcess.write(isMultiline ? `\x1b[200~${prompt}\x1b[201~` : prompt);
+    await sleep(isMultiline ? MULTILINE_PASTE_TO_ENTER_DELAY_MS : PASTE_TO_ENTER_DELAY_MS);
+    ptyProcess.write('\r');
+}
+/**
+ * Serializes the current headless-terminal buffer to plain text and
+ * reports a `busy` heuristic: has the PTY produced output within the
+ * last `busyWindowMs` (default 2s)? Mirrors the spirit of the pod side's
+ * own busy-detection (recent-activity-based) without depending on any
+ * pod-only primitive.
+ */
+export async function captureLocalAgentOutput() {
+    if (!current)
+        return { output: '', busy: false };
+    await current.writeChain;
+    const output = serializeTerminalBuffer(current.term);
+    const busy = Date.now() - current.lastOutputAt < current.busyWindowMs;
+    return { output, busy };
+}

package/dist/login-cmd.js

@@ -0,0 +1,50 @@
+/**
+ * `yolo-bridge login` — device-authorization flow against auth-service
+ * (see device-auth.ts for the exact wire contract). Orchestration only;
+ * the HTTP shapes live in device-auth.ts so they can be unit tested
+ * independent of this polling loop.
+ */
+import { requestDeviceCode, pollDeviceToken } from './device-auth.js';
+import { openBrowserBestEffort } from './browser-open.js';
+import { saveAuth } from './config-store.js';
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function runLogin(deps) {
+    const { authBaseUrl, fetchImpl, env, io } = deps;
+    const sleep = deps.sleep ?? defaultSleep;
+    const openBrowser = deps.openBrowser ?? openBrowserBestEffort;
+    const log = deps.log ?? ((line) => process.stdout.write(`${line}\n`));
+    const code = await requestDeviceCode(authBaseUrl, fetchImpl);
+    log('To finish logging in, open this URL in your browser:');
+    log(`  ${code.verificationUri}`);
+    log('and enter this code when prompted:');
+    log(`  ${code.userCode}`);
+    log('');
+    log('Waiting for approval...');
+    openBrowser(code.verificationUri);
+    const deadline = Date.now() + code.expiresInSec * 1000;
+    const intervalMs = Math.max(1, code.intervalSec) * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        const poll = await pollDeviceToken(authBaseUrl, code.deviceCode, fetchImpl);
+        if (poll.status === 'pending')
+            continue;
+        if (poll.status === 'denied') {
+            return { ok: false, reason: 'denied', message: 'Login was denied.' };
+        }
+        if (poll.status === 'expired') {
+            return { ok: false, reason: 'expired', message: 'Device code expired before login was completed.' };
+        }
+        if (poll.status === 'error') {
+            return { ok: false, reason: 'error', message: poll.message };
+        }
+        saveAuth({
+            accessToken: poll.tokens.accessToken,
+            refreshToken: poll.tokens.refreshToken,
+            tokenType: poll.tokens.tokenType,
+            expiresAtMs: poll.tokens.expiresAtMs,
+        }, env, io);
+        log('Logged in.');
+        return { ok: true };
+    }
+    return { ok: false, reason: 'expired', message: 'Device code expired before login was completed.' };
+}

package/dist/reconnect.js

@@ -0,0 +1,41 @@
+/**
+ * Reconnect backoff for the attach daemon's SSE stream.
+ *
+ * Plan calls for "sleep/wake-aware" resilience (docs/YOLOBRIDGE_PLAN.md,
+ * Architecture → Auth / CLI daemon section). What's implemented: plain
+ * exponential backoff with a cap and jitter, which recovers naturally
+ * after a laptop sleep/wake — the stream just looks like a very long
+ * disconnect, and the next scheduled attempt reconnects it. What's NOT
+ * implemented: an actual OS-level sleep/wake signal (e.g. macOS
+ * `powermetrics`/IOKit notifications, a wall-clock-jump detector that
+ * resets backoff to zero) that would let the daemon reconnect *the
+ * instant* the machine wakes rather than waiting out whatever backoff
+ * step it was on when the lid closed. Flagged in the final report as a
+ * deliberate scope cut, not an oversight — true sleep/wake detection is
+ * platform-specific plumbing with no shared Node API across macOS/Linux/
+ * Windows, and a bounded backoff (cap below) already keeps the worst case
+ * to a single missed heartbeat window's multiple, not indefinite.
+ */
+export const DEFAULT_BACKOFF = {
+    baseMs: 1_000,
+    maxMs: 30_000,
+    factor: 2,
+    jitter: 0.2,
+    random: Math.random,
+};
+/**
+ * `attempt` is 1-indexed (the first reconnect attempt after a drop).
+ * Pure function — no timers, no I/O — so the exponential/cap/jitter math
+ * is fully testable without waiting on a real clock.
+ */
+export function nextBackoffMs(attempt, opts = {}) {
+    const { baseMs, maxMs, factor, jitter, random } = { ...DEFAULT_BACKOFF, ...opts };
+    const raw = baseMs * Math.pow(factor, Math.max(0, attempt - 1));
+    const capped = Math.min(raw, maxMs);
+    if (jitter <= 0)
+        return capped;
+    const jitterRange = capped * jitter;
+    // random() in [0,1) → offset in [-jitterRange, +jitterRange)
+    const offset = (random() * 2 - 1) * jitterRange;
+    return Math.max(0, Math.round(capped + offset));
+}

package/dist/sse-frame-parser.js

@@ -0,0 +1,66 @@
+/**
+ * Parser for the exact SSE framing `yolobridge-service.ts`'s `writeFrame`
+ * emits (`common-api/src/services/yolobridge-service.ts:122-136`):
+ *
+ *   event: <type>\n
+ *   data: <json>\n
+ *   \n
+ *
+ * No `id:` line (deliberate — see that file's comment: this stream has no
+ * replay buffer). Frame types actually written by the server today:
+ *   - `connected`    { attachmentId, workspaceId, timestamp }   (holdStream)
+ *   - `ping`         { t }                                       (holdStream keepalive, ~30s)
+ *   - `prompt`       { attachmentId, prompt }                    (publishPrompt)
+ *   - `read-output`  { attachmentId, requestId }                 (requestReadOutput)
+ *   - `detached`     { attachmentId }                             (detachDaemon)
+ *
+ * Pure incremental parser: feed it raw chunks as they arrive off the wire
+ * (chunk boundaries need not align with frame boundaries — a `data:` line
+ * can legitimately split across two `write()` calls under backpressure),
+ * get back zero or more complete frames per `push()` call. No network or
+ * timer code in this file — fully unit-testable without a real stream.
+ */
+export class SseFrameParser {
+    buffer = '';
+    /** Feed a raw chunk (already decoded to a string). Returns any complete frames it produced. */
+    push(chunk) {
+        this.buffer += chunk;
+        const frames = [];
+        // Frames are separated by a blank line (`\n\n`). Split conservatively:
+        // keep the trailing partial block in the buffer for the next push().
+        let sepIndex;
+        while ((sepIndex = this.buffer.indexOf('\n\n')) !== -1) {
+            const block = this.buffer.slice(0, sepIndex);
+            this.buffer = this.buffer.slice(sepIndex + 2);
+            const frame = parseBlock(block);
+            if (frame)
+                frames.push(frame);
+        }
+        return frames;
+    }
+}
+function parseBlock(block) {
+    let event = 'message'; // SSE default event name when no `event:` line is present.
+    const dataLines = [];
+    for (const line of block.split('\n')) {
+        if (line.startsWith('event:')) {
+            event = line.slice('event:'.length).trim();
+        }
+        else if (line.startsWith('data:')) {
+            dataLines.push(line.slice('data:'.length).trimStart());
+        }
+        // Any other line (comments, unrecognized fields) is ignored — this
+        // stream never sends `id:`/`retry:`.
+    }
+    if (dataLines.length === 0)
+        return null;
+    const raw = dataLines.join('\n');
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        data = undefined;
+    }
+    return { event, data, raw };
+}