@yolo-labs/yolobridge 0.11.0 → 0.12.0

package/dist/ansi-replay-state.js

@@ -0,0 +1,661 @@
+/**
+ * The two things a RAW-BYTE replay cannot get right on its own
+ * (docs/YOLOBRIDGE_PLAN.md, "Live terminal streaming").
+ *
+ * `local-agent.ts`'s ring gives a remote viewer the daemon's last
+ * `RAW_RING_MAX_BYTES` of PTY output to replay, and replaying bytes is exact
+ * where reconstructing state is not. But a ring is a WINDOW onto a byte
+ * stream, and a window has two edges that raw replay alone gets wrong:
+ *
+ *   1. **The window can open mid-escape-sequence.** The ring's `baseOffset`
+ *      (and the stream prime's start point) is wherever the trim happened to
+ *      land — an arbitrary byte. Land it inside `ESC [ 3 8 ; 5 ; 1 9 6 m` and
+ *      the viewer's xterm parses `8;5;196m` as TEXT, prints it, and carries on
+ *      with whatever SGR/mode state that left behind — possibly forever. This
+ *      is not a rare case: escapes are a large fraction of a TUI's bytes.
+ *
+ *      Fixed by `AnsiScanner`, an escape-state machine run over the SAME byte
+ *      stream the terminal consumed, which records the absolute offsets at
+ *      which the parser is in GROUND state. A replay that starts at a ground
+ *      offset starts where a fresh parser and the daemon's parser agree.
+ *
+ *      Deliberately NOT "scan back to the last `\n`": an OSC string (a window
+ *      title, an OSC 8 hyperlink, an OSC 52 clipboard payload) can contain a
+ *      newline, so the newline heuristic is wrong in exactly the cases that
+ *      matter. This is exact.
+ *
+ *   2. **The window can have rolled past a STICKY MODE.** The escape that
+ *      entered the alternate screen, set the scroll region (DECSTBM), hid the
+ *      cursor or turned autowrap off may be older than the oldest retained
+ *      byte. Replay cannot restore what it no longer holds, and every one of
+ *      those changes where subsequent output LANDS.
+ *
+ *      Fixed by `TerminalModeTracker`, which watches the same byte stream for
+ *      exactly those sticky sequences and can emit a short, idempotent MODE
+ *      PROLOGUE ahead of the replay tail. See `buildModePrologue` for the
+ *      split between what is read from the daemon's own `Terminal` (the
+ *      authority) and what this tracker supplies because the public API does
+ *      not expose it.
+ *
+ * PURE. No terminal, no timers, no I/O — every function here is a fold over a
+ * string, which is what makes the whole thing testable byte by byte.
+ *
+ * ⚠️ UTF-8 BYTE OFFSETS, not UTF-16 code units. Every offset this module
+ * produces or consumes is an absolute UTF-8 byte position in the PTY's byte
+ * stream, because that is what the ring, the chunk protocol and the viewer's
+ * splice arithmetic are all measured in.
+ *
+ * KNOWN LIMIT, stated rather than hidden: 8-bit C1 control bytes (a bare 0x9B
+ * as CSI, 0x9D as OSC) are not recognised. In a UTF-8 PTY — which is what
+ * every agent this daemon runs produces — those byte values only ever occur
+ * as continuation bytes inside a multi-byte character, where treating them as
+ * ordinary text is the correct reading.
+ */
+/** Cap on collected CSI parameter bytes. A real sequence is a few dozen bytes;
+ *  this bounds what a hostile or corrupted stream can make us retain. Past the
+ *  cap the parameters are truncated, which makes the sequence unrecognised —
+ *  the safe failure, since an unrecognised sticky mode is simply not restored
+ *  rather than restored wrongly. */
+const MAX_CSI_PARAM_CHARS = 256;
+/**
+ * A resumable escape-state machine over a UTF-8 byte stream.
+ *
+ * Resumable is the point: the ring's oldest retained byte is not the stream's
+ * first byte, so answering "is offset X ground?" requires knowing the parser
+ * state at the start of what is retained. `local-agent.ts` keeps one scanner
+ * fed with the bytes it TRIMS (giving the state at `baseOffset`) and one fed
+ * with every byte it PUSHES (driving the mode tracker).
+ */
+export class AnsiScanner {
+    state = 'ground';
+    collected = '';
+    /** Start over from a known state — used to fork a scan from a saved
+     *  position without replaying the stream that led to it. */
+    reset(state = 'ground') {
+        this.state = state;
+        this.collected = '';
+    }
+    /**
+     * Consume `text`, whose first byte sits at absolute offset `startOffset`.
+     * Returns the absolute offset one past its last byte.
+     *
+     * Iterates CODE POINTS while accounting in BYTES: every byte that can change
+     * parser state is ASCII, so a multi-byte character is always a single
+     * indivisible "printable" — which is exactly what makes it safe to walk the
+     * JS string the ring actually stores instead of encoding it to a Buffer.
+     */
+    feed(text, startOffset, sink) {
+        let offset = startOffset;
+        for (let i = 0; i < text.length;) {
+            const code = text.codePointAt(i);
+            const units = code > 0xffff ? 2 : 1;
+            const size = code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+            // Reported BEFORE consuming: a replay that begins at this offset begins
+            // by parsing this code point, which is only safe from ground.
+            if (this.state === 'ground')
+                sink?.ground?.(offset);
+            this.step(code, sink);
+            offset += size;
+            i += units;
+        }
+        // The position after the last byte is a valid start too, when it is ground.
+        if (this.state === 'ground')
+            sink?.ground?.(offset);
+        return offset;
+    }
+    step(code, sink) {
+        switch (this.state) {
+            case 'ground':
+                if (code === 0x1b)
+                    this.enterEsc();
+                return;
+            case 'esc':
+                this.stepEsc(code, sink);
+                return;
+            case 'esc-intermediate':
+                if (code >= 0x20 && code <= 0x2f)
+                    return; // more intermediates
+                if (code === 0x1b)
+                    return this.enterEsc();
+                // A final byte (or anything else) ends the sequence. Nothing here is
+                // a sticky mode, so no sink callback.
+                this.state = 'ground';
+                return;
+            case 'csi':
+                if (code === 0x1b)
+                    return this.enterEsc();
+                // CAN / SUB abort a sequence in progress, everywhere.
+                if (code === 0x18 || code === 0x1a) {
+                    this.state = 'ground';
+                    return;
+                }
+                if (code >= 0x40 && code <= 0x7e) {
+                    const params = this.collected;
+                    this.collected = '';
+                    this.state = 'ground';
+                    sink?.csi?.(params, String.fromCharCode(code));
+                    return;
+                }
+                if (code >= 0x20 && code <= 0x3f) {
+                    if (this.collected.length < MAX_CSI_PARAM_CHARS) {
+                        this.collected += String.fromCharCode(code);
+                    }
+                    return;
+                }
+                // A C0 control inside a CSI is EXECUTED and the sequence continues —
+                // so this is still not a ground boundary.
+                return;
+            case 'string':
+                if (code === 0x07) {
+                    this.state = 'ground'; // BEL terminates an OSC
+                    return;
+                }
+                if (code === 0x1b) {
+                    this.state = 'string-esc';
+                    return;
+                }
+                if (code === 0x18 || code === 0x1a) {
+                    this.state = 'ground';
+                    return;
+                }
+                // Everything else — INCLUDING `\n` — is string content. This is the
+                // whole reason "scan back to the last newline" is not a substitute.
+                return;
+            case 'string-esc':
+                if (code === 0x5c) {
+                    this.state = 'ground'; // ST (`ESC \`)
+                    return;
+                }
+                // The string ended and a fresh escape sequence began.
+                this.enterEsc();
+                this.stepEsc(code, sink);
+                return;
+            case 'single-shift':
+                // Exactly one character is shifted; whatever it was, we are back.
+                this.state = 'ground';
+                return;
+        }
+    }
+    enterEsc() {
+        this.state = 'esc';
+        this.collected = '';
+    }
+    stepEsc(code, sink) {
+        if (code === 0x1b)
+            return this.enterEsc();
+        if (code === 0x5b) {
+            // `[` — CSI
+            this.state = 'csi';
+            this.collected = '';
+            return;
+        }
+        // `]` OSC, `P` DCS, `X` SOS, `^` PM, `_` APC — all string sequences.
+        if (code === 0x5d || code === 0x50 || code === 0x58 || code === 0x5e || code === 0x5f) {
+            this.state = 'string';
+            return;
+        }
+        if (code === 0x4e || code === 0x4f) {
+            // `N` SS2 / `O` SS3
+            this.state = 'single-shift';
+            return;
+        }
+        if (code >= 0x20 && code <= 0x2f) {
+            this.state = 'esc-intermediate';
+            return;
+        }
+        if (code >= 0x30 && code <= 0x7e) {
+            this.state = 'ground';
+            sink?.esc?.(String.fromCharCode(code));
+            return;
+        }
+        // A control byte (or a stray continuation byte) after ESC: xterm executes
+        // it and abandons the sequence.
+        this.state = 'ground';
+    }
+}
+/**
+ * The absolute offset a replay of `text` should actually start at, given that
+ * the caller WANTS to start at `target`.
+ *
+ * Prefers the greatest ground offset **at or before** `target`, because
+ * starting earlier only ever replays a few extra bytes the viewer would have
+ * applied anyway. Falls back to the smallest ground offset AFTER `target` when
+ * nothing earlier is retained — which is the ring's own case: `baseOffset` is
+ * the oldest byte in existence, so a partial escape sitting on it can only be
+ * skipped, never completed.
+ *
+ * Returns the end of `text` when the whole retained window is inside one
+ * unterminated sequence (a multi-hundred-kilobyte OSC). An empty replay is the
+ * honest answer there: every byte in the window is a fragment of something the
+ * viewer cannot parse the same way the daemon did.
+ */
+export function resolveGroundStart(text, textStartOffset, stateAtStart, target) {
+    const scanner = new AnsiScanner();
+    scanner.reset(stateAtStart);
+    let before = -1;
+    let after = -1;
+    const end = scanner.feed(text, textStartOffset, {
+        ground(offset) {
+            // Ground offsets arrive in increasing order, so the first one past the
+            // target is the smallest one past it.
+            if (offset <= target)
+                before = offset;
+            else if (after < 0)
+                after = offset;
+        },
+    });
+    if (before >= 0)
+        return before;
+    if (after >= 0)
+        return after;
+    return end;
+}
+export const DEFAULT_SGR = {
+    bold: false,
+    dim: false,
+    italic: false,
+    underline: false,
+    blink: false,
+    inverse: false,
+    invisible: false,
+    strikethrough: false,
+    fg: null,
+    bg: null,
+};
+export function sgrIsDefault(s) {
+    return (!s.bold && !s.dim && !s.italic && !s.underline && !s.blink &&
+        !s.inverse && !s.invisible && !s.strikethrough && s.fg === null && s.bg === null);
+}
+/**
+ * Watches the PTY byte stream for the sticky modes the daemon's own
+ * `Terminal` does not expose through its PUBLIC API.
+ *
+ * ⚠️ SCOPE, AND WHY THIS IS NOT "STATE INFERENCE". This does not look at a
+ * rendered screen and guess how it got that way — the thing the raw-replay
+ * design exists to eliminate. It reads the identical byte stream the
+ * authoritative parser read, and understands exactly four sequence families
+ * (DECSTBM, DECTCEM, the alternate-screen DEC private modes, and SGR) plus
+ * the two resets that clear them. Anything else it sees, it ignores.
+ *
+ * It exists only because `@xterm/headless`'s `IModes`/`IBuffer` expose neither
+ * the scroll region, nor cursor visibility, nor the current SGR attributes.
+ * Where the public API DOES expose a mode, `buildModePrologue` reads it from
+ * the terminal instead of from here — see that function.
+ */
+export class TerminalModeTracker {
+    rows;
+    normalRegion;
+    altRegion;
+    altActive = false;
+    cursorHidden = false;
+    sgr = { ...DEFAULT_SGR };
+    constructor(rows) {
+        this.rows = Math.max(1, Math.floor(rows) || 1);
+        this.normalRegion = this.fullRegion();
+        this.altRegion = this.fullRegion();
+    }
+    /** Feed this to `AnsiScanner.feed`. */
+    sink = {
+        csi: (params, final) => this.onCsi(params, final),
+        esc: (final) => this.onEsc(final),
+    };
+    /** The scroll region in force on the named buffer. The caller passes the
+     *  buffer the TERMINAL reports as active, so the two sources cannot drift
+     *  into reporting a region for a screen that is not showing. */
+    regionFor(buffer) {
+        return buffer === 'alternate' ? this.altRegion : this.normalRegion;
+    }
+    /** DECTCEM: `CSI ? 25 l` hides, `CSI ? 25 h` shows. Default: visible. */
+    get isCursorHidden() {
+        return this.cursorHidden;
+    }
+    /** The SGR attributes the next printed character would be drawn with. */
+    get sgrState() {
+        return this.sgr;
+    }
+    /** Whether the tracker believes the alternate screen is active. Only used
+     *  to route DECSTBM to the right buffer; the PROLOGUE takes the flag itself
+     *  from the terminal. */
+    get isAltScreen() {
+        return this.altActive;
+    }
+    isFullRegion(region) {
+        return region.top === 1 && region.bottom === this.rows;
+    }
+    fullRegion() {
+        return { top: 1, bottom: this.rows };
+    }
+    onEsc(final) {
+        if (final === 'c')
+            this.hardReset(); // RIS
+    }
+    onCsi(params, final) {
+        // DECSTR (`CSI ! p`) — a soft reset.
+        if (final === 'p' && params === '!') {
+            this.softReset();
+            return;
+        }
+        const isPrivate = params.charCodeAt(0) === 0x3f; // '?'
+        const body = isPrivate ? params.slice(1) : params;
+        if (final === 'h' || final === 'l') {
+            // Only DEC PRIVATE modes are tracked here. The ANSI ones this prologue
+            // cares about (IRM) are readable from the terminal's public `modes`.
+            if (!isPrivate)
+                return;
+            const on = final === 'h';
+            for (const token of body.split(';')) {
+                const n = Number(token);
+                if (!Number.isFinite(n))
+                    continue;
+                if (n === 25)
+                    this.cursorHidden = !on;
+                else if (n === 1049 || n === 1047 || n === 47)
+                    this.setAltScreen(on);
+            }
+            return;
+        }
+        if (final === 'r' && !isPrivate) {
+            this.setScrollRegion(body);
+            return;
+        }
+        if (final === 'm' && !isPrivate) {
+            this.applySgr(body);
+        }
+    }
+    /**
+     * Entering OR leaving the alternate screen resets the ALT buffer's scroll
+     * region to the full screen, while the normal buffer's survives the round
+     * trip. That is xterm's observed behaviour, and it is why the two regions
+     * are tracked separately rather than as one value.
+     */
+    setAltScreen(on) {
+        if (this.altActive === on)
+            return;
+        this.altActive = on;
+        this.altRegion = this.fullRegion();
+    }
+    /**
+     * DECSTBM. Absent parameters mean "the whole screen"; a bottom past the last
+     * row is clamped; a degenerate or inverted region is IGNORED and leaves the
+     * previous one in force — all three matching what xterm does with the same
+     * bytes.
+     */
+    setScrollRegion(body) {
+        const parts = body.split(';');
+        const rawTop = parts[0] ? Number(parts[0]) : 1;
+        const rawBottom = parts.length > 1 && parts[1] ? Number(parts[1]) : this.rows;
+        if (!Number.isFinite(rawTop) || !Number.isFinite(rawBottom))
+            return;
+        const top = rawTop < 1 ? 1 : Math.floor(rawTop);
+        const bottom = Math.floor(rawBottom > this.rows ? this.rows : rawBottom);
+        if (bottom <= top)
+            return;
+        const region = { top, bottom };
+        if (this.altActive)
+            this.altRegion = region;
+        else
+            this.normalRegion = region;
+    }
+    /** RIS (`ESC c`) — everything back to power-on. */
+    hardReset() {
+        this.normalRegion = this.fullRegion();
+        this.altRegion = this.fullRegion();
+        this.altActive = false;
+        this.cursorHidden = false;
+        this.sgr = { ...DEFAULT_SGR };
+    }
+    /** DECSTR (`CSI ! p`) — scroll region, cursor visibility and SGR reset; the
+     *  active buffer is NOT switched. */
+    softReset() {
+        this.normalRegion = this.fullRegion();
+        this.altRegion = this.fullRegion();
+        this.cursorHidden = false;
+        this.sgr = { ...DEFAULT_SGR };
+    }
+    applySgr(body) {
+        const tokens = body === '' ? ['0'] : body.split(';');
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            // Colon sub-parameters (`4:3` for curly underline, `38:5:196` for an
+            // indexed colour) are a single parameter as far as `;` splitting is
+            // concerned, so they are unpacked here rather than in the loop below.
+            if (token.includes(':')) {
+                this.applySgrSubParam(token);
+                continue;
+            }
+            const n = Number(token === '' ? '0' : token);
+            if (!Number.isFinite(n))
+                continue;
+            if (n === 38 || n === 48) {
+                i = this.applyExtendedColor(tokens, i, n === 38);
+                continue;
+            }
+            this.applySgrCode(n);
+        }
+    }
+    applySgrCode(n) {
+        switch (true) {
+            case n === 0:
+                this.sgr = { ...DEFAULT_SGR };
+                return;
+            case n === 1:
+                this.sgr = { ...this.sgr, bold: true };
+                return;
+            case n === 2:
+                this.sgr = { ...this.sgr, dim: true };
+                return;
+            case n === 3:
+                this.sgr = { ...this.sgr, italic: true };
+                return;
+            // 21 is doubly-underlined in xterm, not "bold off".
+            case n === 4 || n === 21:
+                this.sgr = { ...this.sgr, underline: true };
+                return;
+            case n === 5 || n === 6:
+                this.sgr = { ...this.sgr, blink: true };
+                return;
+            case n === 7:
+                this.sgr = { ...this.sgr, inverse: true };
+                return;
+            case n === 8:
+                this.sgr = { ...this.sgr, invisible: true };
+                return;
+            case n === 9:
+                this.sgr = { ...this.sgr, strikethrough: true };
+                return;
+            case n === 22:
+                this.sgr = { ...this.sgr, bold: false, dim: false };
+                return;
+            case n === 23:
+                this.sgr = { ...this.sgr, italic: false };
+                return;
+            case n === 24:
+                this.sgr = { ...this.sgr, underline: false };
+                return;
+            case n === 25:
+                this.sgr = { ...this.sgr, blink: false };
+                return;
+            case n === 27:
+                this.sgr = { ...this.sgr, inverse: false };
+                return;
+            case n === 28:
+                this.sgr = { ...this.sgr, invisible: false };
+                return;
+            case n === 29:
+                this.sgr = { ...this.sgr, strikethrough: false };
+                return;
+            case n === 39:
+                this.sgr = { ...this.sgr, fg: null };
+                return;
+            case n === 49:
+                this.sgr = { ...this.sgr, bg: null };
+                return;
+            case (n >= 30 && n <= 37) || (n >= 90 && n <= 97):
+                this.sgr = { ...this.sgr, fg: String(n) };
+                return;
+            case (n >= 40 && n <= 47) || (n >= 100 && n <= 107):
+                this.sgr = { ...this.sgr, bg: String(n) };
+                return;
+            default:
+                // Deliberately unhandled: 10-20 (fonts), 26/50-55 (proportional,
+                // framed, overlined), 58/59 (underline colour), 73-75 (super/sub).
+                // Not restoring an attribute we do not model is honest; restoring a
+                // guessed one is not. Divergence from an unmodelled attribute is what
+                // the viewer's integrity check exists to catch.
+                return;
+        }
+    }
+    /** `38:5:196`, `48:2::10:20:30`, `4:3`, … */
+    applySgrSubParam(token) {
+        const parts = token.split(':');
+        const head = Number(parts[0]);
+        if (!Number.isFinite(head))
+            return;
+        if (head === 4) {
+            // `4:0` is underline off; every other sub-value is some underline style.
+            this.sgr = { ...this.sgr, underline: parts[1] !== '0' };
+            return;
+        }
+        if (head === 38 || head === 48) {
+            // Re-spell in the semicolon form, dropping the colon form's empty
+            // colour-space slot (`38:2::r:g:b`).
+            const rest = parts.slice(1).filter((p) => p !== '');
+            if (rest.length === 0)
+                return;
+            const fragment = `${head};${rest.join(';')}`;
+            this.sgr = head === 38 ? { ...this.sgr, fg: fragment } : { ...this.sgr, bg: fragment };
+            return;
+        }
+        this.applySgrCode(head);
+    }
+    /**
+     * `38;5;n` (indexed) / `38;2;r;g;b` (direct), and the same for `48`.
+     * Returns the index of the LAST token consumed so the caller's loop resumes
+     * after the whole colour, never re-reading a channel value as a new
+     * attribute (which is how `38;2;1;7;0` would silently turn on inverse).
+     */
+    applyExtendedColor(tokens, i, isFg) {
+        const kind = Number(tokens[i + 1]);
+        let consumed;
+        if (kind === 5)
+            consumed = 2;
+        else if (kind === 2)
+            consumed = 4;
+        else
+            return i; // malformed — ignore the introducer and keep parsing
+        const slice = tokens.slice(i, i + consumed + 1);
+        if (slice.length < consumed + 1)
+            return tokens.length; // truncated
+        const fragment = slice.join(';');
+        this.sgr = isFg ? { ...this.sgr, fg: fragment } : { ...this.sgr, bg: fragment };
+        return i + consumed;
+    }
+}
+const ESC = '\x1b';
+/**
+ * A short escape prologue that puts a fresh terminal into the daemon's sticky
+ * mode state, to be written IMMEDIATELY BEFORE a truncated raw replay tail.
+ *
+ * ⚠️ EMIT THIS ONLY WHEN THE REPLAY IS TRUNCATED. When the ring still holds
+ * the whole session the replay is self-contained by construction and a
+ * prologue is pure risk for no gain — it would be re-asserting state the tail
+ * is about to set anyway, and two of these sequences (DECOM, DECSTBM) move the
+ * cursor as a side effect.
+ *
+ * ONLY NON-DEFAULT MODES ARE EMITTED, for that same reason: a viewer's
+ * terminal has just been `reset()`, so it is already at power-on defaults, and
+ * `CSI ? 6 l` on an already-unset origin mode is not a no-op — it homes the
+ * cursor. When the daemon is in a wholly default state this returns `''`.
+ *
+ * WHAT IS RESTORED, and from where:
+ *   - alternate screen        ← the terminal (`buffer.active.type`)
+ *   - autowrap (DECAWM)       ← the terminal (`modes.wraparoundMode`)
+ *   - origin mode (DECOM)     ← the terminal (`modes.originMode`)
+ *   - insert mode (IRM)       ← the terminal (`modes.insertMode`)
+ *   - reverse wraparound      ← the terminal (`modes.reverseWraparoundMode`)
+ *   - scroll region (DECSTBM) ← `TerminalModeTracker` (NOT on the public API)
+ *   - cursor visibility       ← `TerminalModeTracker` (NOT on the public API)
+ *   - current SGR             ← `TerminalModeTracker` (NOT on the public API)
+ *
+ * WHAT IS NOT RESTORED, deliberately:
+ *   - the daemon's CURRENT cursor position. The tail replays bytes the daemon
+ *     emitted in the PAST, from a cursor position that is also in the past;
+ *     homing to where the cursor is NOW would put the tail's first relative
+ *     move in the wrong place. The tail's own moves re-establish it.
+ *   - the saved cursor (DECSC), character sets (SCS), tab stops, the palette
+ *     (OSC 4), and the input-affecting modes (DECCKM, bracketed paste, mouse
+ *     reporting) — the last group because this tile has no input path at all.
+ *
+ * ⚠️ THE ONE CURSOR MOVE THAT IS EMITTED, and why it is not the above. When a
+ * SCROLL REGION is in force, the replay must not begin OUTSIDE it. A region
+ * confines scrolling to a band of rows; the rows outside that band are static,
+ * so anything the replay writes there before it converges stays there
+ * FOREVER — the tail will never scroll it away or paint over it. And a fresh
+ * terminal starts at row 1, which under a region like `3;10` is exactly one of
+ * those static rows.
+ *
+ * So the prologue parks the cursor at the region's bottom-left. That is not a
+ * guess at where the cursor WAS: it is the one thing actually known about it —
+ * the output being replayed scrolled within this region, so it was produced
+ * with the cursor inside it. Bottom-left is the position from which the first
+ * line feed scrolls rather than descending through rows the daemon was not
+ * writing to. With no region in force (the common full-screen TUI) nothing is
+ * emitted, because then every row scrolls and residue cannot persist.
+ *
+ * Ordering is load-bearing: the alternate-screen switch comes FIRST because
+ * DECSTBM is per-buffer; DECOM comes before the cursor park because setting it
+ * homes the cursor; SGR comes LAST because no mode set touches it.
+ */
+export function buildModePrologue(observed, tracker) {
+    let out = '';
+    if (observed.altScreen)
+        out += `${ESC}[?1049h`;
+    const region = tracker.regionFor(observed.altScreen ? 'alternate' : 'normal');
+    const scoped = !tracker.isFullRegion(region);
+    if (scoped)
+        out += `${ESC}[${region.top};${region.bottom}r`;
+    if (!observed.wraparound)
+        out += `${ESC}[?7l`;
+    if (observed.origin)
+        out += `${ESC}[?6h`;
+    if (observed.reverseWraparound)
+        out += `${ESC}[?45h`;
+    if (observed.insert)
+        out += `${ESC}[4h`;
+    if (tracker.isCursorHidden)
+        out += `${ESC}[?25l`;
+    if (scoped) {
+        // Bottom-left OF THE REGION — see the header. Under origin mode a CUP row
+        // is region-relative, so the same row has two spellings and using the
+        // wrong one would park the cursor outside the very band this exists to
+        // stay inside.
+        const row = observed.origin ? region.bottom - region.top + 1 : region.bottom;
+        out += `${ESC}[${row};1H`;
+    }
+    const sgr = tracker.sgrState;
+    if (!sgrIsDefault(sgr)) {
+        const codes = ['0'];
+        if (sgr.bold)
+            codes.push('1');
+        if (sgr.dim)
+            codes.push('2');
+        if (sgr.italic)
+            codes.push('3');
+        if (sgr.underline)
+            codes.push('4');
+        if (sgr.blink)
+            codes.push('5');
+        if (sgr.inverse)
+            codes.push('7');
+        if (sgr.invisible)
+            codes.push('8');
+        if (sgr.strikethrough)
+            codes.push('9');
+        if (sgr.fg)
+            codes.push(sgr.fg);
+        if (sgr.bg)
+            codes.push(sgr.bg);
+        out += `${ESC}[${codes.join(';')}m`;
+    }
+    return out;
+}

package/dist/api-client.js

@@ -206,8 +206,10 @@ export async function postReadOutputReply(cfg, workspaceId, attachmentId, reques
                 baseOffset: extra.raw.baseOffset,
                 endOffset: extra.raw.endOffset,
                 truncated: extra.raw.truncated,
+                ...(extra.raw.prologue ? { prologue: extra.raw.prologue } : {}),
             }
             : {}),
+        ...(extra?.screenDigest ? { screenDigest: extra.screenDigest } : {}),
     });
     return Boolean(body?.resolved);
 }

package/dist/attach-cmd.js

@@ -882,8 +882,14 @@ export async function runAttachDaemon(deps) {
                                                 endOffset: raw.endOffset,
                                                 data: raw.data,
                                                 truncated: raw.truncated,
+                                                prologue: raw.prologue,
                                             }
                                             : undefined,
+                                        // The viewer's integrity check compares this against a
+                                        // digest of its OWN rendered screen; a mismatch that
+                                        // survives the false-positive guards is the only
+                                        // available proof that the two parsers have diverged.
+                                        screenDigest: raw?.screenDigest,
                                     })
                                         .catch((err) => noteConnection('degraded', {
                                         detail: `read-output reply failed: ${err instanceof Error ? err.message : String(err)}`,

package/dist/local-agent.js

@@ -35,6 +35,9 @@ import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
 import * as pty from 'node-pty';
 import { splitByUtf8Bytes } from './output-stream.js';
+import { AnsiScanner, TerminalModeTracker, buildModePrologue, resolveGroundStart, } from './ansi-replay-state.js';
+import { screenDigest } from './screen-digest.js';
+export { screenDigest } from './screen-digest.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
@@ -172,8 +175,17 @@ export const RAW_RING_MAX_BYTES = 256 * 1024;
  * 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 };
+function newRawRing(rows = DEFAULT_ROWS) {
+    return {
+        epoch: randomUUID(),
+        chunks: [],
+        bytes: 0,
+        baseOffset: 0,
+        endOffset: 0,
+        baseScanner: new AnsiScanner(),
+        headScanner: new AnsiScanner(),
+        modes: new TerminalModeTracker(rows),
+    };
 }
 let rawRing = newRawRing();
 /** Append to the ring and return where the chunk landed. Synchronous and
@@ -182,6 +194,11 @@ let rawRing = newRawRing();
 function pushRaw(data) {
     const startOffset = rawRing.endOffset;
     const bytes = Buffer.byteLength(data, 'utf-8');
+    // Watch the bytes for sticky modes BEFORE they can be trimmed away. This is
+    // the only place that sees every byte of the session exactly once, which is
+    // what lets a truncated replay still be handed the alt-screen/scroll-region/
+    // cursor/SGR state that predates the ring (see `takeRawSeed`).
+    rawRing.headScanner.feed(data, startOffset, rawRing.modes.sink);
     rawRing.chunks.push(data);
     rawRing.bytes += bytes;
     rawRing.endOffset += bytes;
@@ -199,8 +216,7 @@ function trimRawRing() {
         const oldestBytes = Buffer.byteLength(oldest, 'utf-8');
         if (oldestBytes <= overflow) {
             rawRing.chunks.shift();
-            rawRing.bytes -= oldestBytes;
-            rawRing.baseOffset += oldestBytes;
+            dropFromFront(oldest, oldestBytes);
             continue;
         }
         const { head, tail } = splitByUtf8Bytes(oldest, overflow);
@@ -209,15 +225,28 @@ function trimRawRing() {
             // A single code point wider than the overflow — drop the chunk rather
             // than spin.
             rawRing.chunks.shift();
-            rawRing.bytes -= oldestBytes;
-            rawRing.baseOffset += oldestBytes;
+            dropFromFront(oldest, oldestBytes);
             continue;
         }
         rawRing.chunks[0] = tail;
-        rawRing.bytes -= droppedBytes;
-        rawRing.baseOffset += droppedBytes;
+        dropFromFront(head, droppedBytes);
     }
 }
+/**
+ * Account for `text` (exactly `byteLength` UTF-8 bytes) leaving the front of
+ * the ring.
+ *
+ * The scanner feed is the load-bearing part: once these bytes are gone, the
+ * ONLY record that the new `baseOffset` sits (say) three bytes into an OSC
+ * string is the parser state this leaves behind. Without it, a later
+ * `takeRawSeed` would hand a viewer a replay that begins mid-sequence and the
+ * viewer's xterm would print the remainder as text.
+ */
+function dropFromFront(text, byteLength) {
+    rawRing.baseScanner.feed(text, rawRing.baseOffset);
+    rawRing.bytes -= byteLength;
+    rawRing.baseOffset += byteLength;
+}
 /**
  * Take the current replay tail plus the PTY's grid size, as ONE synchronous
  * observation.
@@ -228,32 +257,85 @@ function trimRawRing() {
  * ≥ `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.
+ *
+ * ⚠️ CALL THIS ONLY AFTER THE TERMINAL HAS CAUGHT UP WITH THE RING. `prologue`
+ * and `screenDigest` are read from `current.term`, and that terminal is fed
+ * through an ASYNC write chain — so a seed taken mid-burst would describe the
+ * modes and the screen of a moment the ring has already moved past. The ring
+ * itself is written synchronously and is always current, which is exactly what
+ * makes the mismatch silent rather than obvious.
+ *
+ * `attach-cmd.ts` gets this right by construction: its `read-output` handler
+ * `await`s `captureOutput()` (which awaits the write chain) BEFORE calling
+ * this. Any new caller must do the same, and the tests do it deliberately.
  */
 export function takeRawSeed() {
     if (!current)
         return undefined;
+    const all = rawRing.chunks.join('');
+    // The ring's oldest retained byte is wherever the trim happened to land, so
+    // it can sit INSIDE an escape sequence. Starting there would feed a viewer's
+    // xterm the tail of a sequence it never saw the head of — which it renders
+    // as text and which can leave it in the wrong SGR or the wrong mode
+    // indefinitely. Nothing earlier than `baseOffset` still exists, so the only
+    // available correction is to skip forward to the next ground boundary; the
+    // few bytes discarded are a fragment no parser could have used.
+    const groundStart = resolveGroundStart(all, rawRing.baseOffset, rawRing.baseScanner.state, rawRing.baseOffset);
+    const data = groundStart > rawRing.baseOffset
+        ? splitByUtf8Bytes(all, groundStart - rawRing.baseOffset).tail
+        : all;
+    const truncated = rawRing.baseOffset > 0;
     return {
         epoch: rawRing.epoch,
-        baseOffset: rawRing.baseOffset,
+        // The offset the replay ACTUALLY starts at, not the one the ring happens
+        // to hold — the viewer positions itself by these numbers.
+        baseOffset: groundStart,
         endOffset: rawRing.endOffset,
-        data: rawRing.chunks.join(''),
+        data,
         cols: current.cols,
         rows: current.rows,
-        truncated: rawRing.baseOffset > 0,
+        truncated,
+        // Only a truncated replay is missing state that predates it.
+        ...(truncated ? { prologue: buildModePrologue(observedModes(current.term), rawRing.modes) } : {}),
+        screenDigest: screenDigest(current.term),
+    };
+}
+/**
+ * The sticky modes readable from the daemon's own terminal's PUBLIC API.
+ *
+ * This is the authority for everything it covers: that `Terminal` consumed
+ * every byte of the session, so what it reports is not an inference from a
+ * screen, it is the parser's own answer. What it does NOT cover — the scroll
+ * region, cursor visibility and current SGR, none of which appear on `IModes`
+ * or `IBuffer` — comes from `TerminalModeTracker` instead, and
+ * `buildModePrologue` documents the split.
+ */
+function observedModes(term) {
+    return {
+        altScreen: term.buffer.active.type === 'alternate',
+        wraparound: term.modes.wraparoundMode,
+        origin: term.modes.originMode,
+        insert: term.modes.insertMode,
+        reverseWraparound: term.modes.reverseWraparoundMode,
     };
 }
 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,
-    };
+    const naiveStart = total <= maxBytes
+        ? rawRing.baseOffset
+        : rawRing.baseOffset + Buffer.byteLength(splitByUtf8Bytes(all, total - maxBytes).head, 'utf-8');
+    // Same hazard as the seed, one degree milder: `maxBytes` is a budget, not a
+    // boundary, so the cut lands on an arbitrary byte and can sit inside an
+    // escape sequence. Unlike the seed, the bytes BEFORE the cut are still
+    // retained, so the fix here loses nothing at all — back up to the last
+    // boundary where a fresh parser and the daemon's agree. The handful of extra
+    // bytes are deduplicated by the viewer's offset arithmetic anyway.
+    const groundStart = resolveGroundStart(all, rawRing.baseOffset, rawRing.baseScanner.state, naiveStart);
+    const data = groundStart > rawRing.baseOffset
+        ? splitByUtf8Bytes(all, groundStart - rawRing.baseOffset).tail
+        : all;
+    return { epoch: rawRing.epoch, startOffset: groundStart, data };
 }
 /** 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). */
@@ -270,8 +352,8 @@ export function isLocalAgentBusy() {
     return Date.now() - current.lastOutputAt < current.busyWindowMs;
 }
 /** Test seam: forget the ring and start a fresh epoch. */
-export function __resetRawRing() {
-    rawRing = newRawRing();
+export function __resetRawRing(rows = DEFAULT_ROWS) {
+    rawRing = newRawRing(rows);
 }
 /**
  * Test seam: the daemon's OWN headless terminal — the thing a remote viewer
@@ -527,7 +609,7 @@ export function startLocalAgent(opts = {}) {
     // 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();
+    rawRing = newRawRing(rows);
     const state = {
         ptyProcess,
         term,

package/dist/screen-digest.js

@@ -0,0 +1,129 @@
+/**
+ * A cheap, comparable fingerprint of a terminal's VISIBLE SCREEN.
+ *
+ * ⚠️ MIRRORED IN THE WEBAPP as `webapp/lib/grid/terminal-screen-digest.ts`.
+ * The two must produce the SAME string for the same screen or the viewer's
+ * integrity check compares apples to oranges and either never fires or fires
+ * forever. Change them in the same commit; `screen-digest.test.ts` (here) and
+ * `terminal-screen-digest.test.ts` (there) pin the same fixture value from
+ * both sides.
+ *
+ * WHY IT EXISTS. Raw-byte replay makes the viewer's terminal a replica of the
+ * daemon's, and the offset arithmetic makes gaps detectable — but neither can
+ * PROVE that no byte sequence will ever desync the two parsers. Rather than
+ * claim a property that cannot be proved, the design guarantees a weaker one
+ * that can: divergence is DETECTED and corrected within a bounded time. This
+ * is the detector. The daemon reports the digest of its own screen alongside
+ * every poll; the viewer digests its own and compares.
+ *
+ * DESIGN NOTES, each of which is a bug avoided:
+ *
+ *   - **Viewport only, addressed from `baseY`.** Not the scrollback: a viewer
+ *     seeded from a rolled ring legitimately has less history than the daemon,
+ *     and hashing that would report a permanent, uncorrectable mismatch. And
+ *     `baseY` rather than `viewportY` so a reader who has scrolled up to read
+ *     something does not look like corruption.
+ *
+ *   - **The documented colour PREDICATES, not `getFgColorMode()`.** The
+ *     typings call that number opaque ("can be used to perform quick
+ *     comparisons of 2 cells") and point at `isFgRGB`/`isFgPalette`/
+ *     `isFgDefault` instead. The two sides of this comparison are two
+ *     different xterm builds — `@xterm/headless` in the daemon, `@xterm/xterm`
+ *     in the browser — so relying on an opaque constant agreeing across them
+ *     is exactly the assumption that would make this detector lie.
+ *
+ *   - **A 32-bit FNV-1a folded in as we walk**, never a concatenated screen
+ *     string. This runs on a poll tick over `cols × rows` cells; building a
+ *     ~100 KB string per tick to throw away would be the expensive part.
+ *
+ *   - **Includes the cursor.** Cursor drift is the defect raw replay was built
+ *     to fix and the one a glyph-only comparison cannot see at all.
+ *
+ * NOT a security primitive: FNV-1a is a hash for detecting accidental
+ * divergence between two copies of a screen, not for resisting anyone.
+ */
+/**
+ * Field separators, spelled as escapes rather than written as raw bytes.
+ *
+ * They must be characters that CANNOT occur in the data being folded, or a
+ * screen could collide with a different screen that happens to contain the
+ * separator as a glyph — a space would do exactly that, since a blank cell
+ * hashes as `' '`. NUL and SOH are never cell contents, so the field boundaries
+ * are unambiguous.
+ *
+ * ⚠️ Part of the cross-package fixture. Changing either value changes every
+ * digest, in both mirrors, and invalidates the pinned test value.
+ */
+const SEP = '\u0000';
+const FIELD = '\u0001';
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+/** Fold a string into a running FNV-1a 32-bit hash. Operates on UTF-16 code
+ *  units, which is fine: both sides hash the same JS strings. */
+function fold(hash, text) {
+    let h = hash;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, FNV_PRIME);
+    }
+    return h >>> 0;
+}
+function flags(cell) {
+    return ((cell.isBold() ? 1 : 0) |
+        (cell.isDim() ? 2 : 0) |
+        (cell.isItalic() ? 4 : 0) |
+        (cell.isUnderline() ? 8 : 0) |
+        (cell.isInverse() ? 16 : 0) |
+        (cell.isStrikethrough() ? 32 : 0));
+}
+function colorKey(isDefault, isPalette, isRgb, color) {
+    // In default mode the colour NUMBER is meaningless (the typings say "should
+    // be 0"; the runtime reports -1), so it is normalised away — otherwise two
+    // identically-rendered default cells would hash differently.
+    if (isDefault)
+        return 'd';
+    if (isRgb)
+        return `r${color}`;
+    if (isPalette)
+        return `p${color}`;
+    return `?${color}`;
+}
+/**
+ * An 8-hex-character digest of the terminal's visible screen and cursor.
+ *
+ * Returns a stable string for a stable screen, and (with overwhelming
+ * likelihood) a different one for any screen that differs in a glyph, an
+ * attribute, a colour, the grid size, the active buffer, or the cursor.
+ */
+export function screenDigest(term) {
+    const buffer = term.buffer.active;
+    let h = FNV_OFFSET_BASIS;
+    h = fold(h, `${term.cols}x${term.rows}|${buffer.type}|${buffer.cursorX},${buffer.cursorY}`);
+    for (let y = 0; y < term.rows; y++) {
+        const line = buffer.getLine(buffer.baseY + y);
+        if (!line) {
+            h = fold(h, `${SEP}~${SEP}`);
+            continue;
+        }
+        h = fold(h, SEP);
+        for (let x = 0; x < term.cols; x++) {
+            const cell = line.getCell(x);
+            if (!cell) {
+                h = fold(h, '~');
+                continue;
+            }
+            // Width 0 is the right half of a wide glyph; its content already came
+            // out of the width-2 cell before it. Hashing it too would double-count
+            // every CJK character and emoji.
+            const width = cell.getWidth();
+            if (width === 0)
+                continue;
+            const chars = cell.getChars();
+            h = fold(h, chars === '' ? ' ' : chars);
+            h = fold(h, `${FIELD}${width}${FIELD}${flags(cell)}${FIELD}`);
+            h = fold(h, colorKey(cell.isFgDefault(), cell.isFgPalette(), cell.isFgRGB(), cell.getFgColor()));
+            h = fold(h, colorKey(cell.isBgDefault(), cell.isBgPalette(), cell.isBgRGB(), cell.getBgColor()));
+        }
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-labs/yolobridge",
-  "version": "0.11.0",
+  "version": "0.12.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",