fix(anthropic): complete transcript reverse-scan windows across short reads

masatohoshino · claude · masatohoshino · commit 223e79bca3bb · 2026-07-17T19:24:22.000+09:00
readLocalClaudeTranscriptPage filled each reverse-scan window with a single
positional read and threw "Claude transcript changed while it was being read"
whenever bytesRead !== size. A positional read may return fewer bytes than
requested inside an unchanged file, so a benign short read failed the transcript
page load with a message implying the file changed. The forward metadata scan in
the same file already loops short reads; the reverse scan did not.

Fill each window across short reads, advancing both the buffer offset and the
file position. A zero-byte read before the window is filled is premature EOF and
still throws the same error.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/extensions/anthropic/session-catalog.test.ts b/extensions/anthropic/session-catalog.test.ts
@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import type { FileHandle } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
@@ -201,6 +202,52 @@ function sdkCliMessage(sessionId: string, text: string): Record<string, unknown>
   };
 }
 
+// Fault-injects short positional reads on the target transcript's FileHandle so
+// tests can drive the reverse-scan pager through partial reads deterministically
+// (production short reads are non-deterministic and cannot be induced reliably).
+// `plan` returns the byte count each read is allowed to satisfy; returning 0
+// simulates a genuine mid-window EOF (truncation). Forward metadata-scan handles
+// (first read at position 0) and the reverse pager handle (first read at a high
+// offset) are distinguishable via `firstPosition`.
+function injectTranscriptShortReads(
+  sessionId: string,
+  plan: (input: {
+    length: number;
+    position: number;
+    call: number;
+    firstPosition: number;
+  }) => number,
+): void {
+  const realOpen = fs.open.bind(fs);
+  vi.spyOn(fs, "open").mockImplementation((async (target: unknown, ...rest: unknown[]) => {
+    const handle = await (realOpen as (...args: unknown[]) => Promise<FileHandle>)(target, ...rest);
+    if (typeof target === "string" && target.endsWith(`${sessionId}.jsonl`)) {
+      const realRead = handle.read.bind(handle) as (
+        buffer: Buffer,
+        offset: number,
+        length: number,
+        position: number,
+      ) => Promise<{ bytesRead: number; buffer: Buffer }>;
+      let call = 0;
+      let firstPosition = -1;
+      (handle as { read: unknown }).read = (
+        buffer: Buffer,
+        offset: number,
+        length: number,
+        position: number,
+      ) => {
+        if (firstPosition < 0) {
+          firstPosition = position;
+        }
+        const allowed = plan({ length, position, call, firstPosition });
+        call += 1;
+        return realRead(buffer, offset, allowed, position);
+      };
+    }
+    return handle;
+  }) as typeof fs.open);
+}
+
 afterEach(async () => {
   vi.restoreAllMocks();
   nodeHostMocks.runNodePtyCommand.mockClear();
@@ -1105,6 +1152,87 @@ describe("Claude session catalog", () => {
     expect(older.nextCursor).toBeUndefined();
   });
 
+  it("pages transcripts identically when every reverse-scan read returns short", async () => {
+    const home = await createHome();
+    const sessionId = "short-read-session";
+    // > TRANSCRIPT_READ_CHUNK_BYTES (128 KiB) so the reverse scan spans multiple
+    // windows, each of which is now split into many consecutive short reads.
+    const oldUser = "old user ".repeat(20_000);
+    await writeProject({
+      home,
+      entries: [
+        {
+          sessionId,
+          fullPath: path.join(home, ".claude", "projects", "-workspace", `${sessionId}.jsonl`),
+          summary: "Transcript",
+          modified: "2026-07-04T00:00:00.000Z",
+          isSidechain: false,
+        },
+      ],
+      transcripts: {
+        [sessionId]: [
+          { type: "queue-operation", sessionId },
+          message(sessionId, "user", oldUser, 1),
+          message(sessionId, "assistant", "old assistant", 2),
+          message(sessionId, "user", "new user", 3),
+          message(sessionId, "assistant", "new assistant", 4),
+        ],
+      },
+    });
+
+    // Every read satisfies at most 4 KiB, so each 128 KiB window is completed
+    // across dozens of non-zero short reads. Fails before the fill-loop fix: the
+    // first short read tripped the "transcript changed" throw.
+    injectTranscriptShortReads(sessionId, ({ length }) => Math.min(length, 4096));
+
+    const latest = await readLocalClaudeTranscriptPage({ threadId: sessionId, limit: 2 }, home);
+    expect(latest.items.map((item) => item.text)).toEqual(["new assistant", "new user"]);
+    expect(latest.nextCursor).toEqual(expect.any(String));
+
+    const older = await readLocalClaudeTranscriptPage(
+      { threadId: sessionId, limit: 2, cursor: latest.nextCursor },
+      home,
+    );
+    expect(older.items.map((item) => item.text)).toEqual(["old assistant", oldUser]);
+    expect(older.nextCursor).toBeUndefined();
+  });
+
+  it("still reports a truncated transcript when a reverse-scan read hits EOF mid-window", async () => {
+    const home = await createHome();
+    const sessionId = "truncated-read-session";
+    const oldUser = "old user ".repeat(20_000);
+    await writeProject({
+      home,
+      entries: [
+        {
+          sessionId,
+          fullPath: path.join(home, ".claude", "projects", "-workspace", `${sessionId}.jsonl`),
+          summary: "Transcript",
+          modified: "2026-07-04T00:00:00.000Z",
+          isSidechain: false,
+        },
+      ],
+      transcripts: {
+        [sessionId]: [
+          message(sessionId, "user", oldUser, 1),
+          message(sessionId, "assistant", "new assistant", 2),
+        ],
+      },
+    });
+
+    // Reverse pager handle (first read at a high offset): return a partial read,
+    // then a 0-byte read = the file was truncated out from under us mid-window,
+    // which must still surface the hard error. Forward metadata-scan handles
+    // (first read at position 0) read normally so the session still resolves.
+    injectTranscriptShortReads(sessionId, ({ length, call, firstPosition }) =>
+      firstPosition === 0 ? length : call === 0 ? Math.min(length, 8) : 0,
+    );
+
+    await expect(
+      readLocalClaudeTranscriptPage({ threadId: sessionId, limit: 2 }, home),
+    ).rejects.toThrow("Claude transcript changed while it was being read");
+  });
+
   it("advertises terminal resume only when the store and Claude binary exist", async () => {
     const home = await createHome();
     const commands = createClaudeSessionNodeHostCommands();
diff --git a/extensions/anthropic/session-catalog.ts b/extensions/anthropic/session-catalog.ts
@@ -745,13 +745,23 @@ export async function readLocalClaudeTranscriptPage(
       );
       position -= size;
       const chunk = Buffer.allocUnsafe(size);
-      const { bytesRead } = await handle.read(chunk, 0, size, position);
-      if (bytesRead !== size) {
-        throw new Error("Claude transcript changed while it was being read");
+      // Positional reads can return fewer bytes than requested even inside a
+      // stat'd, unchanged file, so fill the whole window across short reads
+      // (mirrors the forward metadata scan above). Advance both the buffer
+      // offset and the file position each retry. A zero-byte read before the
+      // window is filled is a genuine premature EOF = the transcript was
+      // truncated mid-read, which stays a hard error.
+      let filled = 0;
+      while (filled < size) {
+        const { bytesRead } = await handle.read(chunk, filled, size - filled, position + filled);
+        if (bytesRead === 0) {
+          throw new Error("Claude transcript changed while it was being read");
+        }
+        filled += bytesRead;
       }
-      scanned += bytesRead;
-      let right = bytesRead;
-      for (let index = bytesRead - 1; index >= 0; index -= 1) {
+      scanned += filled;
+      let right = filled;
+      for (let index = filled - 1; index >= 0; index -= 1) {
         if (chunk[index] !== 0x0a) {
           continue;
         }
