@1agh/maude 1.0.11 → 1.2.0

package/apps/studio/acp/bridge.ts

@@ -8,7 +8,6 @@
 // (env.ts): the child inherits the environment MINUS `ANTHROPIC_API_KEY`, so
 // auth precedence falls through to the user's Pro/Max subscription.
 
-import { readFileSync } from 'node:fs';
 import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 
@@ -32,6 +31,7 @@ import {
 import { scrubAgentEnv } from './env.ts';
 import type { SdkPluginConfig } from './plugin-bootstrap.ts';
 import { resolveAdapterEntry, resolveAgentRuntime, resolveClaudePath } from './probe.ts';
+import { countTranscriptLinesAt, stripInlineBlobs } from './transcript-io.ts';
 import {
   isWriteToolName,
   looksLikeWriteToolCall,
@@ -207,18 +207,16 @@ type Spawned = ReturnType<typeof Bun.spawn>;
 const VALID_SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/;
 
 /** Raw non-empty line count of a transcript file — the re-attach seam's seed.
- *  Deliberately duplicated from `transcript.ts`'s `chatTranscriptSeq` rather
- *  than imported: importing would pull the transcript READER (and its
- *  designRoot/chatId path convention) into the bridge, which knows only an
- *  absolute file path. The two MUST count identically — raw non-empty lines,
- *  never parsed lines, since a corrupt line would otherwise shift every later
- *  seq and permanently desync the seam. */
+ *  Delegates to the ONE shared implementation in `transcript-io.ts`, which
+ *  `transcript.ts`'s `chatTranscriptSeq` also calls. These two counters MUST
+ *  agree — a disagreement shifts every later seq and permanently desyncs the
+ *  seam — and until #119 they were two hand-copied bodies kept in step only by
+ *  a comment. `transcript-io.ts` takes an absolute path and nothing else, so
+ *  sharing it does NOT drag the reader's designRoot/chatId path convention into
+ *  the bridge (the original reason for the duplication). It also counts in
+ *  bounded chunks rather than materializing a multi-hundred-MB file. */
 function countTranscriptLines(path: string): number {
-  try {
-    return readFileSync(path, 'utf8').split('\n').filter(Boolean).length;
-  } catch {
-    return 0; // no transcript yet — first turn of this chat
-  }
+  return countTranscriptLinesAt(path);
 }
 
 // `loadSession`'s replay can, in principle, never settle if the underlying
@@ -1760,7 +1758,14 @@ export class AcpBridge {
     if (claimedSeq === undefined) this.transcriptLines += 1;
     try {
       await mkdir(dirname(path), { recursive: true });
-      await appendFile(path, `${JSON.stringify({ ts: Date.now(), ...entry })}\n`);
+      // #119 — elide inline binary payloads (base64 image/audio `data`, `data:`
+      // URIs) before they reach disk. A tool result carrying a screenshot was
+      // persisted verbatim at up to 1.36 MB PER LINE, and nothing ever read it
+      // back: `readChatMessages` projects a tool call down to its name and
+      // done-flag. In a screenshot-heavy design project that was 66–76% of the
+      // transcript's bytes. Prose, tool arguments and file contents are NOT
+      // touched — those are the audit record of what steered the agent.
+      await appendFile(path, `${JSON.stringify(stripInlineBlobs({ ts: Date.now(), ...entry }))}\n`);
     } catch {
       /* transcript is best-effort; never block the chat on disk errors */
     }

package/apps/studio/acp/transcript-io.ts

@@ -0,0 +1,394 @@
+// Low-level transcript file IO — the primitives that must never load a whole
+// `<designRoot>/_chat/<chatId>.jsonl` into memory, plus the writer-side blob
+// sanitizer that keeps those files small in the first place.
+//
+// WHY THIS MODULE EXISTS (issue #119). Transcripts are append-only and were
+// never capped, rotated, or pruned, and `appendTranscript` persisted every ACP
+// session update VERBATIM — including base64 image payloads from tool results
+// (a `maude design screenshot`, a `Read` of a PNG). A dogfood project reached
+// 554 MB across 24 transcripts, the largest 177 MB in 1733 lines, of which
+// 66–76% was base64 that NOTHING ever reads back (`readChatMessages` projects
+// tool calls down to `{ toolName, done }` and discards `content` entirely).
+//
+// Every reader then did `readFileSync(utf8).split('\n').map(JSON.parse)` over
+// the whole file, and `listChats()` did it for EVERY transcript in the
+// directory — on a code path the client fires at every turn end. Measured
+// under Bun against that project: 661 ms of fully synchronous, event-loop-
+// blocking work and 1.29 GB peak RSS per call, climbing to ~1.9 GB retained.
+// That is one defect presenting as two symptoms: the RSS is the churn, and the
+// "stuck chat" is the same single-threaded loop that serves the ACP socket
+// being blocked by it.
+//
+// The rule this module enforces: a transcript's SIZE must not be able to
+// determine the cost of reading it. Every function here is bounded — by a
+// reusable buffer, a prefix cap, or a tail cap — regardless of file size.
+
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+
+/** Chunk size for the streaming line counter. One reused buffer, never a
+ *  string — the whole point is not to materialize the file. */
+const COUNT_CHUNK_BYTES = 64 * 1024;
+
+const NEWLINE = 0x0a;
+
+/**
+ * Raw non-empty line count of a transcript, read in bounded chunks.
+ *
+ * **This is THE single implementation of the re-attach seam's counter.**
+ * `transcript.ts`'s `chatTranscriptSeq` and `bridge.ts`'s
+ * `countTranscriptLines` both delegate here. They used to be two hand-copied
+ * bodies kept in agreement by a comment ("The two MUST count identically...");
+ * the invariant is now structural, which is the only way it stays true. The
+ * bridge's original objection to sharing — that importing the transcript
+ * READER would drag `designRoot`/`chatId` path conventions into a module that
+ * knows only an absolute path — is respected: this module takes a path and
+ * nothing else.
+ *
+ * Semantics are byte-identical to the string form it replaces,
+ * `readFileSync(f, 'utf8').split('\n').filter(Boolean).length`:
+ *   - segments are split on `\n` ONLY, so a lone `\r` (a CRLF file) is a
+ *     non-empty segment and IS counted, exactly as `filter(Boolean)` counts it;
+ *   - a trailing newline does not add a segment;
+ *   - a final line with no trailing newline DOES count.
+ * Splitting on a single byte is also why chunking is safe for UTF-8: 0x0A can
+ * never occur inside a multi-byte sequence, so a chunk boundary can never
+ * split a character in a way that changes the count.
+ *
+ * A missing/unreadable file is `0` — "no transcript yet", the first turn of a
+ * chat — never a throw. Callers treat the seam's seed as best-effort.
+ */
+export function countTranscriptLinesAt(path: string): number {
+  let fd: number;
+  try {
+    fd = openSync(path, 'r');
+  } catch {
+    return 0;
+  }
+  try {
+    const buf = Buffer.allocUnsafe(COUNT_CHUNK_BYTES);
+    let count = 0;
+    let segmentBytes = 0;
+    for (;;) {
+      const read = readSync(fd, buf, 0, COUNT_CHUNK_BYTES, null);
+      if (read <= 0) break;
+      for (let i = 0; i < read; i++) {
+        if (buf[i] === NEWLINE) {
+          if (segmentBytes > 0) count++;
+          segmentBytes = 0;
+        } else {
+          segmentBytes++;
+        }
+      }
+    }
+    // A final line with no trailing newline is still a line.
+    if (segmentBytes > 0) count++;
+    return count;
+  } catch {
+    return 0;
+  } finally {
+    try {
+      closeSync(fd);
+    } catch {
+      /* already closed / never opened cleanly — nothing to salvage */
+    }
+  }
+}
+
+/** How much of a transcript's HEAD `readChatHead` will look at. The first
+ *  user line is structurally near the top (at most a `role:'bootstrap'` brief
+ *  precedes it), so this is generous by orders of magnitude — it exists to cap
+ *  the pathological case, not to trim the normal one. */
+export const HEAD_SCAN_BYTES = 1024 * 1024;
+
+/** How much of a transcript's TAIL `readTranscriptTail` will hydrate. Bounds
+ *  the one reader that genuinely needs entry CONTENT. Historical transcripts
+ *  bloated by inline blobs (pre-#119) exceed this; the newest ~8 MB is the part
+ *  a user can still meaningfully scroll, and the client's seq-based replay
+ *  (`readChatLinesAfter`) covers anything appended after hydration. */
+export const TAIL_HYDRATE_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Read at most `maxBytes` from the START of a file and return whole lines.
+ *
+ * A truncated trailing line is DROPPED rather than handed back for parsing —
+ * a half-line is not a record, and `JSON.parse` on it would throw on every
+ * call. `complete` reports whether the whole file fit, so a caller can tell
+ * "no user line in this chat" from "no user line in the part I looked at".
+ */
+export function readHeadLines(
+  path: string,
+  maxBytes: number = HEAD_SCAN_BYTES
+): { lines: string[]; complete: boolean } {
+  let fd: number;
+  try {
+    fd = openSync(path, 'r');
+  } catch {
+    return { lines: [], complete: true };
+  }
+  try {
+    // `fstatSync(fd)` — NOT `statSync(path)`. The descriptor is already open,
+    // so sizing from the path re-resolves a name that may no longer be the
+    // file we hold (security review F5). Same reason every read below is
+    // positional on `fd`.
+    const size = fstatSync(fd).size;
+    const want = Math.min(size, maxBytes);
+    const buf = Buffer.allocUnsafe(want);
+    let filled = 0;
+    while (filled < want) {
+      const read = readSync(fd, buf, filled, want - filled, filled);
+      if (read <= 0) break;
+      filled += read;
+    }
+    const complete = filled >= size;
+    let text = buf.subarray(0, filled).toString('utf8');
+    if (!complete) {
+      // Drop the partial tail line — everything after the last newline.
+      const cut = text.lastIndexOf('\n');
+      text = cut === -1 ? '' : text.slice(0, cut);
+    }
+    return { lines: text.split('\n').filter(Boolean), complete };
+  } catch {
+    return { lines: [], complete: true };
+  } finally {
+    try {
+      closeSync(fd);
+    } catch {
+      /* nothing to salvage */
+    }
+  }
+}
+
+/**
+ * Read at most `maxBytes` from the END of a file and return whole lines.
+ *
+ * The leading partial line is dropped by slicing at the first newline INSIDE
+ * the buffer, before decoding — which is also what makes the tail read
+ * UTF-8-safe: cutting at a 0x0A byte can never land mid-character, whereas
+ * decoding the raw window first could corrupt the boundary character.
+ *
+ * `truncated` tells the caller some older history was skipped.
+ */
+export function readTailLines(
+  path: string,
+  maxBytes: number = TAIL_HYDRATE_BYTES
+): { lines: string[]; truncated: boolean } {
+  let fd: number;
+  try {
+    fd = openSync(path, 'r');
+  } catch {
+    return { lines: [], truncated: false };
+  }
+  try {
+    const size = fstatSync(fd).size;
+    if (size <= maxBytes) {
+      const buf = Buffer.allocUnsafe(size);
+      let filled = 0;
+      while (filled < size) {
+        const read = readSync(fd, buf, filled, size - filled, filled);
+        if (read <= 0) break;
+        filled += read;
+      }
+      return {
+        lines: buf.subarray(0, filled).toString('utf8').split('\n').filter(Boolean),
+        truncated: false,
+      };
+    }
+    const start = size - maxBytes;
+    const buf = Buffer.allocUnsafe(maxBytes);
+    let filled = 0;
+    while (filled < maxBytes) {
+      const read = readSync(fd, buf, filled, maxBytes - filled, start + filled);
+      if (read <= 0) break;
+      filled += read;
+    }
+    const window = buf.subarray(0, filled);
+    const nl = window.indexOf(NEWLINE);
+    // No newline in an 8 MB window means one absurd line; hydrate nothing
+    // rather than hand back a fragment that cannot parse.
+    const whole = nl === -1 ? Buffer.alloc(0) : window.subarray(nl + 1);
+    return { lines: whole.toString('utf8').split('\n').filter(Boolean), truncated: true };
+  } catch {
+    return { lines: [], truncated: false };
+  } finally {
+    try {
+      closeSync(fd);
+    } catch {
+      /* nothing to salvage */
+    }
+  }
+}
+
+/**
+ * The tail window AND its absolute line offset, resolved from ONE size
+ * snapshot on ONE descriptor.
+ *
+ * WHY THIS EXISTS RATHER THAN CALLING THE TWO READERS IN SEQUENCE (security
+ * review F4). `readChatLinesAfter` used to do `countTranscriptLinesAt(file)`
+ * and then `readTailLines(file)` as separate passes. The bridge appends to
+ * this exact file continuously during a live turn, so lines landing between
+ * the two passes left `total` stale-low while `tail.length` was fresh-high:
+ * `offset = total - tail.length` under-counted (and could go negative) and
+ * every emitted `seq` shifted with it. That is precisely the permanent
+ * re-attach desync — replaying content the client already has, or skipping
+ * content it never got — that the seam exists to prevent, reintroduced by the
+ * fix for #119 rather than by the bug.
+ *
+ * Both passes here are bounded by the same `size`, so anything appended
+ * mid-read is invisible to BOTH and the arithmetic stays self-consistent. The
+ * client picks those newer lines up on its next attach, which is exactly what
+ * the seq marker is for.
+ */
+export function readTailWithSeq(
+  path: string,
+  maxBytes: number = TAIL_HYDRATE_BYTES
+): { lines: string[]; offset: number; total: number } {
+  let fd: number;
+  try {
+    fd = openSync(path, 'r');
+  } catch {
+    return { lines: [], offset: 0, total: 0 };
+  }
+  try {
+    const size = fstatSync(fd).size;
+    const total = countLinesInRange(fd, size);
+    const lines = readTailInRange(fd, size, maxBytes);
+    // `total` counts every non-empty line in [0, size); `lines` counts those
+    // wholly inside the window. The difference is the prefix we skipped —
+    // including the partial line the window dropped, which IS a whole line in
+    // the file and so is correctly counted by `total`.
+    return { lines, offset: Math.max(0, total - lines.length), total };
+  } catch {
+    return { lines: [], offset: 0, total: 0 };
+  } finally {
+    try {
+      closeSync(fd);
+    } catch {
+      /* nothing to salvage */
+    }
+  }
+}
+
+/** Non-empty line count over `[0, size)` of an already-open descriptor. */
+function countLinesInRange(fd: number, size: number): number {
+  const buf = Buffer.allocUnsafe(COUNT_CHUNK_BYTES);
+  let count = 0;
+  let segmentBytes = 0;
+  let pos = 0;
+  while (pos < size) {
+    const read = readSync(fd, buf, 0, Math.min(COUNT_CHUNK_BYTES, size - pos), pos);
+    if (read <= 0) break;
+    for (let i = 0; i < read; i++) {
+      if (buf[i] === NEWLINE) {
+        if (segmentBytes > 0) count++;
+        segmentBytes = 0;
+      } else {
+        segmentBytes++;
+      }
+    }
+    pos += read;
+  }
+  if (segmentBytes > 0) count++;
+  return count;
+}
+
+/** Whole lines from the last `maxBytes` of `[0, size)` on an open descriptor. */
+function readTailInRange(fd: number, size: number, maxBytes: number): string[] {
+  const want = Math.min(size, maxBytes);
+  const start = size - want;
+  const buf = Buffer.allocUnsafe(want);
+  let filled = 0;
+  while (filled < want) {
+    const read = readSync(fd, buf, filled, want - filled, start + filled);
+    if (read <= 0) break;
+    filled += read;
+  }
+  const window = buf.subarray(0, filled);
+  if (start === 0) return window.toString('utf8').split('\n').filter(Boolean);
+  const nl = window.indexOf(NEWLINE);
+  const whole = nl === -1 ? Buffer.alloc(0) : window.subarray(nl + 1);
+  return whole.toString('utf8').split('\n').filter(Boolean);
+}
+
+// ── Writer-side blob sanitizer ───────────────────────────────────────────────
+
+/**
+ * Inline payloads at or above this size are elided from the persisted line.
+ * Well above any real text chunk (agent message chunks are hundreds of bytes),
+ * well below the megabyte-scale base64 that caused #119.
+ */
+export const INLINE_BLOB_MAX_BYTES = 4096;
+
+/** Keys whose STRING value carries an inline binary payload in the ACP content
+ *  vocabulary. `data` is the base64 field on image/audio content blocks; `uri`
+ *  can carry a `data:` URL of the same magnitude; `blob` is MCP's
+ *  `EmbeddedResource` carrier (security review F2 — the likeliest real-world
+ *  way a megabyte payload would otherwise still reach disk).
+ *
+ *  NOT exhaustive by construction: an array-of-byte-numbers encoding
+ *  (`data: [65, 65, …]`) passes straight through, as does any key we have not
+ *  named. This is a SIZE control, not a security boundary — do not treat it
+ *  as one. */
+const BLOB_KEYS = new Set(['data', 'uri', 'blob']);
+
+/** Marker left in place of an elided payload, so a reader (or a human reading
+ *  the jsonl as the audit record it is) sees that something was dropped and how
+ *  big it was, rather than a silently absent field. */
+export interface ElidedBlob {
+  _maudeElided: 'inline-blob';
+  bytes: number;
+}
+
+function isElidableBlob(key: string, value: unknown): value is string {
+  return BLOB_KEYS.has(key) && typeof value === 'string' && value.length >= INLINE_BLOB_MAX_BYTES;
+}
+
+/**
+ * Structural clone of a transcript entry with inline binary payloads replaced
+ * by a size marker.
+ *
+ * This is a WRITE-path guard, and it is safe precisely because the read path
+ * never wanted these bytes: `readChatMessages` keeps only a tool call's name
+ * and done-flag. Eliding them changes nothing a user can see, and removes
+ * 66–76% of the bytes of a screenshot-heavy transcript.
+ *
+ * Deliberately conservative — it rewrites only `data`/`uri` strings at or over
+ * `INLINE_BLOB_MAX_BYTES`. Prose, tool arguments, diffs and file contents are
+ * untouched: they are the audit record of what steered an auto-approving
+ * agent, and that record is load-bearing (see the note on `stripContextBlock`
+ * in `transcript.ts`).
+ *
+ * A `data:` URI is elided whole rather than kept as a truncated prefix — half a
+ * base64 payload is not more useful than none, and a truncated `data:` URI that
+ * still LOOKS like a URI is worse than an honest marker.
+ */
+export function stripInlineBlobs<T>(value: T): T {
+  return clone(value) as T;
+}
+
+function clone(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(clone);
+  if (value === null || typeof value !== 'object') return value;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    const next = isElidableBlob(k, v)
+      ? ({ _maudeElided: 'inline-blob', bytes: v.length } satisfies ElidedBlob)
+      : clone(v);
+    if (k === '__proto__') {
+      // `JSON.parse` makes `__proto__` an OWN property, but plain assignment
+      // hits the `Object.prototype.__proto__` setter and swaps the clone's
+      // prototype instead of storing a key — so the field vanishes from the
+      // serialized line (security review F6). It cannot pollute
+      // `Object.prototype` here, but silently dropping a key WOULD dent the
+      // audit record this sanitizer otherwise takes care to preserve.
+      Object.defineProperty(out, k, {
+        value: next,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      });
+      continue;
+    }
+    out[k] = next;
+  }
+  return out;
+}

package/apps/studio/acp/transcript.ts

@@ -13,6 +13,14 @@ import {
 } from 'node:fs';
 import { join } from 'node:path';
 
+import {
+  countTranscriptLinesAt,
+  readHeadLines,
+  readTailLines,
+  readTailWithSeq,
+  TAIL_HYDRATE_BYTES,
+} from './transcript-io.ts';
+
 export interface ChatSummary {
   id: string;
   title: string;
@@ -98,22 +106,19 @@ export function writeChatMeta(
   return next;
 }
 
-function readLines(file: string): Array<Record<string, unknown>> {
-  try {
-    return readFileSync(file, 'utf8')
-      .split('\n')
-      .filter(Boolean)
-      .map((l) => {
-        try {
-          return JSON.parse(l) as Record<string, unknown>;
-        } catch {
-          return null;
-        }
-      })
-      .filter((x): x is Record<string, unknown> => x !== null);
-  } catch {
-    return [];
+/** Parse raw jsonl lines, dropping unparseable ones. Callers hand this a
+ *  BOUNDED slice of a transcript (a head or tail window) — never a whole file.
+ *  Reading a transcript whole is the #119 defect; see `transcript-io.ts`. */
+function parseLines(raw: string[]): Array<Record<string, unknown>> {
+  const out: Array<Record<string, unknown>> = [];
+  for (const l of raw) {
+    try {
+      out.push(JSON.parse(l) as Record<string, unknown>);
+    } catch {
+      /* malformed line — skipped */
+    }
   }
+  return out;
 }
 
 // ── The re-attach seam (feature-acp-write-path-scope Addendum, Task 8) ───────
@@ -130,22 +135,25 @@ function readLines(file: string): Array<Record<string, unknown>> {
 // the client should have seen" are the same number by construction.
 //
 // CRITICAL: these two helpers count/index RAW non-empty lines, deliberately NOT
-// `readLines()`, which silently drops unparseable lines. A single corrupt line
-// would otherwise shift every subsequent seq by one and permanently desync the
-// seam — replaying content the client already has, forever. A malformed line is
+// PARSED lines — parsing silently drops unparseable lines, and a single corrupt
+// line would then shift every subsequent seq by one and permanently desync the
+// seam, replaying content the client already has, forever. A malformed line is
 // skipped from the RESULT here but still consumes its index.
+//
+// The counting itself now lives in ONE place — `transcript-io.ts`'s
+// `countTranscriptLinesAt`, which `bridge.ts` calls too. It used to be two
+// hand-copied bodies held in agreement by a comment saying they must agree
+// (#119); a shared function makes the invariant structural instead of
+// aspirational.
 
 /** The chat's current sequence marker: how many transcript lines exist. `0` for
  *  a chat with no transcript yet. Handed to the client as the `X-Maude-Chat-Seq`
  *  header on the history fetch, and echoed back on `attach`. */
 export function chatTranscriptSeq(designRoot: string, chatId: string): number {
-  const file = join(chatDir(designRoot), `${chatId}.jsonl`);
-  if (!existsSync(file)) return 0;
-  try {
-    return readFileSync(file, 'utf8').split('\n').filter(Boolean).length;
-  } catch {
-    return 0;
-  }
+  // Counted in bounded chunks, never by materializing the file as a string —
+  // and by the SAME function the bridge's counter calls, so the two cannot
+  // drift apart and desync the seam (#119).
+  return countTranscriptLinesAt(join(chatDir(designRoot), `${chatId}.jsonl`));
 }
 
 /** Transcript lines strictly after `afterSeq`, each paired with its own 1-based
@@ -161,18 +169,35 @@ export function readChatLinesAfter(
 ): Array<{ seq: number; entry: Record<string, unknown> }> {
   const file = join(chatDir(designRoot), `${chatId}.jsonl`);
   if (!existsSync(file)) return [];
-  let raw: string[];
-  try {
-    raw = readFileSync(file, 'utf8').split('\n').filter(Boolean);
-  } catch {
-    return [];
-  }
+  // The replay window is the TAIL by construction (`limit` most-recent lines),
+  // so a tail read suffices — but `seq` is a 1-based index into the WHOLE
+  // file, so the skipped prefix still has to be counted (cheaply) to keep the
+  // numbering absolute. Counting and reading are separate passes precisely
+  // because only one of them needs the bytes.
+  //
+  // Two bounds now apply, and they do not conflict in practice: `limit`
+  // (default 500) caps the RESULT to the newest lines, and the tail window
+  // caps the BYTES scanned. A client whose `afterSeq` predates the window
+  // would, in principle, miss the lines between — but those are more than
+  // `TAIL_HYDRATE_BYTES` back in the file, so `limit` has already truncated
+  // them away first. The replay is for the gap since the last hydration, not
+  // for the archive (see this function's contract above).
+  // ONE descriptor, ONE size snapshot — `readTailWithSeq` resolves the window
+  // and its absolute offset together. Doing this as two passes (count, then
+  // read) let the bridge's concurrent appends drift `offset` and shift every
+  // emitted seq: security review F4, and the very desync this seam exists to
+  // prevent.
+  const { lines: raw, offset, total } = readTailWithSeq(file);
+  if (total === 0) return [];
   const out: Array<{ seq: number; entry: Record<string, unknown> }> = [];
   // Walk from the END so `limit` keeps the MOST RECENT lines — truncating the
   // tail would drop precisely the streaming updates the re-attach is for.
-  for (let i = raw.length - 1; i >= afterSeq && out.length < limit; i--) {
+  // `i` indexes the tail window; `offset + i` is the absolute line index, which
+  // is what `afterSeq` is expressed in and what `seq` must report.
+  const lowest = Math.max(0, afterSeq - offset);
+  for (let i = raw.length - 1; i >= lowest && out.length < limit; i--) {
     try {
-      out.push({ seq: i + 1, entry: JSON.parse(raw[i]) as Record<string, unknown> });
+      out.push({ seq: offset + i + 1, entry: JSON.parse(raw[i]) as Record<string, unknown> });
     } catch {
       /* malformed line — skipped from the result, but its index is still spent */
     }
@@ -204,14 +229,35 @@ export function listChats(designRoot: string): ChatSummary[] {
     if (meta.archived) continue;
     const file = join(dir, name);
     let updated = 0;
+    let size = 0;
     try {
-      updated = statSync(file).mtimeMs;
+      const st = statSync(file);
+      updated = st.mtimeMs;
+      size = st.size;
     } catch {
       /* skip unreadable */
     }
-    const lines = readLines(file);
-    if (lines.length === 0) continue;
-    out.push({ id, title: meta.title || deriveTitle(lines), updated, renamed: !!meta.title });
+    if (size === 0) continue;
+    // #119: this used to `readLines(file)` — the WHOLE transcript — for every
+    // chat in the directory, to pull ~60 characters out of the first user
+    // line, on a path the client fires at every turn end. The first user line
+    // sits at the top of the file by construction (only a `role:'bootstrap'`
+    // brief can precede it), so a bounded HEAD read answers the same question
+    // for a fixed cost no matter how large the transcript has grown.
+    //
+    // A user-renamed chat needs no scan at all — the title is already in the
+    // sidecar, so skip the read entirely.
+    if (meta.title) {
+      out.push({ id, title: meta.title, updated, renamed: true });
+      continue;
+    }
+    const head = readHeadLines(file);
+    const lines = parseLines(head.lines);
+    // A file with bytes but no parseable line is still a real chat; only a
+    // genuinely empty one is skipped (matching the old `lines.length === 0`
+    // guard, which could only be reached for an empty/blank file).
+    if (lines.length === 0 && head.complete) continue;
+    out.push({ id, title: deriveTitle(lines), updated, renamed: false });
   }
   return out.sort((a, b) => b.updated - a.updated);
 }
@@ -274,8 +320,27 @@ function stripContextBlock(text: string): string {
 export function readChatMessages(designRoot: string, chatId: string): ChatMessage[] {
   const file = join(chatDir(designRoot), `${chatId}.jsonl`);
   if (!existsSync(file)) return [];
-  const lines = readLines(file);
+  // #119: bounded TAIL read. Below `TAIL_HYDRATE_BYTES` — every transcript
+  // written since inline blobs stopped being persisted — this reads the whole
+  // file and behaves exactly as before. Above it (a historical transcript
+  // bloated by base64 tool results), the newest bytes are hydrated and the
+  // older ones are left on disk rather than pulled through the server and into
+  // the browser. The client's seq-based replay still covers everything
+  // appended AFTER hydration, so the live seam is unaffected either way.
+  const { lines: raw, truncated } = readTailLines(file, TAIL_HYDRATE_BYTES);
+  const lines = parseLines(raw);
   const messages: ChatMessage[] = [];
+  if (truncated) {
+    messages.push({
+      role: 'assistant',
+      parts: [
+        {
+          type: 'text',
+          text: '_Older messages in this chat are not shown — the transcript exceeds the hydration limit. The full record remains on disk._',
+        },
+      ],
+    });
+  }
   let assistant: ChatMessage | null = null;
   const toolIndex = new Map<string, number>();