fix(read-file): keep Use offset= through the reactor 10k cap

Footer-bearing read_file pages already skip the leisure 10k cut so
the 50KB page and its continuation footer reach the reactor. The
always-on size-cap then sliced the first 10k of the body and dropped
Use offset=. Skip that cap for the same pages leisure skips.

Dead offsets on files larger than the 8MB scan ceiling now report
beyond-EOF with the path and valid range. Skip bytes still do not
count against the scan ceiling.

Author: TheGreatAxios

src/plugins/read-file-guard-plugin.test.ts

@@ -3,8 +3,13 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { createSizeCapTransform } from "@intx/inference";
 import { createBlobReader } from "@intx/types/runtime";
-import type { ToolCall, ToolResult } from "@intx/types/runtime";
+import type {
+  StrategyContext,
+  ToolCall,
+  ToolResult,
+} from "@intx/types/runtime";
 import {
   READ_FILE_DEFAULT_MAX_LINES,
   READ_FILE_MAX_BYTES,
@@ -100,6 +105,8 @@ describe("readFileBounded", () => {
     expect(isError).toBe(true);
     expect(content).toContain("beyond end of file");
     expect(content).toContain("(2 lines)");
+    expect(content).toContain(p);
+    expect(content).toContain("valid offsets 0-1");
   });
 
   test("truncates an overlong single line", async () => {
@@ -286,9 +293,10 @@ describe("readFileBounded", () => {
     );
   });
 
-  test("offset past the scan ceiling reports the scan limit, not a fake EOF", async () => {
-    // Many short lines totaling more than the scan ceiling; a huge offset can
-    // never be reached within one scan pass.
+  test("a dead offset on a file larger than the scan ceiling reports beyond-EOF with path and valid range", async () => {
+    // Skip bytes are not scanned, so an offset past true EOF on a >8MB file
+    // still reaches the end of the file. Report the real line count and valid
+    // range, not a scan-limit that would hide a reachable EOF.
     const line = `${"y".repeat(80)}\n`;
     const count = Math.ceil(
       (READ_FILE_MAX_SCAN_BYTES + 1_000_000) / line.length,
@@ -301,8 +309,11 @@ describe("readFileBounded", () => {
       neverAbort(),
     );
     expect(isError).toBe(true);
-    expect(content).toContain("scan limit");
-    expect(content).not.toContain("beyond end of file");
+    expect(content).toContain("beyond end of file");
+    expect(content).toContain(`(${count} lines)`);
+    expect(content).toContain(p);
+    expect(content).toContain(`valid offsets 0-${count - 1}`);
+    expect(content).not.toContain("scan limit");
   });
 });
 
@@ -529,6 +540,60 @@ describe("CL-8979 large-file pagination", () => {
     expect(spilled.size).toBe(0);
   });
 
+  test("a large-file page keeps Use offset= through leisure and the reactor 10k size-cap", async () => {
+    const name = "cl8979-reactor-page.txt";
+    const rows = Array.from(
+      { length: 3_000 },
+      (_, i) => `cell-${i}-` + "v".repeat(50),
+    );
+    await fixture(name, `${rows.join("\n")}\n`);
+    const plugin = readFileGuardPlugin(dir, {});
+    const guardMiddleware = plugin.middleware;
+    if (guardMiddleware === undefined) throw new Error("expected middleware");
+    const fallback = async (call: ToolCall): Promise<ToolResult> => ({
+      callId: call.id,
+      content: "FALLBACK",
+    });
+    const guard = guardMiddleware(fallback);
+    const spilled = new Map<string, Uint8Array>();
+    const truncPlugin = resultTruncationPlugin({
+      getBlobWriter: () => async (key: string, payload: Uint8Array) => {
+        spilled.set(key, payload);
+      },
+    });
+    const truncMiddleware = truncPlugin.middleware;
+    if (truncMiddleware === undefined) throw new Error("expected middleware");
+    const leisure = truncMiddleware(guard);
+    const leisurePage = await leisure(
+      { id: "page-cap", name: "read_file", arguments: { path: name } },
+      neverAbort(),
+    );
+    const leisureContent = String(leisurePage.content);
+    expect(leisurePage.isError).toBeFalsy();
+    expect(leisureContent).toContain("Use offset=");
+    expect(leisureContent.length).toBeGreaterThan(10_000);
+
+    const reactorCap = createSizeCapTransform({
+      maxChars: 10_000,
+      contextStore: {
+        writeBlob: async (key: string, payload: Uint8Array) => {
+          spilled.set(key, payload);
+        },
+      },
+    });
+    const capped = await reactorCap.apply(
+      {
+        call: { id: "page-cap", name: "read_file", arguments: { path: name } },
+        result: leisurePage,
+      },
+      {} as StrategyContext,
+    );
+    const modelFacing = String(capped.output.content);
+    expect(modelFacing).toContain("Use offset=");
+    expect(modelFacing).toBe(leisureContent);
+    expect(modelFacing).not.toContain("Tool output truncated");
+  });
+
   test("an aborted read rejects with a timeout, not a fallback page", async () => {
     const p = await fixture("cl8979-abort.txt", "x".repeat(1000));
     const ctl = new AbortController();

src/plugins/read-file-guard-plugin.ts

@@ -118,7 +118,6 @@ function readStreamBounded(
     let firstChunk = true;
     let lineNo = 0;
     let scanned = 0;
-    let diskBytes = 0;
     let skipDone = offset <= 0;
     let outBytes = 0;
     let emitted = 0;
@@ -241,20 +240,19 @@ function readStreamBounded(
           done({ content: "" });
           return;
         }
-        // An offset never reached after more than one scan pass of the source
-        // is unlocatable in a single pass: report the scan limit, not a
-        // beyond-EOF count. Offsets reached within the pass read through even
-        // when the skipped prefix alone exceeds the ceiling.
-        if (!endReached || diskBytes > READ_FILE_MAX_SCAN_BYTES) {
+        // Skip bytes are not scanned, so a dead offset on a file larger than
+        // the ceiling still reaches EOF. Report the true range, not a scan
+        // limit that would hide a reachable end of file.
+        if (endReached) {
           done({
-            content: `[reached the ${
-              READ_FILE_MAX_SCAN_BYTES / (1024 * 1024)
-            }MB scan limit before offset ${offset}; the file is larger than read_file scans in one pass. Use a smaller offset or grep to locate content.]`,
+            content: `[offset ${offset} is beyond end of file ${displayPath} (${lineNo} lines); valid offsets 0-${lineNo - 1}]`,
             isError: true,
           });
         } else {
           done({
-            content: `[offset ${offset} is beyond end of file (${lineNo} lines)]`,
+            content: `[reached the ${
+              READ_FILE_MAX_SCAN_BYTES / (1024 * 1024)
+            }MB scan limit before offset ${offset}; the file is larger than read_file scans in one pass. Use a smaller offset or grep to locate content.]`,
             isError: true,
           });
         }
@@ -281,7 +279,6 @@ function readStreamBounded(
         }
       }
       if (skipDone) scanned += chunk.length;
-      diskBytes += chunk.length;
       pending += decoder.write(chunk);
       if (!drainPending()) {
         finishOk();

vendor/intx-inference/PATCHES.md

@@ -575,6 +575,7 @@ revisit point is the next vendored sync (see `docs/VENDORING.md`).
 | state-ts-deep-freeze-turns-revision | Make `ReactorState.snapshot().turns` a lazy, revision-tracked getter | Alexander Guy <alexander.guy@pm.me> | This ledger (#state-ts-deep-freeze-turns-revision) | Next vendored sync |
 | inference-ts-cl-7783-truncated-tool-call | Surface `stop_reason`/`finish_reason` on usage events; fail the turn instead of dispatching unparseable tool calls at end-of-stream finalization | Alexander Guy <alexander.guy@pm.me> | This ledger (#inference-ts-cl-7783-truncated-tool-call) | Next vendored sync |
 | google-genai-files-ts-body-init-cast | Widen `BodyInit` to accept Node's `Uint8Array` typing so the cast can be removed | Alexander Guy <alexander.guy@pm.me> | This ledger (#google-genai-files-ts-body-init-cast) | Next vendored sync |
+| size-cap-ts-paged-read-file | Skip `createSizeCapTransform` for footer-bearing `read_file` pages so `Use offset=` survives the default 10k cap | Alexander Guy <alexander.guy@pm.me> | This ledger (#size-cap-ts-paged-read-file) | Next vendored sync |
 
 Contact basis: identified from the read-only upstream clone
 (`faremeter/interchange`); Alexander Guy <alexander.guy@pm.me> is the
@@ -605,6 +606,21 @@ the two on next sync, and consider restoring the dropped guard suite.
 **Removal path:**
 Upstream adding `claude-fable-5-1` to its own `ADAPTIVE_THINKING_MODELS`.
 
+## size-cap-ts-paged-read-file
+
+`transforms/size-cap.ts` — Footer-bearing `read_file` pages already carry a
+plain `Use offset=N to continue.` contract and are sized to the 50KB page
+budget. The default 10k size-cap would slice the body and drop the footer,
+stranding pagination. Pass those pages through unchanged (no spill). Other
+`read_file` results, and any other tool, still cap as before.
+
+**Disposition:** Promotion candidate. Requires upstream to skip size-cap when
+a `read_file` result already names the next offset. Downstream users that
+never emit that footer are unaffected.
+**Removal path:** Upstream PR to `@intx/inference` exempting footer-bearing
+`read_file` pages from `createSizeCapTransform`.
+**Re-carry:** isolated predicate at the start of `apply`; low merge risk.
+
 ---
 
 The `void track(p)` → `track(p)` change at three call sites in `reactor.ts`

vendor/intx-inference/src/transforms/size-cap.test.ts

@@ -169,4 +169,56 @@ describe("createSizeCapTransform", () => {
     }
     expect(thrown?.message).toContain("positive finite");
   });
+
+  test("passes a footer-bearing read_file page through even when over maxChars", async () => {
+    const { store, calls } = recordingWriteBlob();
+    const transform = createSizeCapTransform({
+      maxChars: 10_000,
+      contextStore: store,
+    });
+
+    const body = Array.from(
+      { length: 3000 },
+      (_, i) =>
+        `${String(i + 1).padStart(6, " ")}\tcell-${String(i)}-${"v".repeat(50)}`,
+    ).join("\n");
+    const page =
+      `${body}\n\n[Showing lines 1-3000; stopped at the 50KB output limit. ` +
+      `Use offset=3000 to continue.]`;
+    expect(page.length).toBeGreaterThan(10_000);
+    expect(page).toContain("Use offset=");
+
+    const result: ToolResult = { callId: "rf1", content: page };
+    const out = await transform.apply(
+      { call: call("rf1", "read_file"), result },
+      emptyContext(),
+    );
+
+    expect(out.output).toBe(result);
+    expect(out.output.content).toBe(page);
+    expect(String(out.output.content)).toContain("Use offset=");
+    expect(out.record.reason).toBe("paged-read-file");
+    expect(out.blobs).toBeUndefined();
+    expect(calls).toHaveLength(0);
+  });
+
+  test("still caps oversize read_file results that lack a continuation footer", async () => {
+    const { store, calls } = recordingWriteBlob();
+    const transform = createSizeCapTransform({
+      maxChars: 10_000,
+      contextStore: store,
+    });
+
+    const full = "x".repeat(12_000);
+    const result: ToolResult = { callId: "rf2", content: full };
+    const out = await transform.apply(
+      { call: call("rf2", "read_file"), result },
+      emptyContext(),
+    );
+
+    expect(out.record.reason).toBe("exceeded-cap");
+    expect(String(out.output.content)).toContain("Tool output truncated");
+    expect(String(out.output.content)).not.toContain("Use offset=");
+    expect(calls).toHaveLength(1);
+  });
 });

vendor/intx-inference/src/transforms/size-cap.ts

@@ -8,6 +8,8 @@
 //
 // Within-cap results pass through unchanged (no blob is written) but still
 // produce a `TransformRecord` so the manifest captures every invocation.
+// Locally patched — see vendor/intx-inference/PATCHES.md#size-cap-ts-paged-read-file:
+// footer-bearing `read_file` pages also pass through, even when over `maxChars`.
 
 import type {
   ContextStore,
@@ -19,12 +21,22 @@ import type {
 
 const SIZE_CAP_VERSION = "1";
 const SIZE_CAP_NAME = "size-cap";
+// Locally patched — see vendor/intx-inference/PATCHES.md#size-cap-ts-paged-read-file
+const READ_FILE_CONTINUATION_RE = /Use offset=\d+ to continue\./;
 
 export type SizeCapTransformOptions = {
   maxChars: number;
   contextStore: Pick<ContextStore, "writeBlob">;
 };
 
+function isPagedReadFilePage(toolName: string, result: ToolResult): boolean {
+  return (
+    toolName === "read_file" &&
+    typeof result.content === "string" &&
+    READ_FILE_CONTINUATION_RE.test(result.content)
+  );
+}
+
 /**
  * Create a `ToolResultTransform` that caps inline tool result content at
  * `maxChars` characters. Oversized results are spilled to the context store
@@ -54,6 +66,20 @@ export function createSizeCapTransform(
           ? result.content
           : JSON.stringify(result.content);
 
+      // Locally patched — see vendor/intx-inference/PATCHES.md#size-cap-ts-paged-read-file
+      if (isPagedReadFilePage(call.name, result)) {
+        return {
+          output: result,
+          record: {
+            strategy: SIZE_CAP_NAME,
+            version: SIZE_CAP_VERSION,
+            parameters: { maxChars },
+            reason: "paged-read-file",
+            decisions: { callId: call.id, length: text.length },
+          },
+        };
+      }
+
       if (text.length <= maxChars) {
         return {
           output: result,