@yolo-labs/yolobridge 0.9.0 → 0.11.0

package/dist/api-client.js

@@ -191,16 +191,61 @@ export async function postHeartbeat(cfg, workspaceId, attachmentId) {
     const body = await postEvent(cfg, workspaceId, { attachmentId, type: 'heartbeat' });
     return Boolean(body?.recorded);
 }
-export async function postReadOutputReply(cfg, workspaceId, attachmentId, requestId, output, busy) {
+export async function postReadOutputReply(cfg, workspaceId, attachmentId, requestId, output, busy, extra) {
     const body = await postEvent(cfg, workspaceId, {
         attachmentId,
         type: 'read-output-reply',
         requestId,
         output,
         busy,
+        ...(extra?.cols && extra?.rows ? { cols: extra.cols, rows: extra.rows } : {}),
+        ...(extra?.raw
+            ? {
+                raw: extra.raw.data,
+                epoch: extra.raw.epoch,
+                baseOffset: extra.raw.baseOffset,
+                endOffset: extra.raw.endOffset,
+                truncated: extra.raw.truncated,
+            }
+            : {}),
     });
     return Boolean(body?.resolved);
 }
+/**
+ * `POST .../yolobridge/events {type:'output-chunk'}` — one batch of live PTY
+ * output (docs/YOLOBRIDGE_PLAN.md, "Live terminal streaming").
+ *
+ * Sent ONLY while the server has an unexpired `output-stream-start` lease
+ * outstanding, i.e. only while a browser is actually watching the tile. A
+ * daemon with no viewer sends none of these at all — see attach-cmd.ts's
+ * stream controller.
+ *
+ * Authenticated with the WORKSPACE-SCOPED credential like every other
+ * post-attach call (Boundary B refuses an account token here), and the bytes
+ * are relayed in memory by the server onto the workspace's own event stream —
+ * never logged, never written to Mongo, never appended to the resumable event
+ * buffer. This is the operator's live screen; it can contain anything they
+ * typed.
+ *
+ * `droppedBytes` is how many bytes were SKIPPED immediately before `data`
+ * (see output-stream.ts). Non-zero means the viewer must treat its screen as
+ * unreliable and re-seed — it is not a diagnostic counter, it is part of the
+ * protocol.
+ */
+export async function postOutputChunk(cfg, workspaceId, attachmentId, chunk) {
+    const body = await postEvent(cfg, workspaceId, {
+        attachmentId,
+        type: 'output-chunk',
+        streamId: chunk.streamId,
+        seq: chunk.seq,
+        data: chunk.data,
+        droppedBytes: chunk.droppedBytes,
+        ...(chunk.epoch ? { epoch: chunk.epoch } : {}),
+        ...(typeof chunk.startOffset === 'number' ? { startOffset: chunk.startOffset } : {}),
+        ...(chunk.cols && chunk.rows ? { cols: chunk.cols, rows: chunk.rows } : {}),
+    });
+    return Boolean(body?.relayed);
+}
 async function postEvent(cfg, workspaceId, payload) {
     const fetchImpl = cfg.fetchImpl ?? fetch;
     const res = await fetchImpl(`${base(cfg)}/v1/workspaces/${workspaceId}/yolobridge/events`, {

package/dist/attach-cmd.js

@@ -22,7 +22,8 @@ import { SseFrameParser } from './sse-frame-parser.js';
 import { actionForFrame } from './frame-actions.js';
 import { startHeartbeat, defaultTimers } from './heartbeat.js';
 import { nextBackoffMs } from './reconnect.js';
-import { deliverPromptToLocalAgent, captureLocalAgentOutput } from './local-agent.js';
+import { deliverPromptToLocalAgent, captureLocalAgentOutput, onLocalAgentData, takeRawSeed as takeRawSeedFromAgent, primeRawStream as primeRawStreamFromAgent, getLocalAgentGeometry, } from './local-agent.js';
+import { OutputStreamBuffer, DEFAULT_FLUSH_INTERVAL_MS, } from './output-stream.js';
 import * as apiClient from './api-client.js';
 import { refreshAccessToken as refreshAccessTokenApi } from './device-auth.js';
 import { loadAuth, saveAuth, loadAttachment, saveAttachment, clearAttachment, } from './config-store.js';
@@ -83,6 +84,11 @@ export async function runAttachDaemon(deps) {
     const refreshBufferMs = deps.refreshBufferMs ?? DEFAULT_REFRESH_BUFFER_MS;
     const authBaseUrl = deps.authBaseUrl ?? process.env.YOLOBRIDGE_AUTH_URL ?? DEFAULT_AUTH_URL;
     const doRefresh = deps.refreshAccessToken ?? refreshAccessTokenApi;
+    const subscribeAgentOutput = deps.subscribeAgentOutput ?? onLocalAgentData;
+    const takeRawSeed = deps.takeRawSeed ?? takeRawSeedFromAgent;
+    const primeRawStream = deps.primeRawStream ?? primeRawStreamFromAgent;
+    const getGeometry = deps.getAgentGeometry ?? getLocalAgentGeometry;
+    const flushIntervalMs = deps.outputFlushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
     /**
      * THE ACCOUNT identity. Full-account bearer from `yolo-bridge login`, and the
      * ONLY thing `ensureFreshToken` may write to. Used for exactly one call —
@@ -594,6 +600,133 @@ export async function runAttachDaemon(deps) {
         clearAttachment(env, io);
         return { ok: true, reason: 'stopped' };
     }
+    let outputStream;
+    function stopOutputStream() {
+        const session = outputStream;
+        if (!session)
+            return;
+        outputStream = undefined;
+        try {
+            session.unsubscribe();
+        }
+        catch { /* best effort */ }
+        timers.clearInterval(session.flushHandle);
+        // Anything still queued belongs to a streamId that no longer exists.
+        session.buffer.reset();
+    }
+    async function flushOutputStream(session) {
+        if (outputStream !== session)
+            return;
+        // Lease check FIRST, before any work: this tick is the only thing that
+        // ever notices a lapsed grant, and it must notice it even when the buffer
+        // is empty.
+        if (now() >= session.leaseUntilMs) {
+            stopOutputStream();
+            return;
+        }
+        if (session.posting)
+            return;
+        const batch = session.buffer.drain();
+        if (!batch)
+            return;
+        const bytes = Buffer.byteLength(batch.data, 'utf-8');
+        session.posting = true;
+        try {
+            const geometry = getGeometry();
+            await apiClient.postOutputChunk(scopedCfg(), workspaceId, attachmentId, {
+                streamId: session.streamId,
+                seq: session.seq,
+                data: batch.data,
+                droppedBytes: batch.droppedBytes,
+                epoch: session.epoch,
+                startOffset: batch.startOffset,
+                cols: geometry?.cols,
+                rows: geometry?.rows,
+            });
+            if (outputStream === session)
+                session.seq += 1;
+        }
+        catch (err) {
+            // These bytes are GONE — re-queueing them would reorder the stream
+            // behind whatever the PTY produced while the POST was in flight, and an
+            // out-of-order terminal frame is worse than an acknowledged hole. Fold
+            // them (plus any gap this batch was already carrying) into the next
+            // batch's `droppedBytes` so the viewer re-seeds instead of trusting a
+            // screen that silently lost a frame.
+            if (outputStream === session)
+                session.buffer.noteDropped(bytes + batch.droppedBytes);
+            // Out-of-band, never `log`: this fires mid-session while the local
+            // agent's TUI owns stdout (connection-state.ts's module header). The
+            // detail carries the transport error only — NEVER the PTY bytes.
+            noteConnection('degraded', {
+                detail: `output chunk relay failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        finally {
+            if (outputStream === session)
+                session.posting = false;
+        }
+    }
+    /**
+     * Honour an `output-stream-start` frame.
+     *
+     * Same `streamId` → this is a LEASE RENEWAL (the server re-sends while
+     * demand persists); keep the tap, the buffer and the sequence exactly as
+     * they are, so a renewal is invisible to the viewer.
+     *
+     * Different `streamId` → a NEW episode (the previous one was stopped, or
+     * this daemon reconnected and the server re-granted). Tear the old one down
+     * first: its queued bytes describe a screen the viewer is no longer showing.
+     */
+    function startOrRenewOutputStream(streamId, leaseMs) {
+        if (!streamId)
+            return;
+        const existing = outputStream;
+        if (existing && existing.streamId === streamId) {
+            existing.leaseUntilMs = now() + leaseMs;
+            return;
+        }
+        stopOutputStream();
+        // Prime from the raw ring, atomically with taking the tap below. The seed
+        // the viewer fetches is a SEPARATE round trip that can land either side of
+        // this moment, so the stream deliberately starts BEHIND it: overlapping
+        // bytes are trimmed by the viewer using their absolute offsets, whereas a
+        // hole would cost a re-seed. Overlap is free; a gap is not.
+        const prime = primeRawStream();
+        const buffer = new OutputStreamBuffer(deps.outputStreamOptions);
+        buffer.setBaseOffset(prime.startOffset);
+        if (prime.data)
+            buffer.push(prime.data);
+        const session = {
+            streamId,
+            seq: 0,
+            buffer,
+            unsubscribe: () => { },
+            flushHandle: undefined,
+            leaseUntilMs: now() + leaseMs,
+            posting: false,
+            epoch: prime.epoch,
+        };
+        outputStream = session;
+        // Subscribe AFTER the session exists so a synchronous first chunk can't
+        // land on a half-built one.
+        session.unsubscribe = subscribeAgentOutput((data, meta) => {
+            if (outputStream !== session)
+                return;
+            if (meta && meta.epoch !== session.epoch) {
+                // The local agent was respawned under us. Everything queued describes a
+                // screen that no longer exists; rebase onto the new session's offsets
+                // and let the viewer notice the epoch change and re-seed.
+                buffer.reset();
+                buffer.setBaseOffset(meta.startOffset);
+                session.epoch = meta.epoch;
+            }
+            buffer.push(data);
+        });
+        session.flushHandle = timers.setInterval(() => {
+            void flushOutputStream(session);
+        }, flushIntervalMs);
+    }
     let heartbeat;
     let attempt = 0;
     /** Set when a proactive refresh (see ensureFreshToken) fails while a
@@ -730,13 +863,39 @@ export async function runAttachDaemon(deps) {
                                     break;
                                 case 'read-output': {
                                     const captured = await captureOutput();
+                                    // Taken AFTER the (async) capture and synchronously, so
+                                    // `endOffset` names the exact byte position this reply leaves
+                                    // the viewer at. Anything the PTY produces from here on
+                                    // carries a higher offset and is spliced on by the viewer;
+                                    // anything already inside `raw.data` is trimmed by the same
+                                    // arithmetic. That is what makes seed and tap non-atomic in
+                                    // WALL CLOCK yet exactly-once in effect.
+                                    const raw = action.mode === 'raw' ? takeRawSeed() : undefined;
                                     await apiClient
-                                        .postReadOutputReply(scopedCfg(), workspaceId, attachmentId, action.requestId, captured.output, captured.busy)
+                                        .postReadOutputReply(scopedCfg(), workspaceId, attachmentId, action.requestId, captured.output, captured.busy, {
+                                        cols: raw?.cols ?? captured.cols,
+                                        rows: raw?.rows ?? captured.rows,
+                                        raw: raw
+                                            ? {
+                                                epoch: raw.epoch,
+                                                baseOffset: raw.baseOffset,
+                                                endOffset: raw.endOffset,
+                                                data: raw.data,
+                                                truncated: raw.truncated,
+                                            }
+                                            : undefined,
+                                    })
                                         .catch((err) => noteConnection('degraded', {
                                         detail: `read-output reply failed: ${err instanceof Error ? err.message : String(err)}`,
                                     }));
                                     break;
                                 }
+                                case 'output-stream-start':
+                                    startOrRenewOutputStream(action.streamId, action.leaseMs);
+                                    break;
+                                case 'output-stream-stop':
+                                    stopOutputStream();
+                                    break;
                                 case 'detached':
                                     noteConnection('detached');
                                     sawDetached = true;
@@ -765,6 +924,11 @@ export async function runAttachDaemon(deps) {
             }
             heartbeat?.stop();
             heartbeat = undefined;
+            // The grant died with the connection that carried it. A reconnect gets a
+            // FRESH `output-stream-start` (new streamId) if demand still exists —
+            // never a silent resumption of the old one, which is what keeps a
+            // reconnect from splicing two episodes' bytes into one screen.
+            stopOutputStream();
             if (sawDetached || sawGone) {
                 clearAttachment(env, io);
                 return { ok: true, reason: 'detached-by-server' };
@@ -781,6 +945,11 @@ export async function runAttachDaemon(deps) {
     }
     finally {
         heartbeat?.stop();
+        // Belt and braces for every path out of the loop (a break, a throw, a
+        // stop signal): no code path may leave a live PTY tap or flush timer
+        // behind, or the daemon would keep streaming with nobody watching — the
+        // exact failure this whole mechanism exists to prevent.
+        stopOutputStream();
     }
     if (scopedRefreshFailed) {
         // OUT-OF-BAND ONLY — no `log()` here, unlike the account-token path below.

package/dist/frame-actions.js

@@ -7,6 +7,13 @@
  * reconnecting" — is unit-testable without a live stream or a real
  * daemon loop.
  */
+/** Lease to assume when a server sends `output-stream-start` without one (or
+ *  with a nonsense value). Deliberately short — an unknown lease is a reason to
+ *  be conservative, not generous. */
+export const FALLBACK_OUTPUT_STREAM_LEASE_MS = 30_000;
+/** Upper bound on a server-supplied lease. A buggy or hostile server cannot
+ *  talk this daemon into streaming for an hour on one frame. */
+export const MAX_OUTPUT_STREAM_LEASE_MS = 5 * 60_000;
 export function actionForFrame(frame) {
     const data = (frame.data ?? {});
     switch (frame.event) {
@@ -25,7 +32,24 @@ export function actionForFrame(frame) {
                 kind: 'read-output',
                 attachmentId: String(data.attachmentId ?? ''),
                 requestId: String(data.requestId ?? ''),
+                // Anything unrecognized (including an absent field, which is what a
+                // server predating raw seeding sends) means the old screen dump.
+                mode: data.mode === 'raw' ? 'raw' : 'screen',
             };
+        case 'output-stream-start': {
+            const raw = typeof data.leaseMs === 'number' ? data.leaseMs : NaN;
+            const leaseMs = Number.isFinite(raw) && raw > 0
+                ? Math.min(raw, MAX_OUTPUT_STREAM_LEASE_MS)
+                : FALLBACK_OUTPUT_STREAM_LEASE_MS;
+            return {
+                kind: 'output-stream-start',
+                attachmentId: String(data.attachmentId ?? ''),
+                streamId: String(data.streamId ?? ''),
+                leaseMs,
+            };
+        }
+        case 'output-stream-stop':
+            return { kind: 'output-stream-stop', attachmentId: String(data.attachmentId ?? '') };
         case 'detached':
             return { kind: 'detached', attachmentId: String(data.attachmentId ?? '') };
         default:

package/dist/local-agent.js

@@ -32,7 +32,9 @@
  * module at all, so nothing there needed to change.
  */
 import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
 import * as pty from 'node-pty';
+import { splitByUtf8Bytes } from './output-stream.js';
 // `@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
@@ -45,8 +47,8 @@ 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;
+export const DEFAULT_COLS = 120;
+export const DEFAULT_ROWS = 40;
 /** How recently the PTY must have produced output to be considered "busy". */
 const DEFAULT_BUSY_WINDOW_MS = 2_000;
 /**
@@ -95,6 +97,191 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 let current;
+const rawDataListeners = new Set();
+/**
+ * Register a raw-output tap. Returns an unsubscribe that is safe to call more
+ * than once.
+ */
+export function onLocalAgentData(listener) {
+    rawDataListeners.add(listener);
+    return () => {
+        rawDataListeners.delete(listener);
+    };
+}
+/** Fan a PTY chunk out to every tap. A throwing tap must never break the
+ *  human's own view of the session, which is the very next thing that would
+ *  happen if this propagated out of the `onData` handler. */
+function fanOutRawData(data, meta) {
+    if (rawDataListeners.size === 0)
+        return;
+    for (const listener of rawDataListeners) {
+        try {
+            listener(data, meta);
+        }
+        catch {
+            // A broken tap degrades the remote view, never the local session.
+        }
+    }
+}
+// ─── The raw replay ring (docs/YOLOBRIDGE_PLAN.md, "Live terminal streaming")
+//
+// ⚠️ WHY THIS EXISTS AT ALL, given `serializeTerminalBuffer` already produces a
+// perfectly good screen dump.
+//
+// A line dump is the right primitive for a STATIC snapshot (`read_tile_output`
+// still uses it). It is the WRONG primitive for resuming a LIVE stream, and
+// the difference is not cosmetic. A dump carries the glyphs and their colours
+// and nothing else: not the cursor position, not the scroll region (DECSTBM),
+// not whether the alternate screen is active, not the saved cursor, not
+// autowrap mode. A real TUI — Claude Code, codex, anything with a spinner or a
+// redrawn prompt box — repaints using RELATIVE moves (`\x1b[A`, `\x1b[K`, a
+// bare `\r`). Seed a viewer from a dump and every one of those moves is applied
+// from the wrong origin, so redraws land on the wrong rows: text drawn on top
+// of other text, prompt boxes marching down the screen. That is a state
+// reconstruction bug, and the only fix that does not have a next instance is
+// to stop reconstructing state.
+//
+// So: keep the last `RAW_RING_MAX_BYTES` of the RAW PTY byte stream and replay
+// those bytes into the viewer's terminal. The viewer's xterm then parses
+// exactly what the daemon's terminal parsed and arrives at exactly the same
+// state — no cursor inference, no mode inference, no seam to get wrong.
+//
+// Every byte is stamped with an absolute offset, which is what makes the seed
+// and the tap safe to be two independent, racing operations: overlap is
+// deduplicated by offset and a hole is detected by offset. Neither is possible
+// with `seq`, which only orders what was actually sent.
+/**
+ * Raw PTY bytes retained for seeding a viewer. 256 KiB.
+ *
+ * The number is chosen for what it has to CONTAIN, not for memory: a viewer
+ * seeded mid-session needs the bytes back to (at least) the TUI's most recent
+ * full repaint, and a repainting agent redraws its whole screen many times per
+ * minute — a 120×40 full repaint with colour is on the order of 10-30 KiB, so
+ * this holds many of them. It is also comfortably under the server's 5 MB JSON
+ * body limit, since the whole ring can travel in one seed reply.
+ */
+export const RAW_RING_MAX_BYTES = 256 * 1024;
+/**
+ * How much of the ring is replayed into a NEW streaming episode's queue.
+ *
+ * The tap and the seed are separate round trips, so a viewer's seed can end at
+ * an offset slightly before (or after) the point the tap starts at. Priming
+ * the episode with a recent tail guarantees the stream covers the seam from
+ * below; the viewer trims the duplicate prefix by offset. 64 KiB is ~1000×
+ * more than one HTTP round trip's worth of agent output, and a miss is not
+ * fatal anyway — it reads as a gap and costs one extra re-seed.
+ */
+export const RAW_STREAM_PRIME_BYTES = 64 * 1024;
+function newRawRing() {
+    return { epoch: randomUUID(), chunks: [], bytes: 0, baseOffset: 0, endOffset: 0 };
+}
+let rawRing = newRawRing();
+/** Append to the ring and return where the chunk landed. Synchronous and
+ *  called from `onData`, so a tap and a seed taken in the same tick can never
+ *  disagree about the offset. */
+function pushRaw(data) {
+    const startOffset = rawRing.endOffset;
+    const bytes = Buffer.byteLength(data, 'utf-8');
+    rawRing.chunks.push(data);
+    rawRing.bytes += bytes;
+    rawRing.endOffset += bytes;
+    trimRawRing();
+    return { epoch: rawRing.epoch, startOffset };
+}
+/** Drop from the FRONT until the ring is within its cap, advancing
+ *  `baseOffset` by exactly what was dropped. Cuts only at code-point
+ *  boundaries (`splitByUtf8Bytes`) so a replayed tail is never a lone
+ *  surrogate. */
+function trimRawRing() {
+    while (rawRing.bytes > RAW_RING_MAX_BYTES && rawRing.chunks.length > 0) {
+        const overflow = rawRing.bytes - RAW_RING_MAX_BYTES;
+        const oldest = rawRing.chunks[0];
+        const oldestBytes = Buffer.byteLength(oldest, 'utf-8');
+        if (oldestBytes <= overflow) {
+            rawRing.chunks.shift();
+            rawRing.bytes -= oldestBytes;
+            rawRing.baseOffset += oldestBytes;
+            continue;
+        }
+        const { head, tail } = splitByUtf8Bytes(oldest, overflow);
+        const droppedBytes = Buffer.byteLength(head, 'utf-8');
+        if (droppedBytes === 0) {
+            // A single code point wider than the overflow — drop the chunk rather
+            // than spin.
+            rawRing.chunks.shift();
+            rawRing.bytes -= oldestBytes;
+            rawRing.baseOffset += oldestBytes;
+            continue;
+        }
+        rawRing.chunks[0] = tail;
+        rawRing.bytes -= droppedBytes;
+        rawRing.baseOffset += droppedBytes;
+    }
+}
+/**
+ * Take the current replay tail plus the PTY's grid size, as ONE synchronous
+ * observation.
+ *
+ * Atomic by construction: nothing can interleave between reading the ring and
+ * reading the offsets, so `endOffset` is exactly the position a viewer reaches
+ * by writing `data`. Bytes the PTY produces after this call carry offsets
+ * ≥ `endOffset` and are therefore either spliced on cleanly or (if they were
+ * already in `data`) trimmed away by the viewer — never lost, never applied
+ * twice.
+ */
+export function takeRawSeed() {
+    if (!current)
+        return undefined;
+    return {
+        epoch: rawRing.epoch,
+        baseOffset: rawRing.baseOffset,
+        endOffset: rawRing.endOffset,
+        data: rawRing.chunks.join(''),
+        cols: current.cols,
+        rows: current.rows,
+        truncated: rawRing.baseOffset > 0,
+    };
+}
+export function primeRawStream(maxBytes = RAW_STREAM_PRIME_BYTES) {
+    const all = rawRing.chunks.join('');
+    const total = Buffer.byteLength(all, 'utf-8');
+    if (total <= maxBytes) {
+        return { epoch: rawRing.epoch, startOffset: rawRing.baseOffset, data: all };
+    }
+    const { head, tail } = splitByUtf8Bytes(all, total - maxBytes);
+    return {
+        epoch: rawRing.epoch,
+        startOffset: rawRing.baseOffset + Buffer.byteLength(head, 'utf-8'),
+        data: tail,
+    };
+}
+/** The PTY's grid, which the tile must render at EXACTLY (it cannot be
+ *  resized — the human at the keyboard is watching the same PTY). */
+export function getLocalAgentGeometry() {
+    if (!current)
+        return undefined;
+    return { cols: current.cols, rows: current.rows };
+}
+/** The same recent-activity heuristic `captureLocalAgentOutput` reports, without
+ *  paying for a buffer serialization. */
+export function isLocalAgentBusy() {
+    if (!current)
+        return false;
+    return Date.now() - current.lastOutputAt < current.busyWindowMs;
+}
+/** Test seam: forget the ring and start a fresh epoch. */
+export function __resetRawRing() {
+    rawRing = newRawRing();
+}
+/**
+ * Test seam: the daemon's OWN headless terminal — the thing a remote viewer
+ * must end up cell-for-cell identical to. Exposed only so a test can assert
+ * that equality directly (glyphs, attributes AND cursor position) instead of
+ * eyeballing a serialized dump, which cannot see cursor drift at all.
+ */
+export function __getLocalAgentTerminal() {
+    return current?.term;
+}
 function sanitizeEnv(env) {
     const out = {};
     for (const [k, v] of Object.entries(env)) {
@@ -336,9 +523,16 @@ export function startLocalAgent(opts = {}) {
         env: sanitizeEnv(opts.env ?? process.env),
     });
     const term = new Terminal({ cols, rows, allowProposedApi: true });
+    // A NEW PTY is a new byte stream: everything retained belongs to a screen
+    // that no longer exists, and offsets restart. The fresh `epoch` is what a
+    // viewer keyed to the old one sees, and it re-seeds rather than splicing two
+    // sessions' bytes together.
+    rawRing = newRawRing();
     const state = {
         ptyProcess,
         term,
+        cols,
+        rows,
         lastOutputAt: Date.now(),
         busyWindowMs,
         readinessQuietMs,
@@ -354,6 +548,11 @@ export function startLocalAgent(opts = {}) {
         state.lastOutputAt = Date.now();
         outStream.write(data);
         state.writeChain = state.writeChain.then(() => new Promise((resolve) => term.write(data, () => resolve())));
+        // Ring FIRST, then the taps, with the offset the ring assigned — a tap and
+        // a `takeRawSeed()` taken in the same tick must agree on where this chunk
+        // sits, or the viewer's dedupe/gap logic is reasoning about two different
+        // coordinate systems.
+        fanOutRawData(data, pushRaw(data));
     });
     if (inStream && typeof inStream.on === 'function') {
         const stdinListener = (data) => {
@@ -374,7 +573,7 @@ export function startLocalAgent(opts = {}) {
             current = undefined;
         opts.onExit?.({ exitCode, signal });
     });
-    return { stop: stopLocalAgent };
+    return { stop: stopLocalAgent, cols, rows };
 }
 /**
  * Real bug (found 2026-08-23 chasing a report that `attach` never fully
@@ -588,5 +787,8 @@ export async function captureLocalAgentOutput() {
     await current.writeChain;
     const output = serializeTerminalBuffer(current.term);
     const busy = Date.now() - current.lastOutputAt < current.busyWindowMs;
-    return { output, busy };
+    // The grid the screen above was laid out FOR. A viewer that renders it at
+    // any other width re-wraps every long line — the dump has no width of its
+    // own, only the one the PTY composed it at.
+    return { output, busy, cols: current.cols, rows: current.rows };
 }

package/dist/output-stream.js

@@ -0,0 +1,282 @@
+/**
+ * Volume control for the daemon→server live output stream
+ * (docs/YOLOBRIDGE_PLAN.md, "Live terminal streaming").
+ *
+ * PURE — no timers, no network, no PTY. `attach-cmd.ts` owns the flush tick
+ * and the POST; this file owns the only question that is genuinely hard:
+ * **what do we send, and what do we refuse to send, when the PTY produces
+ * more than the link (or the operator's bandwidth budget) can carry?**
+ *
+ * PTY output is bursty and can be enormous — a build log, `yes`, a `cat` of a
+ * multi-megabyte file. Relaying it verbatim would turn one careless command on
+ * the operator's laptop into an unbounded upload and an unbounded fan-out onto
+ * the workspace event bus. Three independent bounds, each doing a different
+ * job:
+ *
+ *   1. **`maxQueueBytes`** — the standing backlog. When the producer outruns
+ *      the drain the queue is trimmed from the FRONT (oldest first), because
+ *      on a terminal the newest bytes are the ones the viewer needs: they are
+ *      what is on screen right now. The trimmed byte count is REMEMBERED, not
+ *      forgotten (see `droppedBytes`).
+ *   2. **`maxBatchBytes`** — the size of any single POST, so one flush can
+ *      never produce a request the server has to buffer megabytes for.
+ *   3. **`maxBytesPerSecond`** — a token bucket over the whole stream. This is
+ *      the one that actually caps sustained cost; the other two bound a single
+ *      moment. A full bucket is allowed as a one-second burst, so ordinary
+ *      agent output (which is bursty but small) is never throttled at all.
+ *
+ * **A drop is always MARKED, never silent.** `drain()` returns the number of
+ * bytes skipped alongside the data that follows them, and the viewer renders
+ * an explicit gap marker and re-seeds from the poll route. That matters
+ * specifically because this is a TERMINAL: dropping bytes out of a stream of
+ * cursor-addressing escapes does not degrade gracefully into "slightly less
+ * text", it produces a screen that is confidently wrong. Telling the viewer
+ * "there is a hole here" is what lets it recover instead of lying.
+ *
+ * Byte lengths are UTF-8 (`Buffer.byteLength`), because that is what actually
+ * crosses the wire — not `String.length`, which under-counts every non-ASCII
+ * character an agent's box-drawing/emoji output is full of.
+ */
+/** Default flush cadence, owned by the caller — exported here so the tuning
+ *  constants that describe one mechanism live together. Short enough that
+ *  output reads as live, long enough that a chatty PTY costs ~12 POSTs/second
+ *  rather than one per `onData`. */
+export const DEFAULT_FLUSH_INTERVAL_MS = 80;
+/** ~192 KiB/s sustained. Comfortably above a fast agent's real output rate
+ *  (a streaming LLM response is a few KiB/s), far below what `cat`ting a
+ *  large file would produce. */
+export const DEFAULT_MAX_BYTES_PER_SECOND = 192 * 1024;
+/** One POST never carries more than this. At the default flush interval this
+ *  is also well above the per-tick share of the rate cap, so it only ever
+ *  binds on the very first tick after an idle period (when the token bucket
+ *  is full). */
+export const DEFAULT_MAX_BATCH_BYTES = 32 * 1024;
+/** Standing backlog cap. Two seconds of rate-capped output — enough to ride
+ *  out one slow POST without dropping anything, small enough that a runaway
+ *  producer can never grow the daemon's heap. */
+export const DEFAULT_MAX_QUEUE_BYTES = 384 * 1024;
+/**
+ * Longest prefix of `s` whose UTF-8 encoding is at most `maxBytes`, plus the
+ * remainder.
+ *
+ * Never splits a surrogate pair: a JS string is UTF-16, and cutting between
+ * the halves of an astral character (an emoji in an agent's output) produces a
+ * lone surrogate, which `JSON.stringify` escapes into a value the server
+ * decodes back as U+FFFD — a permanently corrupted character rather than one
+ * that reassembles on the far side. Splitting only at code-point boundaries
+ * makes the two halves concatenate back into exactly the original text.
+ *
+ * Fast path for pure ASCII (`byteLength === length`), which is the
+ * overwhelming majority of terminal output; the walk is only paid for when a
+ * chunk actually contains multibyte characters AND is large enough to need
+ * splitting.
+ */
+export function splitByUtf8Bytes(s, maxBytes) {
+    if (maxBytes <= 0)
+        return { head: '', tail: s };
+    const total = Buffer.byteLength(s, 'utf-8');
+    if (total <= maxBytes)
+        return { head: s, tail: '' };
+    if (total === s.length) {
+        // Pure ASCII — one byte per UTF-16 code unit, so the cut is exact.
+        return { head: s.slice(0, maxBytes), tail: s.slice(maxBytes) };
+    }
+    let bytes = 0;
+    let i = 0;
+    while (i < s.length) {
+        const code = s.codePointAt(i);
+        const units = code > 0xffff ? 2 : 1;
+        const size = code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+        if (bytes + size > maxBytes)
+            break;
+        bytes += size;
+        i += units;
+    }
+    return { head: s.slice(0, i), tail: s.slice(i) };
+}
+/**
+ * Bounded, rate-limited FIFO of PTY output awaiting relay.
+ *
+ * Holds JS strings rather than Buffers because that is what `node-pty` hands
+ * us and what the JSON body carries — converting to bytes and back would add
+ * two encodes per chunk for no gain, and the only place byte counts matter
+ * (the caps) can measure them on demand.
+ */
+export class OutputStreamBuffer {
+    maxQueueBytes;
+    maxBatchBytes;
+    maxBytesPerSecond;
+    now;
+    chunks = [];
+    queuedBytesValue = 0;
+    droppedBytes = 0;
+    /** Absolute offset of the first byte still queued (== `writeOffset` when the
+     *  queue is empty). Advanced by everything that LEAVES the queue, whether it
+     *  was drained or trimmed, so it always names the next byte a viewer has not
+     *  been offered. */
+    headOffset = 0;
+    /** Absolute offset one past the last byte ever pushed. */
+    writeOffset = 0;
+    /** Token bucket, in bytes. Starts FULL so the first burst after an idle
+     *  period (the common case — a viewer opens the tile and the agent starts
+     *  talking) is never throttled. */
+    tokens;
+    lastRefillAt;
+    constructor(opts = {}) {
+        this.maxQueueBytes = opts.maxQueueBytes ?? DEFAULT_MAX_QUEUE_BYTES;
+        this.maxBatchBytes = opts.maxBatchBytes ?? DEFAULT_MAX_BATCH_BYTES;
+        this.maxBytesPerSecond = opts.maxBytesPerSecond ?? DEFAULT_MAX_BYTES_PER_SECOND;
+        this.now = opts.now ?? Date.now;
+        this.tokens = this.maxBytesPerSecond;
+        this.lastRefillAt = this.now();
+        this.headOffset = opts.startOffset ?? 0;
+        this.writeOffset = this.headOffset;
+    }
+    /**
+     * Rebase this buffer onto a new absolute byte position. Only meaningful on
+     * an EMPTY buffer — it is called when a streaming episode starts (priming
+     * from local-agent.ts's raw ring) and when the PTY session underneath is
+     * replaced, both of which discard whatever was queued first.
+     */
+    setBaseOffset(offset) {
+        this.headOffset = offset;
+        this.writeOffset = offset;
+    }
+    /** Absolute offset of the next byte a viewer has not been offered yet. */
+    get nextOffset() {
+        return this.headOffset;
+    }
+    get queuedBytes() {
+        return this.queuedBytesValue;
+    }
+    /** Bytes skipped so far and not yet reported to the viewer. */
+    get pendingDroppedBytes() {
+        return this.droppedBytes;
+    }
+    /**
+     * Enqueue raw PTY output, trimming the OLDEST bytes if that pushes the
+     * backlog past `maxQueueBytes`.
+     *
+     * A single chunk larger than the whole cap is itself trimmed from its front,
+     * so `push` can never leave the queue over the bound no matter what one
+     * `onData` delivers.
+     */
+    push(chunk) {
+        if (!chunk)
+            return;
+        this.chunks.push(chunk);
+        const pushed = Buffer.byteLength(chunk, 'utf-8');
+        this.queuedBytesValue += pushed;
+        this.writeOffset += pushed;
+        this.trim();
+    }
+    /**
+     * Record bytes that were LOST rather than queued — today, a batch whose POST
+     * failed after `drain()` had already handed the bytes over. Reporting them
+     * as a gap is the honest outcome: they are gone, and the viewer's screen is
+     * missing them either way. Re-queueing them instead would reorder the stream
+     * behind whatever arrived while the POST was in flight, which on a terminal
+     * is worse than an acknowledged hole.
+     */
+    noteDropped(bytes) {
+        if (bytes > 0)
+            this.droppedBytes += bytes;
+    }
+    trim() {
+        while (this.queuedBytesValue > this.maxQueueBytes && this.chunks.length > 0) {
+            const overflow = this.queuedBytesValue - this.maxQueueBytes;
+            const oldest = this.chunks[0];
+            const oldestBytes = Buffer.byteLength(oldest, 'utf-8');
+            if (oldestBytes <= overflow) {
+                this.chunks.shift();
+                this.queuedBytesValue -= oldestBytes;
+                this.droppedBytes += oldestBytes;
+                this.headOffset += oldestBytes;
+                continue;
+            }
+            // Partially trim the oldest chunk: drop exactly the overflow off its
+            // front (at a code-point boundary) and keep the rest.
+            const { head } = splitByUtf8Bytes(oldest, overflow);
+            const dropped = Buffer.byteLength(head, 'utf-8');
+            const kept = oldest.slice(head.length);
+            this.chunks[0] = kept;
+            this.queuedBytesValue -= dropped;
+            this.droppedBytes += dropped;
+            this.headOffset += dropped;
+            // `splitByUtf8Bytes` can stop just SHORT of `overflow` when the next
+            // code point straddles the boundary; loop again rather than assuming one
+            // pass is enough.
+            if (dropped === 0) {
+                // Cannot make progress (a single code point wider than the overflow):
+                // drop the whole chunk rather than spin.
+                this.chunks.shift();
+                this.queuedBytesValue -= oldestBytes;
+                this.droppedBytes += oldestBytes;
+                this.headOffset += oldestBytes;
+            }
+        }
+    }
+    refill() {
+        const at = this.now();
+        const elapsedMs = at - this.lastRefillAt;
+        if (elapsedMs <= 0)
+            return;
+        this.lastRefillAt = at;
+        this.tokens = Math.min(this.maxBytesPerSecond, this.tokens + (this.maxBytesPerSecond * elapsedMs) / 1000);
+    }
+    /**
+     * Take the next batch to relay, or `null` when there is nothing to send
+     * right now (empty queue with no gap to report, or the rate cap is spent).
+     *
+     * Spending the rate cap is deliberately NOT an error and does not itself
+     * drop anything: the bytes stay queued and go out on a later tick. They are
+     * only dropped if the producer keeps running long enough to overflow
+     * `maxQueueBytes` — which is exactly the "genuinely more output than we will
+     * ever relay" case, and is reported as a gap when it happens.
+     */
+    drain() {
+        this.refill();
+        const allowance = Math.min(this.maxBatchBytes, Math.floor(this.tokens));
+        if (allowance <= 0)
+            return null;
+        const startOffset = this.headOffset;
+        let taken = '';
+        let takenBytes = 0;
+        while (this.chunks.length > 0 && takenBytes < allowance) {
+            const chunk = this.chunks[0];
+            const chunkBytes = Buffer.byteLength(chunk, 'utf-8');
+            if (takenBytes + chunkBytes <= allowance) {
+                taken += chunk;
+                takenBytes += chunkBytes;
+                this.chunks.shift();
+                this.queuedBytesValue -= chunkBytes;
+                continue;
+            }
+            const { head, tail } = splitByUtf8Bytes(chunk, allowance - takenBytes);
+            if (!head)
+                break; // next code point doesn't fit — leave it for the next tick
+            const headBytes = Buffer.byteLength(head, 'utf-8');
+            taken += head;
+            takenBytes += headBytes;
+            this.chunks[0] = tail;
+            this.queuedBytesValue -= headBytes;
+            break;
+        }
+        const droppedBytes = this.droppedBytes;
+        if (takenBytes === 0 && droppedBytes === 0)
+            return null;
+        this.droppedBytes = 0;
+        this.tokens -= takenBytes;
+        this.headOffset += takenBytes;
+        return { data: taken, droppedBytes, startOffset };
+    }
+    /** Forget everything queued. Used when a stream ends — those bytes belong to
+     *  a `streamId` that no longer exists, and carrying them into the next
+     *  stream would splice one session's screen into another's. */
+    reset() {
+        this.chunks = [];
+        this.queuedBytesValue = 0;
+        this.droppedBytes = 0;
+        this.headOffset = this.writeOffset;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-labs/yolobridge",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "YoloBridge — 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",