@coreplane/switchboard 1.210.0 → 1.212.0

package/dist/assets/deploy/cloudflare-resident/worker.ts

@@ -96,11 +96,14 @@ import {
 } from "../../src/execution/residentDepCache.js";
 import { parseWorktreeCleanliness, worktreeCleanlinessScript } from "../../src/execution/residentCleanliness.js";
 import {
-  base64ByteLength,
-  MAX_READ_BASE64_CHARS,
+  base64LengthOf,
+  chunkPlan,
   MAX_READ_BYTES,
+  parseByteSize,
+  readChunkCommandFor,
   readCommandFor,
   readEncodingOf,
+  statCommandFor,
   type Base64ReadAnswer,
   type ReadEncoding,
 } from "../../src/execution/binaryRead.js";
@@ -1692,7 +1695,7 @@ export class ResidentDO extends Sandbox<Env> {
   private async run(
     argv: readonly string[],
     opts: { cwd?: string; timeoutMs?: number; env?: Record<string, string> } = {},
-  ): Promise<{ stdout: string; stderr: string; exitCode: number; timedOut: boolean }> {
+  ): Promise<{ stdout: string; stderr: string; exitCode: number; timedOut: boolean; truncated?: boolean }> {
     const timeout = opts.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS;
     const launch = {
       ...(opts.cwd ? { cwd: opts.cwd } : {}),
@@ -1727,7 +1730,15 @@ export class ResidentDO extends Sandbox<Env> {
     }
     try {
       const out = await proc.output({ encoding: "utf8", timeout: timeout + 30_000 });
-      return { stdout: out.stdout, stderr: out.stderr, exitCode: out.exitCode, timedOut: out.timedOut };
+      // `truncated` is the SDK saying the process log stream was cut past its
+      // own retention — the output here is a prefix, whatever our caps say.
+      return {
+        stdout: out.stdout,
+        stderr: out.stderr,
+        exitCode: out.exitCode,
+        timedOut: out.timedOut,
+        truncated: out.truncated,
+      };
     } catch (err) {
       if (isRuntimeReplacement(err)) {
         this.swapIncarnation(); // the container this incarnation's memos described is gone
@@ -3931,7 +3942,7 @@ export class ResidentDO extends Sandbox<Env> {
     timeoutMs: number,
     capBytes?: number,
     capFiles?: { out: string; err: string },
-  ): Promise<{ stdout: string; stderr: string; exitCode: number; timedOut: boolean }> {
+  ): Promise<{ stdout: string; stderr: string; exitCode: number; timedOut: boolean; truncated?: boolean }> {
     const injected = { GIT_TERMINAL_PROMPT: "0" };
     validateEnvNames(injected);
     const body = capBytes
@@ -3954,7 +3965,7 @@ export class ResidentDO extends Sandbox<Env> {
     command: string,
     timeoutMs: number,
     charCap: number,
-  ): Promise<{ stdout: string; stderr: string; exitCode: number; timedOut: boolean }> {
+  ): Promise<{ stdout: string; stderr: string; exitCode: number; timedOut: boolean; truncated?: boolean }> {
     const capBytes = capBytesFor(charCap);
     const files = execCapFiles();
     const r = await this.threadRun(user, worktreePath, command, timeoutMs, capBytes, files);
@@ -5161,7 +5172,7 @@ export class ResidentDO extends Sandbox<Env> {
       if (err instanceof RuntimeReplacedError) return runtimeReplacedErr(err);
       throw err;
     }
-    const truncated = r.stdout.length > EXEC_OUTPUT_CAP || r.stderr.length > EXEC_OUTPUT_CAP;
+    const truncated = r.stdout.length > EXEC_OUTPUT_CAP || r.stderr.length > EXEC_OUTPUT_CAP || r.truncated === true;
     const notes: string[] = [];
     if (r.timedOut)
       notes.push(
@@ -5201,31 +5212,68 @@ export class ResidentDO extends Sandbox<Env> {
     const resolved = confineThreadPath(pre.binding.worktreePath, path);
     if (!resolved)
       return { error: `path-escape: ${JSON.stringify(path)} does not stay inside the thread worktree`, status: 400 };
-    const cap = encoding === "base64" ? MAX_READ_BASE64_CHARS : READ_CONTENT_CAP;
+    if (encoding === "base64") return this.readThreadBytes(pre.binding, resolved);
     let r: Awaited<ReturnType<ResidentDO["threadRun"]>>;
     try {
       r = await this.threadRun(
         pre.binding.user,
         pre.binding.worktreePath,
-        readCommandFor(encoding, resolved),
+        readCommandFor(resolved),
         DEFAULT_EXEC_TIMEOUT_MS,
-        capBytesFor(cap),
+        capBytesFor(READ_CONTENT_CAP),
       );
     } catch (err) {
       if (err instanceof RuntimeReplacedError) return runtimeReplacedErr(err);
       throw err;
     }
     if (r.exitCode !== 0 || r.timedOut) return { error: `read-failed: ${describeStepFailure(r)}`, status: 404 };
-    const truncated = r.stdout.length > cap;
-    if (encoding === "base64") {
-      // Padding hides up to two bytes inside the cap's char count, so the
-      // decoded size is checked too — the cap is bytes, not characters.
-      const content = r.stdout.trimEnd();
-      return truncated || base64ByteLength(content) > MAX_READ_BYTES
-        ? { encoding, tooLarge: true }
-        : { encoding, content };
+    const truncated = r.stdout.length > READ_CONTENT_CAP || r.truncated === true;
+    return { content: truncated ? r.stdout.slice(0, READ_CONTENT_CAP) : r.stdout, truncated };
+  }
+
+  /** The bytes of a confined file as base64, as the thread user, in chunks
+   *  (src/execution/binaryRead.ts): one command's stdout crosses the SDK's
+   *  process log stream, which cuts a stream past a retention limit far below
+   *  the binary cap and says so only through `truncated` — a 12 MB file once
+   *  came back as 1.7 MB and was handed on as complete. So: `stat` first (the
+   *  cap is judged on the size, before any read), then chunks small enough
+   *  that no stream is ever cut; a chunk the SDK still flags, or one whose
+   *  length is not what the size promised, fails the read by name. The answer
+   *  carries the size for the client to check the decoded bytes against. */
+  private async readThreadBytes(
+    binding: { user: string; worktreePath: string },
+    resolved: string,
+  ): Promise<Base64ReadAnswer | ThreadErr> {
+    const run = (command: string, capChars: number) =>
+      this.threadRun(binding.user, binding.worktreePath, command, DEFAULT_EXEC_TIMEOUT_MS, capBytesFor(capChars));
+    try {
+      const stat = await run(statCommandFor(resolved), 64);
+      if (stat.exitCode !== 0 || stat.timedOut)
+        return { error: `read-failed: ${describeStepFailure(stat)}`, status: 404 };
+      const size = parseByteSize(stat.stdout);
+      if (size === null)
+        return { error: `read-failed: stat answered ${JSON.stringify(stat.stdout.slice(0, 64))}`, status: 500 };
+      if (size > MAX_READ_BYTES) return { encoding: "base64", tooLarge: true };
+      const chunks = chunkPlan(size);
+      const parts: string[] = [];
+      for (const [i, chunk] of chunks.entries()) {
+        const expected = base64LengthOf(chunk.length);
+        const r = await run(readChunkCommandFor(resolved, chunk), expected);
+        if (r.exitCode !== 0 || r.timedOut) return { error: `read-failed: ${describeStepFailure(r)}`, status: 404 };
+        const piece = r.stdout.trimEnd();
+        if (r.truncated === true || piece.length !== expected) {
+          return {
+            error: `read-inconsistent: chunk ${i + 1} of ${chunks.length} arrived as ${piece.length} of ${expected} base64 chars${r.truncated ? " (the SDK cut the output stream)" : ""}`,
+            status: 409,
+          };
+        }
+        parts.push(piece);
+      }
+      return { encoding: "base64", content: parts.join(""), size };
+    } catch (err) {
+      if (err instanceof RuntimeReplacedError) return runtimeReplacedErr(err);
+      throw err;
     }
-    return { content: truncated ? r.stdout.slice(0, cap) : r.stdout, truncated };
   }
 
   /** POST /write: content travels via the SDK file API into the thread's
@@ -5652,7 +5700,7 @@ export class ResidentDO extends Sandbox<Env> {
         timedOut: r.timedOut,
       });
       const ok = r.exitCode === 0 && !r.timedOut;
-      const truncated = r.stdout.length > EXEC_OUTPUT_CAP || r.stderr.length > EXEC_OUTPUT_CAP;
+      const truncated = r.stdout.length > EXEC_OUTPUT_CAP || r.stderr.length > EXEC_OUTPUT_CAP || r.truncated === true;
       const notes: string[] = [];
       if (r.timedOut) notes.push(`command timed out after ${OP_EXEC_TIMEOUT_MS}ms`);
       if (truncated) notes.push(`output truncated to ${EXEC_OUTPUT_CAP} chars per stream`);

package/dist/assets/deploy/cloudflare-sandbox/worker.ts

@@ -21,7 +21,9 @@ import { BASH_TIMEOUT_MAX_MS, clampBashTimeout } from "../../src/execution/bashT
 import {
   base64ByteLength,
   MAX_READ_BYTES,
+  parseByteSize,
   readEncodingOf,
+  statCommandFor,
   type Base64ReadAnswer,
 } from "../../src/execution/binaryRead.js";
 import {
@@ -278,13 +280,25 @@ export default {
           if (typeof encoding !== "string") return json({ error: encoding.error }, 400);
           const path = abs(String(body.path ?? ""));
           if (encoding === "base64") {
+            // The size first, from `stat`, so the cap is judged before any
+            // read and the client can hold the decoded bytes to it — an SDK
+            // read that came back short would otherwise pass as the file.
+            const stat = await withSessionRecovery(sandbox, () => sandbox.exec(statCommandFor(path)));
+            if ((stat.exitCode ?? 0) !== 0) {
+              return json({ error: `read-failed: ${String(stat.stderr ?? stat.stdout ?? "").trim()}` }, 404);
+            }
+            const size = parseByteSize(String(stat.stdout ?? ""));
+            if (size === null) return json({ error: `read-failed: stat answered ${JSON.stringify(stat.stdout)}` }, 500);
+            if (size > MAX_READ_BYTES) return json({ encoding: "base64", tooLarge: true } satisfies Base64ReadAnswer);
             const file = await withSessionRecovery(sandbox, () => sandbox.readFile(path, { encoding: "base64" }));
             const content = typeof file === "string" ? file : (file?.content ?? "");
-            const answer: Base64ReadAnswer =
-              base64ByteLength(content) > MAX_READ_BYTES
-                ? { encoding: "base64", tooLarge: true }
-                : { encoding: "base64", content };
-            return json(answer);
+            const got = base64ByteLength(content);
+            if (got !== size) {
+              // 409, not 5xx: the client retries a 5xx twice over 30 s, and a
+              // short read is answered by the caller re-reading, not by waiting.
+              return json({ error: `read-inconsistent: ${path} is ${size} bytes but the read returned ${got}` }, 409);
+            }
+            return json({ encoding: "base64", content, size } satisfies Base64ReadAnswer);
           }
           const file = await withSessionRecovery(sandbox, () => sandbox.readFile(path));
           return json({ content: typeof file === "string" ? file : (file?.content ?? "") });

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.210.0",
+  "version": "1.212.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.210.0",
+      "version": "1.212.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -18999,7 +18999,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.210.0",
+      "version": "1.212.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.124.0",

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.210.0",
+  "version": "1.212.0",
   "private": true,
   "description": "Mention it in Slack and an agent reviews the PR, ships the fix, or answers the question — on the model you choose, with its tools running where you decide.",
   "license": "Apache-2.0",

package/dist/assets/project.json

@@ -212,7 +212,7 @@
       "when": "Part of `check:consistency`."
     },
     "load": {
-      "does": "Load harness: `-- history|resident|sandbox|e2e|cards|provider|pi`.",
+      "does": "Load harness: `-- history|resident|sandbox|e2e|cards|provider|pi|route`.",
       "when": "Capacity receipts (docs/reference/specs/load-harness.md)."
     }
   }

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.210.0",
-  "commit": "1c1f94ae5c58bff0f3734e2b522b2ab440baa89d",
-  "builtAt": "2026-09-14T05:52:14.303Z"
+  "version": "1.212.0",
+  "commit": "c3e94f963fc37fc7c8308cb34268f868413b76b3",
+  "builtAt": "2026-09-14T06:44:27.746Z"
 }

package/dist/assets/src/agents/registry.ts

@@ -96,6 +96,15 @@ export interface AgentDef {
    *  worktree flag and the token the sandbox env and the `repo-cold` vet mint
    *  read this, through the run's effective profile. */
   identity: Identity;
+  /** Whether the request router (docs/reference/specs/routing-and-config.md
+   *  item 21) may pick this preset for a plain message. Absent means yes: the
+   *  router's table is rendered from this registry. `false` keeps a preset
+   *  out of the table — structurally: it is absent from the table the model
+   *  is shown and refused as a single route even if the model names it.
+   *  `ship` (it holds the merge grant) opts out for good; `conductor` (it
+   *  starts other runs) opts out of the table and is reached through the
+   *  router's compound form alone, with its parts named. */
+  routable?: false;
   /** System prompt variant for resident-repo runs (docs/reference/specs/resident-repos.md):
    *  the workspace is a ready worktree — no cloning, no installs, no repo
    *  discovery, no gh CLI. Selected by the dispatcher AFTER executor
@@ -418,6 +427,8 @@ WHAT A CHILD IS. A child is an ordinary Switchboard run started as the person wh
 
 THE PRESETS a child can run: \`research\` (a question the web or our repositories answer), \`coding\` (implement a change and open a pull request; needs the repository), \`review\` (review a pull request; needs its URL), \`explore\` (a long, read-only investigation with a shell; needs the repository), \`general\` (a quick answer with the GitHub tools), \`ship\` (coding, review and fixes until a pull request is merge-ready; needs the repository).
 
+ROUTED COMPOUNDS. A request may arrive already split: the router found independent parts, and the message ends with the line "Routed as a compound request: N independent parts" followed by a numbered list, one part per line as \`<preset>\`: <text>. Spawn exactly those children — one \`spawn_run\` per line, the preset as listed, the line's text as the child's prompt (it already stands alone; add the repository where the preset needs one) — then \`await_runs\` them all and compile. Never merge, drop or add a part; a part whose spawn is refused is reported as refused, by the gate's name.
+
 HOW TO WORK. Fan out, await, compile. Read the request and split it into children only where the parts are independent; a request one preset answers is one child. Spawn each child with a self-contained prompt — everything it needs, since it sees none of this thread — and the repository where the preset needs one. Then call \`await_runs\` once with every child's id: it returns when all of them have ended, or earlier — at the edge of your own budget, at a stop, or when a follow-up lands in this thread — and \`ended\` says which; a child still running at the cut keeps running (name it in your answer, or await again after a follow-up). Steer a child with \`send_to_run\` when the request changes or a child is heading the wrong way. A child that ended — finished, failed, interrupted by a restart — is reported as it ended and never restarted; spawn a new child if the work still matters. Then compile: one answer from the write-ups \`await_runs\` returned. Never do a child's job yourself, and never claim a child finished or found something you did not read from \`await_runs\` or \`get_run_status\`.
 
 Maintain the user-facing status card with the update_status tool: one item per child (○ pending, ✱ running, ✓ finished — only once await_runs or get_run_status said so).
@@ -488,6 +499,10 @@ export const AGENTS: Record<string, AgentDef> = {
     toolset: "full",
     machine: "repo-resident",
     identity: "write",
+    // Never routed: ship is the plan runner and holds the merge grant, so a
+    // wrong route into it is code landing on main, not a stray pull request.
+    // A request that wants it names it — `agent:ship`.
+    routable: false,
     maxTurns: 1,
     maxTokens: 16000,
     maxMinutes: 120,
@@ -531,6 +546,13 @@ export const AGENTS: Record<string, AgentDef> = {
     // dispatcher, the GitHub reads are REST in the bot process.
     machine: "none",
     identity: "none",
+    // Never a row of the router's table: a plain message is never routed to a
+    // conductor that decides the split itself. The compound form is its one
+    // door (docs/reference/specs/routing-and-config.md item 21): the router
+    // names the parts and their presets, each checked against the same table
+    // and the requester's allowlist, and the brief tells the conductor to
+    // spawn exactly those — so no child runs that the record did not name.
+    routable: false,
     maxTokens: 32000,
     ...loopBudget(120), // long enough to outlast a coding child; every child is capped by what remains of it
     // No built-in effort: the deployment decides, as for coding.

package/dist/assets/src/core/runEvents.ts

@@ -144,6 +144,13 @@ type _EveryKindListed = [RunNoteKind] extends [(typeof RUN_NOTE_KINDS)[number]]
 const _everyKindListed: _EveryKindListed = true;
 void _everyKindListed;
 
+/** How a run's preset was chosen (docs/reference/specs/routing-and-config.md
+ *  items 1–3 and 21), as `run_meta.agentSource` records it: a directive on
+ *  the message, the thread's sticky preset, the user or the channel scope's
+ *  `agent`, `defaults.agent`, or the request router. The replay harness
+ *  (`load route`) reads it to tell a requester's own choice from a fallback. */
+export type AgentSource = "directive" | "sticky" | "user" | "channel" | "default" | "route";
+
 /** How an operator asked a run to stop: `soft` — take no new steps and
  *  wrap up through the normal finale; `hard` — abort the in-flight call now, no
  *  finale, tear the workspace down. */
@@ -204,13 +211,14 @@ export function isSpanRecord(e: { type: string }): e is SpanStartEvent | SpanEnd
 }
 
 /** The protected head (docs/reference/specs/tracing.md; live-view item 2) — is this event head material? The root's start, `slack.receive` and the
- *  `dispatch.*` span pairs, `input`, `context`, `run_meta`, and the
+ *  `dispatch.*` span pairs, `input`, `context`, `run_meta`, `route`, and the
  *  `mcp_unavailable` / `spans_dropped` notes. */
 export function isHeadMaterial(event: RunEvent): boolean {
   switch (event.type) {
     case "input":
     case "context":
     case "run_meta":
+    case "route":
       return true;
     case "run_note":
       return event.kind === "mcp_unavailable" || event.kind === "spans_dropped" || event.kind === "cold_sandbox";
@@ -361,6 +369,8 @@ export type RunEvent =
   | {
       type: "run_meta";
       agent: string;
+      /** How `agent` was chosen (`AgentSource`); absent on a command run and on records written before it existed. */
+      agentSource?: AgentSource;
       /** Absent on a command run, which resolves no model. */
       model?: string;
       /** The request's trace id (docs/reference/specs/tracing.md), once the root exists. */
@@ -476,6 +486,28 @@ export type RunEvent =
    *  straight to the registry (like `pr_opened`), never through the runner.
    *  Additive: unknown → ignored. */
   | { type: "ship_round"; index: number; agent: string; outcome: ShipRoundOutcome; seq?: number; at?: number }
+  /** The request router's decision (docs/reference/specs/routing-and-config.md
+   *  item 21): the preset a plain message was routed to, the one-line reason
+   *  the router gave (redacted, capped — the same text the card's `routed:`
+   *  line carries) and the model that decided. A compound route is `preset:
+   *  "conductor"` with `parts` — one per child the conductor was told to
+   *  spawn: its preset and its text, the child's whole prompt. A compound the
+   *  parse refused is recorded too, on the run that fell to the default:
+   *  `preset` is `defaults.agent` and `reason` reads `compound_rejected:
+   *  <why>` (the run's `run_meta.agentSource` stays `default`). Published by
+   *  the dispatcher straight to the registry right after `run_meta`, once per
+   *  run the router answered; absent on every run a directive, a sticky
+   *  preset or a scope chose. Head material, like `run_meta`. Additive:
+   *  unknown → ignored. */
+  | {
+      type: "route";
+      preset: string;
+      reason: string;
+      model: string;
+      parts?: ReadonlyArray<{ preset: string; text: string }>;
+      seq?: number;
+      at?: number;
+    }
   /** The span records (docs/reference/specs/tracing.md): published, counted and stored like
    *  every other event, read as timing and never as content. */
   | SpanStartEvent

package/dist/assets/src/core/runFriction.ts

@@ -370,7 +370,7 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
   // final answer (`answer`) — are the run's story, not its steps: none counts
   // toward `eventCount`.
   let narrativeEvents = 0;
-  let sideFactEvents = 0; // skill_use / review_artifact / pr_description / pr_opened / review_posted / ship_round: facts about the run, not steps
+  let sideFactEvents = 0; // skill_use / review_artifact / pr_description / pr_opened / review_posted / ship_round / route: facts about the run, not steps
   let spanEvents = 0; // span_start / span_end (docs/reference/specs/tracing.md): timing records, not steps
   let wrapUp: { index: number; at?: number } | undefined;
   events.forEach((ev, index) => {
@@ -385,16 +385,17 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
     }
     // Side facts about the run, not steps: skill_use rides beside a use_skill
     // call that already produced its own tool pair; review_artifact,
-    // pr_description, pr_opened, review_posted and the ship_round boundaries
-    // are published by the dispatcher/pipeline outside the model loop
-    // entirely. Counting any of them would distort the story.
+    // pr_description, pr_opened, review_posted, the ship_round boundaries and
+    // the router's route are published by the dispatcher/pipeline outside the
+    // model loop entirely. Counting any of them would distort the story.
     if (
       ev.type === "skill_use" ||
       ev.type === "review_artifact" ||
       ev.type === "pr_description" ||
       ev.type === "pr_opened" ||
       ev.type === "review_posted" ||
-      ev.type === "ship_round"
+      ev.type === "ship_round" ||
+      ev.type === "route"
     ) {
       sideFactEvents++;
       return;

package/dist/assets/src/core/trace/streamSpans.ts

@@ -38,6 +38,7 @@ export const STREAMED_SPANS = [
   "dispatch.refuse",
   "dispatch.ship_preflight",
   "dispatch.ledger_claim",
+  "dispatch.route",
   "run.agent",
   "run.command",
   "run.reading_diff",
@@ -89,6 +90,7 @@ const GETTING_READY: ReadonlySet<string> = new Set([
   "dispatch.refuse",
   "dispatch.ship_preflight",
   "dispatch.ledger_claim",
+  "dispatch.route",
 ]);
 const FINISHING_UP: ReadonlySet<string> = new Set([
   "run.observe_workspace",
@@ -145,6 +147,7 @@ export const PARENTS: Readonly<Record<string, readonly string[]>> = {
   "dispatch.refuse": ["request"],
   "dispatch.ship_preflight": ["request"],
   "dispatch.ledger_claim": ["request"],
+  "dispatch.route": ["request"],
   "run.agent": ["request", "ship.round", "run.settle_reviewed_head", "run.description_turn"],
   "run.command": ["request"],
   "run.reading_diff": ["request"],

package/dist/assets/src/execution/binaryRead.ts

@@ -2,10 +2,10 @@
 // the whole file as bytes, for a tool that hands a workspace artifact — a
 // screenshot, a PDF — to somewhere that needs the bytes, not a text view. Both
 // remote executors ask their Worker's `/read` route for `encoding: "base64"`;
-// the Worker answers `{ content, encoding: "base64" }`. This module is the
-// contract both ends share: the caps, the request/answer shape, the resident's
-// read command. It is bundled into the Workers too, so it stays free of Node
-// imports.
+// the Worker answers `{ encoding: "base64", content, size }`. This module is
+// the contract both ends share: the caps, the request/answer shape, the
+// resident's stat and chunk commands. It is bundled into the Workers too, so it
+// stays free of Node imports.
 
 /** The most bytes one `readBytes` hands over. A binary cannot be truncated
  *  the way text output is, so a larger file is refused by name, never trimmed.
@@ -28,11 +28,10 @@ export function readEncodingOf(body: Record<string, unknown>): ReadEncoding | {
   return { error: `encoding must be "base64" or absent, got ${JSON.stringify(body.encoding)}` };
 }
 
-/** The command a resident runs for a read of an already-confined path: `cat`
- *  for text; `base64 -w0` for bytes — one unwrapped line, so the Durable
- *  Object's character cap slices a plain string and nothing else. */
-export function readCommandFor(encoding: ReadEncoding, resolvedPath: string): string {
-  return encoding === "base64" ? `base64 -w0 -- ${resolvedPath}` : `cat -- ${resolvedPath}`;
+/** The command a resident runs for a text read of an already-confined path.
+ *  Bytes never go through one command: see `chunkPlan`. */
+export function readCommandFor(resolvedPath: string): string {
+  return `cat -- ${resolvedPath}`;
 }
 
 /** How many bytes a base64 string decodes to, padding discounted. */
@@ -43,11 +42,54 @@ export function base64ByteLength(b64: string): number {
   return Math.floor((trimmed.length * 3) / 4) - padding;
 }
 
-/** A Worker's answer to a base64 read: the bytes, or the named refusal of a
- *  file over the cap — HTTP 200 either way. The clients classify a non-2xx or
- *  an in-body `error` as a sick Worker (fail-fast counts it); a large file is
- *  the model's mistake, not infrastructure, so it travels as a plain field. */
-export type Base64ReadAnswer = { encoding: "base64"; content: string } | { encoding: "base64"; tooLarge: true };
+/** A Worker's answer to a base64 read: the bytes with the file's size, or the
+ *  named refusal of a file over the cap — HTTP 200 either way. The clients
+ *  classify a non-2xx or an in-body `error` as a sick Worker (fail-fast counts
+ *  it); a large file is the model's mistake, not infrastructure, so it travels
+ *  as a plain field. `size` is the file's byte count from a `stat` taken before
+ *  the read: the client refuses an answer whose decoded length differs, so a
+ *  stream cut in transit can never pass as the file. */
+export type Base64ReadAnswer =
+  { encoding: "base64"; content: string; size: number } | { encoding: "base64"; tooLarge: true };
+
+/** The command that measures a confined file, as the thread user: one number. */
+export function statCommandFor(resolvedPath: string): string {
+  return `stat -c %s -- ${resolvedPath}`;
+}
+
+/** `stat -c %s`'s output as a byte count; null for anything that is not one. */
+export function parseByteSize(stdout: string): number | null {
+  const m = /^\s*(\d{1,15})\s*$/.exec(stdout);
+  return m ? Number(m[1]) : null;
+}
+
+/** Bytes per chunk of a resident's base64 read. A command's stdout crosses the
+ *  sandbox SDK's process log stream, which cuts a stream past a retention
+ *  limit the typings do not name (observed: about 2.3 MB) and reports the cut
+ *  only as a `truncated` flag — so no single command may carry the whole file.
+ *  One MiB less one: a multiple of 3, so each chunk's base64 has no padding and
+ *  the pieces concatenate into the encoding of the whole. */
+export const READ_CHUNK_BYTES = 1_048_575;
+
+/** The chunks that cover a `size`-byte file, in order; none for an empty file. */
+export function chunkPlan(size: number, chunkBytes = READ_CHUNK_BYTES): Array<{ offset: number; length: number }> {
+  const chunks: Array<{ offset: number; length: number }> = [];
+  for (let offset = 0; offset < size; offset += chunkBytes) {
+    chunks.push({ offset, length: Math.min(chunkBytes, size - offset) });
+  }
+  return chunks;
+}
+
+/** One chunk of a confined file as unwrapped base64: `tail -c +N` seeks on a
+ *  regular file, `head -c` bounds the piece. */
+export function readChunkCommandFor(resolvedPath: string, chunk: { offset: number; length: number }): string {
+  return `tail -c +${chunk.offset + 1} -- ${resolvedPath} | head -c ${chunk.length} | base64 -w0`;
+}
+
+/** The base64 length `bytes` encode to (four chars per three bytes, padded). */
+export function base64LengthOf(bytes: number): number {
+  return Math.ceil(bytes / 3) * 4;
+}
 
 /** One message for a file over the cap, for every implementation. `bytes` is
  *  the size when the reader could measure it; a resident sees only that its

package/dist/assets/src/execution/residentStepReport.ts

@@ -24,6 +24,10 @@ export interface StepResult {
   stderr: string;
   exitCode: number;
   timedOut: boolean;
+  /** The sandbox SDK cut the process's output stream past its own retention
+   *  limit (one its typings do not name; about 2.3 MB observed): what is here
+   *  is a prefix. Distinct from the DO's char caps, which slice what arrived. */
+  truncated?: boolean;
 }
 
 /** Chars kept per stream in the STORED reason — it travels into DO storage,