fix(coding-agents): bound transcript reads so an oversized session still retains (#3345)

Closes #3292.

Every live-transcript reader did `readFileSync(path, "utf8").split("\n")`. Past
V8's maximum string length (~537M chars) that throws ERR_STRING_TOO_LONG before a
single record is parsed; the readers catch it as "unreadable file" and return no
turns, so the Stop hook exits successfully having retained nothing. An agent that
had been running for weeks just stops updating memory, with no error anywhere.

Reproduced on a 575MB Codex rollout: readFileSync throws ERR_STRING_TOO_LONG,
readCodexTranscript returns []. With this change the same file yields 8,162 turns
ending in the most recent exchange, in 51MB of heap.

core/jsonl.ts streams the file a chunk at a time through a StringDecoder (so a
multi-byte character split across chunks is reassembled) and reads only the last
MAX_TRANSCRIPT_BYTES. Truncating the HEAD is what makes a cap safe here: the
recent exchange is the part worth retaining, and the incremental write-back only
sends turns after its cursor anyway. Landing mid-record drops that fragment
rather than emitting half a line; starting one byte early keeps a record whose
boundary the cut happened to land on. A truncated read is logged, never silent —
which was the actual complaint.

Applied to all six readers that shared the pattern (claude-code, codex,
antigravity-cli, copilot-cli, cursor-cli, grok-build), not just the one filed:
same bug, same line, and a large Claude Code transcript fails identically.

Author: nicoloboschi

hindsight-integrations/coding-agents/src/core/jsonl.test.ts

@@ -0,0 +1,110 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MAX_TRANSCRIPT_BYTES, readJsonlTail } from "./jsonl";
+
+// Spy on the REAL readFileSync (not a stub that throws): the point is to prove nothing in this path
+// calls it, which is what #3292 came down to — past V8's maximum string length it throws
+// ERR_STRING_TOO_LONG, and the readers turned that into "no turns" with no error anywhere.
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return { ...actual, readFileSync: vi.fn(actual.readFileSync) };
+});
+
+let root: string;
+let file: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "hs-jsonl-"));
+  file = join(root, "transcript.jsonl");
+  vi.mocked(readFileSync).mockClear();
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+const read = (maxBytes?: number) => {
+  const tail = readJsonlTail(file, { scope: "test", maxBytes });
+  return { lines: [...tail.lines], skippedBytes: tail.skippedBytes };
+};
+
+describe("readJsonlTail", () => {
+  it("yields every record of a file under the cap", () => {
+    writeFileSync(file, ["a", "b", "c"].join("\n") + "\n");
+    expect(read()).toEqual({ lines: ["a", "b", "c"], skippedBytes: 0 });
+  });
+
+  it("yields a final record that has no trailing newline", () => {
+    writeFileSync(file, "a\nb");
+    expect(read().lines).toEqual(["a", "b"]);
+  });
+
+  it("preserves blank and whitespace-only records for the caller to skip", () => {
+    // The readers decide what to drop (they trim and skip empties); this must not silently change
+    // the record stream they used to get from split("\n").
+    writeFileSync(file, "a\n\n b \nc\n");
+    expect(read().lines).toEqual(["a", "", " b ", "c"]);
+  });
+
+  it("keeps \\r on CRLF records, exactly as split('\\n') did", () => {
+    writeFileSync(file, "a\r\nb\r\n");
+    expect(read().lines).toEqual(["a\r", "b\r"]);
+  });
+
+  it("reads the TAIL when the file exceeds the cap, dropping the record it lands inside", () => {
+    // The cap lands mid-record; that fragment must be discarded whole rather than emitted as a
+    // half line that fails to parse.
+    const records = ["1111111111", "2222222222", "3333333333", "4444444444"];
+    writeFileSync(file, records.join("\n") + "\n"); // 44 bytes
+    const { lines, skippedBytes } = read(25);
+    expect(skippedBytes).toBe(19);
+    expect(lines).toEqual(["3333333333", "4444444444"]);
+  });
+
+  it("keeps whole records when the cap lands exactly on a boundary", () => {
+    writeFileSync(file, ["aaaa", "bbbb", "cccc"].join("\n") + "\n"); // 15 bytes
+    // Last 10 bytes start exactly at "bbbb"; the leading newline is the dropped 'partial'.
+    expect(read(10).lines).toEqual(["bbbb", "cccc"]);
+  });
+
+  it("reassembles a multi-byte character split across the read boundary", () => {
+    // 'é' is 2 bytes; place it so its first byte ends one 64KB chunk and its second starts the next.
+    const pad = "a".repeat(65535);
+    writeFileSync(file, `${pad}é-tail\nsecond\n`);
+    const lines = read().lines;
+    expect(lines[0].endsWith("é-tail")).toBe(true);
+    expect(lines[0]).not.toContain("�"); // no replacement char: the sequence survived
+    expect(lines[1]).toBe("second");
+  });
+
+  it("yields nothing for a missing file instead of throwing", () => {
+    expect(read()).toEqual({ lines: [], skippedBytes: 0 });
+  });
+
+  it("yields nothing for an empty file", () => {
+    writeFileSync(file, "");
+    expect(read().lines).toEqual([]);
+  });
+
+  it("closes the file even when the consumer stops early", () => {
+    writeFileSync(file, ["a", "b", "c"].join("\n") + "\n");
+    const { lines } = readJsonlTail(file, { scope: "test" });
+    for (const line of lines) {
+      expect(line).toBe("a");
+      break; // for..of calls the generator's return(), which must run the finally that closes the fd
+    }
+    expect(lines.next().done).toBe(true);
+  });
+
+  it("never reads the whole file into one string", () => {
+    writeFileSync(file, "a\nb\n");
+    expect(read().lines).toEqual(["a", "b"]);
+    expect(vi.mocked(readFileSync)).not.toHaveBeenCalled();
+  });
+
+  it("caps at 32MB by default", () => {
+    expect(MAX_TRANSCRIPT_BYTES).toBe(32 * 1024 * 1024);
+  });
+});

hindsight-integrations/coding-agents/src/core/jsonl.ts

@@ -0,0 +1,118 @@
+/**
+ * Bounded JSONL reading for the harness transcript readers.
+ *
+ * Every live-transcript reader used to do `readFileSync(path, "utf8").split("\n")`. Two things go
+ * wrong with that as a session grows, and the second is silent:
+ *
+ *   - past V8's maximum string length (~537M chars) `readFileSync` throws ERR_STRING_TOO_LONG
+ *     before a single record is parsed. The readers catch that as "unreadable file" and return no
+ *     turns, so the Stop hook exits successfully having retained nothing — an agent that had been
+ *     running for weeks just stopped updating memory, with no error anywhere (#3292).
+ *   - well before that limit, decoding hundreds of MB into one string (and then a turn per line)
+ *     costs several times the file size in heap, in a hook process that must not fall over.
+ *
+ * So: stream the file a chunk at a time, and read only the LAST `maxBytes` of it. Truncating the
+ * head rather than the tail is what makes the cap safe to apply everywhere — the recent exchange is
+ * the part worth retaining, and the incremental write-back (core/retain-cursor.ts) only sends turns
+ * added since its cursor anyway. A transcript over the cap is reported, never dropped in silence.
+ */
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { log } from "./log";
+
+/** Read granularity. Large enough that a multi-MB transcript is a few hundred syscalls. */
+const CHUNK_BYTES = 64 * 1024;
+
+/**
+ * Most transcript we will decode, per read.
+ *
+ * A parsed transcript costs roughly 3x its bytes in heap (one string per line plus the turn
+ * objects), so this keeps a hook process near ~100MB even in the worst case. It is far above any
+ * real coding session: the largest transcripts seen in the wild are single-digit MB, and a file
+ * over this has already stopped being a conversation anyone can extract meaning from.
+ */
+export const MAX_TRANSCRIPT_BYTES = 32 * 1024 * 1024;
+
+export interface JsonlTail {
+  /** Complete records, oldest first. Never holds more than one line plus a chunk in memory. */
+  lines: Generator<string>;
+  /** Bytes skipped from the head because the file exceeded the cap; 0 when it was read whole. */
+  skippedBytes: number;
+}
+
+/**
+ * The last `maxBytes` of a JSONL file, one complete record at a time.
+ *
+ * Fail-open like the readers it serves: a missing or unreadable file yields no records rather than
+ * throwing. `scope` only names the harness in the truncation warning.
+ */
+export function readJsonlTail(path: string, opts: { scope: string; maxBytes?: number }): JsonlTail {
+  const maxBytes = opts.maxBytes ?? MAX_TRANSCRIPT_BYTES;
+  let size: number;
+  try {
+    size = statSync(path).size;
+  } catch {
+    return { lines: emptyLines(), skippedBytes: 0 };
+  }
+  const skippedBytes = size > maxBytes ? size - maxBytes : 0;
+  if (skippedBytes > 0) {
+    // The whole point of #3292: an oversized transcript must not fail quietly.
+    log.warn(opts.scope, "transcript too large — retaining the most recent portion only", {
+      path,
+      sizeBytes: size,
+      skippedBytes,
+    });
+  }
+  return { lines: streamLines(path, skippedBytes), skippedBytes };
+}
+
+function* emptyLines(): Generator<string> {
+  /* nothing to yield — see the fail-open contract above */
+}
+
+/** Yield complete lines from `start` to EOF. The fd is opened lazily (on first iteration) and
+ *  closed even if the consumer abandons the generator early — for..of calls return() for us. */
+function* streamLines(path: string, start: number): Generator<string> {
+  let fd: number;
+  try {
+    fd = openSync(path, "r");
+  } catch {
+    return;
+  }
+  try {
+    const buffer = Buffer.allocUnsafe(CHUNK_BYTES);
+    // StringDecoder holds back a trailing partial UTF-8 sequence, so a multi-byte character split
+    // across two chunks is reassembled instead of becoming two replacement chars.
+    const decoder = new StringDecoder("utf8");
+    let pending = "";
+    // Begin one byte EARLY so the cut can be classified: if that byte is the newline ending the
+    // previous record, the cut was clean and the "partial" we drop is an empty string, costing
+    // nothing. Otherwise we really did land inside a record and drop that fragment.
+    let position = start > 0 ? start - 1 : 0;
+    let dropPartial = start > 0;
+
+    for (;;) {
+      const bytesRead = readSync(fd, buffer, 0, buffer.length, position);
+      if (bytesRead <= 0) break;
+      position += bytesRead;
+      pending += decoder.write(buffer.subarray(0, bytesRead));
+
+      let newline: number;
+      while ((newline = pending.indexOf("\n")) !== -1) {
+        const line = pending.slice(0, newline);
+        pending = pending.slice(newline + 1);
+        if (dropPartial) {
+          dropPartial = false;
+          continue;
+        }
+        yield line;
+      }
+    }
+
+    pending += decoder.end();
+    // A final record with no trailing newline still counts (and is not the dropped partial).
+    if (pending && !dropPartial) yield pending;
+  } finally {
+    closeSync(fd);
+  }
+}

hindsight-integrations/coding-agents/src/core/transcript-antigravity.ts

@@ -1,20 +1,13 @@
-import { readFileSync } from "node:fs";
 import type { TransportTurn } from "./chat";
+import { readJsonlTail } from "./jsonl";
 import { stripInjectedMemory } from "./transcript-util";
 
 /** Read Antigravity's transcript JSONL defensively. The documented hook contract guarantees only
  * the path, not the internal event schema, so support its user/assistant role and message variants. */
 export function readAntigravityTranscript(path: string | undefined): TransportTurn[] {
   if (!path) return [];
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return [];
-  }
-
   const turns: TransportTurn[] = [];
-  for (const line of raw.split("\n")) {
+  for (const line of readJsonlTail(path, { scope: "antigravity-cli" }).lines) {
     try {
       const event = JSON.parse(line) as {
         role?: string;

hindsight-integrations/coding-agents/src/core/transcript-codex.ts

@@ -20,8 +20,8 @@
  * prevents a retain→recall feedback loop (plus stripInjectedMemory as a defensive second pass on the
  * text we do keep). Fail-open: never throws on a missing file or a malformed line.
  */
-import { readFileSync } from "node:fs";
 import type { TransportTurn } from "./chat";
+import { readJsonlTail } from "./jsonl";
 import { actionLine, stripInjectedMemory } from "./transcript-util";
 
 interface ContentItem {
@@ -60,15 +60,8 @@ function messageText(payload: Payload): string {
  *  Drops developer/system + synthetic-startup + reasoning + injected memory + empty turns.
  *  Never throws on bad lines. */
 export function readCodexTranscript(path: string): TransportTurn[] {
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return [];
-  }
-
   const turns: TransportTurn[] = [];
-  for (const rawLine of raw.split("\n")) {
+  for (const rawLine of readJsonlTail(path, { scope: "codex" }).lines) {
     const trimmed = rawLine.trim();
     if (!trimmed) continue;
 

hindsight-integrations/coding-agents/src/core/transcript-copilot.ts

@@ -1,18 +1,11 @@
-import { readFileSync } from "node:fs";
 import type { TransportTurn } from "./chat";
+import { readJsonlTail } from "./jsonl";
 import { stripInjectedMemory } from "./transcript-util";
 
 /** Normalize Copilot CLI's session-state `events.jsonl` user/assistant message records. */
 export function readCopilotTranscript(path: string): TransportTurn[] {
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return [];
-  }
-
   const turns: TransportTurn[] = [];
-  for (const rawLine of raw.split("\n")) {
+  for (const rawLine of readJsonlTail(path, { scope: "copilot-cli" }).lines) {
     try {
       const event = JSON.parse(rawLine) as {
         type?: string;

hindsight-integrations/coding-agents/src/core/transcript-cursor.ts

@@ -1,6 +1,6 @@
 /** Cursor CLI transcript reader for its `stop` write-back hook. */
-import { readFileSync } from "node:fs";
 import type { TransportTurn } from "./chat";
+import { readJsonlTail } from "./jsonl";
 import { actionLine, stripInjectedMemory } from "./transcript-util";
 
 interface ContentBlock {
@@ -35,15 +35,8 @@ function textFrom(content: string | ContentBlock[] | undefined): string {
 
 /** Parse Cursor's JSONL message and tool-call events into durable text and compact action turns. */
 export function readCursorTranscript(path: string): TransportTurn[] {
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return [];
-  }
-
   const turns: TransportTurn[] = [];
-  for (const rawLine of raw.split("\n")) {
+  for (const rawLine of readJsonlTail(path, { scope: "cursor-cli" }).lines) {
     let parsed: unknown;
     try {
       parsed = JSON.parse(rawLine);

hindsight-integrations/coding-agents/src/core/transcript-grok.ts

@@ -5,6 +5,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { TransportTurn } from "./chat";
+import { readJsonlTail } from "./jsonl";
 import { actionLine, stripInjectedMemory } from "./transcript-util";
 
 const CHAT_HISTORY = "chat_history.jsonl";
@@ -36,15 +37,8 @@ export function grokTranscriptPath(
 /** Normalize Grok's persisted chat-history records into user, assistant, and compact action turns.
  * Synthetic user records carry `synthetic_reason`; only prompt-indexed records are actual user work. */
 export function readGrokTranscript(path: string): TransportTurn[] {
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return [];
-  }
-
   const turns: TransportTurn[] = [];
-  for (const rawLine of raw.split("\n")) {
+  for (const rawLine of readJsonlTail(path, { scope: "grok-build" }).lines) {
     try {
       const event = JSON.parse(rawLine) as {
         type?: string;

hindsight-integrations/coding-agents/src/core/transcript.ts

@@ -13,8 +13,8 @@
  * Fail-open: never throws on a missing file, malformed line, or a line that parses to a
  * non-object JSON value (`null`, a number, a boxed primitive, …).
  */
-import { readFileSync } from "node:fs";
 import type { TransportTurn } from "./chat";
+import { readJsonlTail } from "./jsonl";
 import { actionLine, stripInjectedMemory } from "./transcript-util";
 
 interface ContentBlock {
@@ -76,15 +76,8 @@ function renderLine(content: string | ContentBlock[] | undefined, type: string):
  *  Drops thinking blocks, isMeta/isSidechain lines, injected memory, and empty turns.
  *  Never throws on bad lines. */
 export function readClaudeTranscript(path: string): TransportTurn[] {
-  let raw: string;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return [];
-  }
-
   const turns: TransportTurn[] = [];
-  for (const rawLine of raw.split("\n")) {
+  for (const rawLine of readJsonlTail(path, { scope: "claude-code" }).lines) {
     const trimmed = rawLine.trim();
     if (!trimmed) continue;