@coreplane/switchboard 1.211.0 → 1.213.0

package/dist/assets/deploy/cloudflare-resident/wrangler.template.jsonc

@@ -30,7 +30,15 @@
     // binding's bucket below — the SDK signs URLs for this name, the offboard
     // sweep deletes through the binding. Public config, not secrets.
     "CLOUDFLARE_ACCOUNT_ID": "{{account}}",
-    "BACKUP_BUCKET_NAME": "{{script}}-cache"
+    "BACKUP_BUCKET_NAME": "{{script}}-cache",
+    // The wake budget (docs/reference/specs/resident-repos.md item 64): how long
+    // the SDK's physical start waits for the container's control port to accept
+    // a request before the first connect — WAKE_PORT_READY_MS in
+    // src/execution/residentRefresh.ts, 3 min in place of the SDK's 90 s, so a
+    // slow boot (a 2.65 GB image on a cold host) is not read as an unreachable
+    // runtime. The env name and its bounds (10 s to 600 s) are the SDK's; a test
+    // pins this value to the constant.
+    "SANDBOX_PORT_TIMEOUT_MS": "180000"
   },
   "containers": [
     {

package/dist/assets/deploy/cloudflare-sandbox/Dockerfile

@@ -136,3 +136,21 @@ RUN apt-get update \
   && playwright --version | grep -qx 'Version 1.63.0' \
   && playwright screenshot --viewport-size=640,480 'data:text/html,<h1>ok</h1>' /tmp/ok.png && test -s /tmp/ok.png \
   && rm -f /tmp/proof.mp4 /tmp/proof_*.png /tmp/ok.png
+
+# pi — the coding harness the bot can start INSIDE this container in place of
+# its native turn loop (docs/reference/specs/harness-pi.md): `pi --mode rpc`,
+# one process per run in the thread's worktree, driven by the bot over its
+# JSONL protocol, with the run's model-proxy bearer as its only key (never a
+# model key: the bearer buys calls through the bot, docs/reference/specs/
+# model-proxy.md). Installed globally with this image's Node — pi needs
+# >= 22.19.0 and the image ships 24 — so every user finds it on PATH, at an
+# EXACT pin held by src/deploy/imagePiHarness.test.ts (the pnpm lesson: a
+# floating tag would move the harness's protocol with the build date, and a
+# pi minor changes RPC events and extension hooks). Proven by the layer, so
+# the BUILD fails, not a run: the pi on PATH answers the pin, and its own help
+# names the RPC mode the harness drives. Dark until a deployment sets
+# `harness: { coding: pi }`: nothing here starts pi on its own.
+RUN npm install -g @earendil-works/pi-coding-agent@0.85.1 \
+  && npm cache clean --force \
+  && pi --version | grep -qx '0.85.1' \
+  && pi --help | grep -q -- '--mode <mode>'

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/deploy/secrets.manifest.json

@@ -75,6 +75,24 @@
       "optional": true,
       "note": "The secret half of R2_ACCESS_KEY_ID (same token). Both or neither."
     },
+    {
+      "name": "ARTIFACTS_R2_ACCESS_KEY_ID",
+      "workers": ["bot"],
+      "optional": true,
+      "note": "R2 API token (S3 access key id) scoped Object Read & Write to the artifacts bucket ONLY (`artifacts.r2.bucket` in config.yaml; docs/reference/specs/execution.md item 20): the bot signs presigned PUT/GET URLs and HEADs objects with it; it never carries a file. Optional: absent with no `artifacts:` section means no store. Created in the Cloudflare dashboard (R2 → Manage API tokens); rotate = new token, `deploy secrets bot`, `deploy restart`."
+    },
+    {
+      "name": "ARTIFACTS_R2_SECRET_ACCESS_KEY",
+      "workers": ["bot"],
+      "optional": true,
+      "note": "The secret half of ARTIFACTS_R2_ACCESS_KEY_ID (same token). Both or neither."
+    },
+    {
+      "name": "ARTIFACTS_COPY_TOKEN",
+      "workers": ["bot"],
+      "optional": true,
+      "note": "Shared bearer between the bot and its own Worker's `POST /artifacts/copy` route, which streams an inbound Slack file into the artifacts bucket (the Worker holds the R2 binding and the Slack token; the bot only asks). Self-minted (`openssl rand -hex 32`); the Worker checks it, the container presents it. Required whenever `artifacts:` is configured — the bot fails fast at startup without it."
+    },
     {
       "name": "MCP_CREDENTIAL_KEY",
       "workers": ["bot"],

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.211.0",
+  "version": "1.213.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.211.0",
+      "version": "1.213.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -21,6 +21,7 @@
       "dependencies": {
         "@anthropic-ai/sdk": "^0.124.0",
         "@slack/bolt": "^5.1.0",
+        "aws4fetch": "^1.0.20",
         "e2b": "^2.46.1",
         "mdast-util-from-markdown": "^2.0.3",
         "undici": "^8.10.2",
@@ -18999,11 +19000,12 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.211.0",
+      "version": "1.213.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.124.0",
         "@slack/bolt": "^5.1.0",
+        "aws4fetch": "^1.0.20",
         "e2b": "^2.46.1",
         "mdast-util-from-markdown": "^2.0.3",
         "undici": "^8.10.2",

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.211.0",
+  "version": "1.213.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",
@@ -81,6 +81,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.124.0",
     "@slack/bolt": "^5.1.0",
+    "aws4fetch": "^1.0.20",
     "e2b": "^2.46.1",
     "mdast-util-from-markdown": "^2.0.3",
     "undici": "^8.10.2",

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.211.0",
-  "commit": "1cee216b3cca53760bd183254c56904d4b990aa9",
-  "builtAt": "2026-09-14T06:10:14.818Z"
+  "version": "1.213.0",
+  "commit": "e6d1e5ef45c220f43d4a956547c3f55458fbf3ab",
+  "builtAt": "2026-09-14T17:32:11.100Z"
 }

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

@@ -42,6 +42,15 @@ export function machineNeedsRepo(machine: MachineClass): boolean {
 export const IDENTITIES = ["none", "read", "write"] as const;
 export type Identity = (typeof IDENTITIES)[number];
 
+/** The loops a preset's runs can be driven by (docs/reference/specs/harness-pi.md
+ *  item 1): `native`, the in-process turn loop (`src/runner.ts`), or `pi`, the
+ *  pi coding agent in the run's own execution container, driven over its RPC
+ *  protocol and bridged onto the run's events. A deployment's `harness:` block
+ *  overrides a preset's own declaration (`effectiveHarness`,
+ *  src/core/harness/select.ts). */
+export const HARNESSES = ["native", "pi"] as const;
+export type Harness = (typeof HARNESSES)[number];
+
 /** The pace that marks a run as looping rather than working: a model turn
  *  every ten seconds, sustained for the whole wall clock. A busy run takes
  *  20–40 s a turn (a model think plus a tool call), so a run that averages six
@@ -99,16 +108,22 @@ export interface AgentDef {
   /** 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
-   *  for a typed directive alone — structurally: it is absent from the table
-   *  the model is shown and refused by the allowlist even if the model names
-   *  it. `ship` (it holds the merge grant) and `conductor` (it starts other
-   *  runs) opt out. */
+   *  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
    *  resolution via RunOptions.system; the shared AgentDef is never mutated. */
   residentSystem?: string;
+  /** Which loop drives the preset's runs (`HARNESSES`): the native loop
+   *  unless declared, and whatever a deployment's `harness.<preset>` says
+   *  over that. Only a preset with a workspace can run on pi — pi is a process
+   *  in the run's execution container. */
+  harness?: Harness;
 }
 
 // Every PR the coding agent ships carries a rich description by default —
@@ -426,12 +441,34 @@ 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).
 
 Use Slack-friendly formatting (no markdown headers; *bold*, bullets, code blocks). Your final message is posted to Slack: lead with the outcome, then one line per child — its preset, its thread, its status and its result in a sentence — and what is still running, if anything.`;
 
+/** The compound answer's preset — the one preset absent from the router's
+ *  table that a plain message still reaches: a message with two or more
+ *  independent asks routes to it with the parts named
+ *  (docs/reference/specs/routing-and-config.md item 21). Its def below opts
+ *  out of the table (`routable: false`); the router names it only in the
+ *  compound form. */
+export const COMPOUND_PRESET = "conductor";
+
+/** How a plain message reaches a preset (docs/reference/specs/routing-and-config.md
+ *  item 21), read off its def: `routed` — a row of the router's table, picked
+ *  for a single ask; `compound` — the compound form alone, a message with
+ *  several independent asks; `directive` — never picked, only `agent:<name>`.
+ *  `help` renders its lines from this, so its words follow the registry. */
+export type PresetDoor = "routed" | "compound" | "directive";
+
+export function presetDoor(def: AgentDef): PresetDoor {
+  if (def.routable !== false) return "routed";
+  return def.name === COMPOUND_PRESET ? "compound" : "directive";
+}
+
 export const AGENTS: Record<string, AgentDef> = {
   general: {
     name: "general",
@@ -463,6 +500,9 @@ export const AGENTS: Record<string, AgentDef> = {
     // `config set channel efforts.coding=…`, or `effort:` per request).
     machine: "repo-resident",
     identity: "write", // pushes branches and opens pull requests
+    // The native loop until the pi series moves this preset; a deployment
+    // flips it early with `harness: { coding: pi }` (docs/reference/specs/harness-pi.md).
+    harness: "native",
   },
   review: {
     name: "review",
@@ -543,9 +583,12 @@ export const AGENTS: Record<string, AgentDef> = {
     // dispatcher, the GitHub reads are REST in the bot process.
     machine: "none",
     identity: "none",
-    // Never offered to the router: its children are runs under the requester's
-    // permissions with a directive of their own, so a routed conductor could
-    // fan a plain message out into runs nobody named — a person names it.
+    // 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

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

@@ -46,6 +46,14 @@ const REDACT: Array<{ re: RegExp; replace: string }> = [
 const SECRET_COMPONENT =
   /^(secret|token|password|passwd|pwd|credential|credentials|key|apikey|auth|session|sessionid|cookie)$/i;
 
+// An identifier component that marks the whole identifier as an ERROR CODE, not
+// a secret name: `github-token-mint-failed: HTTP 422 …` names a failure about a
+// token, and the word after the colon is diagnosis, never a credential. Without
+// this guard the assignment pass redacted `HTTP` out of that message
+// (`github-token-mint-failed: «redacted» 422 …`), garbling the one line that
+// tells an operator what went wrong.
+const ERROR_CODE_COMPONENT = /^(failed|failure|error|err|refused|denied|invalid|missing|expired|unset|mismatch)$/i;
+
 /** Redact the VALUE of any `<name> = value` / `<name>: value` where the name has
  *  a secret-marking component. Handles quoted values (with spaces) and unquoted,
  *  and a quoted NAME (`"password": "…"` in pasted JSON — the closing quote sits
@@ -64,7 +72,9 @@ function redactNamedAssignments(text: string): string {
     // decides whether it names a secret (`_SECRET` → ["", "SECRET"]).
     /(?<![A-Za-z0-9_-])([A-Za-z0-9_-]+)("?)(\s*[=:]\s*)("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^\s]{4,})/g,
     (whole, id: string, close: string, sep: string, val: string) => {
-      if (!id.split(/[_-]/).some((p) => SECRET_COMPONENT.test(p))) return whole;
+      const parts = id.split(/[_-]/);
+      if (!parts.some((p) => SECRET_COMPONENT.test(p))) return whole;
+      if (parts.some((p) => ERROR_CODE_COMPONENT.test(p))) return whole;
       const quote = val[0] === '"' || val[0] === "'" ? val[0] : "";
       return `${id}${close}${sep}${quote}«redacted»${quote}`;
     },

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

@@ -118,7 +118,23 @@ export type RunNoteKind =
    *  post-step beside the thread's Slack-only note, so the record says the
    *  verdict is Slack-only and a coordinator reading it never asks GitHub
    *  for a review that was never sent. */
-  | "review_not_posted";
+  | "review_not_posted"
+  /** A pi run's context was compacted (docs/reference/specs/harness-pi.md item
+   *  6): pi summarized its older turns into one entry and the model reads the
+   *  summary from here on; the transcript keeps the originals, so the record
+   *  is a superset of the model's context. The summary names the token counts
+   *  before and after. Published by the pi bridge. */
+  | "compacted"
+  /** The pi harness itself failed in a way the run must show (harness-pi.md
+   *  item 6): the extension threw, pi asked a dialog no one answers (answered
+   *  cancelled), or pi emitted an event kind this build's bridge does not
+   *  know — named, so a pi bump is visible in the first run's record. Published
+   *  by the pi bridge. */
+  | "harness_error"
+  /** The harness's gate refused a tool call the model asked for (harness-pi.md
+   *  item 7): the summary names the tool and the rule; the model read the same
+   *  reason as the tool's result. Published by the bot's authorize route. */
+  | "tool_refused";
 
 /** Every `RunNoteKind`, as a value (a reader that filters notes by kind uses
  *  this; adding a kind to the union without adding it here is a type error). */
@@ -139,6 +155,9 @@ export const RUN_NOTE_KINDS = [
   "cold_sandbox",
   "pr_not_opened",
   "review_not_posted",
+  "compacted",
+  "harness_error",
+  "tool_refused",
 ] as const satisfies readonly RunNoteKind[];
 type _EveryKindListed = [RunNoteKind] extends [(typeof RUN_NOTE_KINDS)[number]] ? true : never;
 const _everyKindListed: _EveryKindListed = true;
@@ -383,6 +402,27 @@ export type RunEvent =
       seq?: number;
       at?: number;
     }
+  /** A file moved through the artifact store (docs/reference/specs/execution.md item 20,
+   *  record 0033): one the run received from its thread (`in`, staged before
+   *  the turn) or one it sent (`out`, `attach_file`). The record keeps the
+   *  store KEY and the facts a page needs to list the file — never a URL: the
+   *  run page's proxy route (`/runs/:id/artifacts/<key>`, live-view.md item 26)
+   *  mints a signed GET per request, so a stored record never carries a
+   *  credential that expires or leaks, and the parser refuses a payload that
+   *  tries. A side fact beside the tool pair that moved the file (like
+   *  `skill_use`), never a step; the friction analyzer ignores it. */
+  | {
+      type: "artifact";
+      direction: "in" | "out";
+      /** The store key (`src/artifacts/keys.ts`): `runs/<runId>/out/<seq>-<basename>` or `threads/<thread>/in/<ts>/<i>-<basename>`. */
+      key: string;
+      /** The file's name as the person sees it (the Slack filename, the tool's `name`). */
+      name: string;
+      size: number;
+      contentType: string;
+      seq?: number;
+      at?: number;
+    }
   /** A skill was loaded into the model's context (docs/reference/specs/skills.md). Emitted
    *  by the `use_skill` tool on a successful load — alongside, not instead of,
    *  its `tool_call`/`tool_result` pair — so skill use is a first-class fact in
@@ -489,11 +529,25 @@ export type RunEvent =
   /** 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. Published by the dispatcher
-   *  straight to the registry right after `run_meta`, once per routed run;
-   *  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; seq?: number; at?: number }
+   *  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

@@ -384,12 +384,14 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
       return;
     }
     // 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, 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.
+    // call that already produced its own tool pair, and artifact beside the
+    // attach_file call (or the dispatcher's staging) that moved the file;
+    // review_artifact, 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 === "artifact" ||
       ev.type === "review_artifact" ||
       ev.type === "pr_description" ||
       ev.type === "pr_opened" ||

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

@@ -55,6 +55,10 @@ export function shimRoute(pathname: string): string | undefined {
   // The model proxy's two routes (docs/reference/specs/model-proxy.md): a bounded
   // request per model call, forwarded to the container like everything else.
   if (pathname === "/v1/messages" || pathname === "/v1/chat/completions") return "model-proxy";
+  // The pi harness's three routes (docs/reference/specs/harness-pi.md item 7): a
+  // run's extension asking for its tools, a verdict, a relayed tool's result.
+  if (pathname === "/harness/tools" || pathname === "/harness/authorize" || pathname === "/harness/tool")
+    return "harness";
   if (pathname === "/docs" || pathname.startsWith("/docs/")) return "docs";
   if (pathname === "/" || pathname === "/index.html") return "page";
   return "other";

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