@coreplane/switchboard 1.205.0 → 1.206.0

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

@@ -11,7 +11,12 @@ import {
 import { tokenize } from "../../src/core/memory/scorer.ts";
 import { FIRING_DETAIL_MAX, isScheduleFiring, type ScheduleFiring } from "../../src/core/schedules.ts";
 import { REPO_SLUG } from "../../src/core/delivery.ts";
-import { isDeliverySnapshot, type DeliverySnapshot } from "../../src/core/deliverySnapshotStore.ts";
+import {
+  isDeliverySnapshot,
+  isDeliverySnapshotPatch,
+  type DeliverySnapshot,
+  type DeliverySnapshotPatch,
+} from "../../src/core/deliverySnapshotStore.ts";
 import {
   applyRetention,
   clampRetentionPolicy,
@@ -43,6 +48,16 @@ import {
   reclaimPhase,
   selectReclaim,
 } from "../../src/core/runLedger/decisions.ts";
+import {
+  IDEMPOTENCY_KEY_PATTERN,
+  INSTANCE_ID_PATTERN,
+  isCoordinatorInstance,
+  isCoordinatorUnit,
+  sendRunFinished,
+  type CoordinatorInstance,
+  type CoordinatorUnit,
+  type RunFinishedSend,
+} from "../../src/core/coordinator/contract.ts";
 import {
   GEN_PATTERN,
   type ClaimRequest,
@@ -131,6 +146,12 @@ export interface Env {
   RUN_TRANSCRIPTS: DurableObjectNamespace<RunTranscriptDO>;
   /** Delivery snapshots (delivery item 10): ONE DeliveryDO (named "delivery"), one snapshot per repository. */
   DELIVERY: DurableObjectNamespace<DeliveryDO>;
+  /** The ship coordinator Workflow in the bot's shim Worker (run-history item
+   *  47): where `RunHistoryDO.finish` sends `run finished:<runId>` for a record
+   *  carrying `parentInstanceId`. Optional: this Worker deploys without it (the
+   *  binding is a cross-script one, and the class must exist on the bot before
+   *  the state Worker may name it), and a finish then commits with no event. */
+  SHIP_COORDINATOR?: Workflow;
   MEMORY_TOKEN?: string;
 }
 
@@ -149,6 +170,8 @@ const SCHEDULES_OBJECT = "schedules";
 const MAX_LIMIT = 50;
 /** Candidates per write batch (the reflection pass emits ≤6). */
 const MAX_BATCH = 50;
+/** Unit rows one put may carry: a plan has tens of units, never hundreds. */
+const MAX_UNITS_PER_PUT = 200;
 const MAX_TEXT_CHARS = 4000;
 const MAX_KEYWORDS = 20;
 const MAX_KEYWORD_CHARS = 64;
@@ -713,11 +736,14 @@ function parseStored<T>(text: string, guard: (v: unknown) => v is T): T | null {
 
 // The delivery page's snapshot (docs/reference/specs/delivery.md item 10): the
 // merged pull requests' facts over the snapshot window, as GitHub gave them,
-// and when they were read. A busy repository's window is a few MB — the review
+// and when they were read. A busy repository's window is many MB — the review
 // bodies and every workflow run of every branch — so a snapshot is stored as
 // one row per pull request under a meta row, never as one JSON value (the
 // per-row limit is 2 MB). A put replaces the repository's snapshot whole, in
-// one transaction; a get reassembles it in pull request number order.
+// one transaction — the first read; a merge applies a refresh — the rows it
+// re-read replace theirs by number, the rows that aged out go, the meta is
+// replaced — so the hourly write is the change, not the window; a get
+// reassembles the snapshot in pull request number order.
 
 /** One pull request's facts may not exceed a fraction of the row limit; the fence names the pull request. */
 const MAX_PULL_REQUEST_FACTS_BYTES = 1024 * 1024;
@@ -766,6 +792,38 @@ export class DeliveryDO extends DurableObject<Env> {
     return prs.length;
   }
 
+  /** Apply a refresh to the repository's snapshot in one transaction; the rows now stored, or null
+   *  when the repository has no snapshot to merge into (a partial snapshot would claim a
+   *  completeness it lacks — the caller writes whole instead). */
+  async merge(patch: DeliverySnapshotPatch): Promise<number | null> {
+    const { upsert, drop, ...meta } = patch;
+    return this.ctx.storage.transactionSync(() => {
+      const stored = this.sql.exec(`SELECT 1 FROM snapshots WHERE repo = ?`, patch.repo).toArray().length > 0;
+      if (!stored) return null;
+      for (const pr of upsert) {
+        this.sql.exec(
+          `INSERT OR REPLACE INTO pull_requests (repo, number, facts) VALUES (?, ?, ?)`,
+          patch.repo,
+          pr.number,
+          JSON.stringify(pr),
+        );
+      }
+      for (const number of drop) {
+        this.sql.exec(`DELETE FROM pull_requests WHERE repo = ? AND number = ?`, patch.repo, number);
+      }
+      this.sql.exec(
+        `INSERT OR REPLACE INTO snapshots (repo, snapshot_at, meta) VALUES (?, ?, ?)`,
+        patch.repo,
+        patch.snapshotAt,
+        JSON.stringify(meta),
+      );
+      const count = this.sql
+        .exec<{ n: number }>(`SELECT COUNT(*) AS n FROM pull_requests WHERE repo = ?`, patch.repo)
+        .toArray()[0];
+      return count?.n ?? 0;
+    });
+  }
+
   /** The repository's snapshot, pull requests in number order; null when none was stored. */
   async get(repo: string): Promise<DeliverySnapshot | null> {
     const row = this.sql.exec<{ meta: string }>(`SELECT meta FROM snapshots WHERE repo = ?`, repo).toArray()[0];
@@ -778,7 +836,13 @@ export class DeliveryDO extends DurableObject<Env> {
   }
 }
 
-const DELIVERY_ROUTES = new Set(["/delivery/get", "/delivery/put"]);
+const DELIVERY_ROUTES = new Set(["/delivery/get", "/delivery/put", "/delivery/merge"]);
+
+/** The pull request whose facts exceed the row fence, if any — checked before the transaction. */
+function oversizedFacts(prs: readonly DeliverySnapshot["prs"][number][]): number | undefined {
+  const encoder = new TextEncoder();
+  return prs.find((pr) => encoder.encode(JSON.stringify(pr)).byteLength > MAX_PULL_REQUEST_FACTS_BYTES)?.number;
+}
 
 async function handleDelivery(pathname: string, body: unknown, env: Env): Promise<Response> {
   const b = (typeof body === "object" && body !== null ? body : {}) as Record<string, unknown>;
@@ -797,19 +861,38 @@ async function handleDelivery(pathname: string, body: unknown, env: Env): Promis
         { error: "snapshot must be a DeliverySnapshot (repo, snapshotAt, range, prs[], truncated, completeFrom)" },
         400,
       );
-    const encoder = new TextEncoder();
-    const oversized = b.snapshot.prs.find(
-      (pr) => encoder.encode(JSON.stringify(pr)).byteLength > MAX_PULL_REQUEST_FACTS_BYTES,
-    );
-    if (oversized)
+    const oversized = oversizedFacts(b.snapshot.prs);
+    if (oversized !== undefined)
       return json(
-        { error: `pull request ${oversized.number}'s facts must be at most ${MAX_PULL_REQUEST_FACTS_BYTES} bytes` },
+        { error: `pull request ${oversized}'s facts must be at most ${MAX_PULL_REQUEST_FACTS_BYTES} bytes` },
         413,
       );
     const prs = await dO.put(b.snapshot);
     console.log(`[delivery/put] ${b.snapshot.repo} <- ${prs} pull requests as of ${b.snapshot.snapshotAt}`);
     return json({ ok: true, prs });
   }
+  if (pathname === "/delivery/merge") {
+    if (!isDeliverySnapshotPatch(b.patch))
+      return json(
+        {
+          error:
+            "patch must be a DeliverySnapshotPatch (repo, snapshotAt, range, truncated, completeFrom, upsert[], drop[])",
+        },
+        400,
+      );
+    const oversized = oversizedFacts(b.patch.upsert);
+    if (oversized !== undefined)
+      return json(
+        { error: `pull request ${oversized}'s facts must be at most ${MAX_PULL_REQUEST_FACTS_BYTES} bytes` },
+        413,
+      );
+    const prs = await dO.merge(b.patch);
+    if (prs === null) return json({ error: `no snapshot for ${b.patch.repo} to merge into` }, 404);
+    console.log(
+      `[delivery/merge] ${b.patch.repo} <- ${b.patch.upsert.length} pull requests re-read, ${b.patch.drop.length} dropped, ${prs} stored as of ${b.patch.snapshotAt}`,
+    );
+    return json({ ok: true, prs });
+  }
   return json({ error: "not found" }, 404);
 }
 
@@ -1090,6 +1173,102 @@ export class RunHistoryDO extends DurableObject<Env> {
         PRIMARY KEY (run_id, kind)
       );
     `);
+    // The coordinator's parent records (run-history item 49): one row per
+    // instance, written by the bot at the instance's creation and read by the
+    // spawn route for the requester, channel and thread every child acts as.
+    this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS coordinator_instances (
+        instance_id TEXT PRIMARY KEY,
+        json TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      );
+    `);
+    // The units of the plan an instance runs (run-history item 50): one row per
+    // (instance, unit), replaced whole as the runner reaches the unit; the
+    // rowid keeps the order the rows were first written — the plan's.
+    this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS coordinator_units (
+        instance_id TEXT NOT NULL,
+        unit TEXT NOT NULL,
+        json TEXT NOT NULL,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (instance_id, unit)
+      );
+    `);
+  }
+
+  // ---- the coordinator's parent records (run-history item 49) -----------------
+
+  /** Idempotent for the same record; a different record under a taken id is refused. */
+  async putInstance(instance: CoordinatorInstance): Promise<{ ok: true } | { ok: false; reason: "exists" }> {
+    let out: { ok: true } | { ok: false; reason: "exists" } = { ok: true };
+    this.ctx.storage.transactionSync(() => {
+      const text = JSON.stringify(instance);
+      const existing = this.sql
+        .exec<{ json: string }>(`SELECT json FROM coordinator_instances WHERE instance_id = ?`, instance.id)
+        .toArray()[0];
+      if (existing) {
+        if (existing.json !== text) out = { ok: false, reason: "exists" };
+        return;
+      }
+      this.sql.exec(
+        `INSERT INTO coordinator_instances (instance_id, json, created_at) VALUES (?, ?, ?)`,
+        instance.id,
+        text,
+        instance.createdAt,
+      );
+    });
+    return out;
+  }
+
+  /** The record written over whatever the id holds and the id's unit rows
+   *  dropped, in one transaction — an attempt starting over: the leftover of one
+   *  whose Workflow instance was never created, once the shim said so. */
+  async replaceInstance(instance: CoordinatorInstance): Promise<{ ok: true }> {
+    this.ctx.storage.transactionSync(() => {
+      this.sql.exec(
+        `INSERT INTO coordinator_instances (instance_id, json, created_at) VALUES (?, ?, ?)
+         ON CONFLICT(instance_id) DO UPDATE SET json = excluded.json, created_at = excluded.created_at`,
+        instance.id,
+        JSON.stringify(instance),
+        instance.createdAt,
+      );
+      this.sql.exec(`DELETE FROM coordinator_units WHERE instance_id = ?`, instance.id);
+    });
+    return { ok: true };
+  }
+
+  async getInstance(id: string): Promise<CoordinatorInstance | null> {
+    const row = this.sql
+      .exec<{ json: string }>(`SELECT json FROM coordinator_instances WHERE instance_id = ?`, id)
+      .toArray()[0];
+    return row ? (JSON.parse(row.json) as CoordinatorInstance) : null;
+  }
+
+  // ---- the units of the plan an instance runs (run-history item 50) -----------
+
+  /** Each row replaced whole under its (instance, unit); a replace keeps the row's place. */
+  async putUnits(units: CoordinatorUnit[], now: number): Promise<{ ok: true }> {
+    this.ctx.storage.transactionSync(() => {
+      for (const u of units) {
+        this.sql.exec(
+          `INSERT INTO coordinator_units (instance_id, unit, json, updated_at) VALUES (?, ?, ?, ?)
+           ON CONFLICT(instance_id, unit) DO UPDATE SET json = excluded.json, updated_at = excluded.updated_at`,
+          u.instanceId,
+          u.unit,
+          JSON.stringify(u),
+          now,
+        );
+      }
+    });
+    return { ok: true };
+  }
+
+  async listUnits(instanceId: string): Promise<CoordinatorUnit[]> {
+    return this.sql
+      .exec<{ json: string }>(`SELECT json FROM coordinator_units WHERE instance_id = ? ORDER BY rowid`, instanceId)
+      .toArray()
+      .map((r) => JSON.parse(r.json) as CoordinatorUnit);
   }
 
   // ---- the live-run ledger (run-history items 28–34) --------------------------
@@ -1117,6 +1296,7 @@ export class RunHistoryDO extends DurableObject<Env> {
               agent: existing.meta.agent,
               startedAt: existing.startedAt,
               ownerGen: existing.ownerGen,
+              idempotencyKey: existing.meta.idempotencyKey,
             }
           : undefined,
         req,
@@ -1298,13 +1478,17 @@ export class RunHistoryDO extends DurableObject<Env> {
     return out;
   }
 
-  /** The finished record replaces the live rows in ONE transaction (item 33). Fenced. */
+  /** The finished record replaces the live rows in ONE transaction (item 33).
+   *  Fenced. Then, for a record carrying `parentInstanceId`, ONE `run
+   *  finished:<runId>` to that coordinator instance (item 47) — after the
+   *  commit, never inside it, and never able to undo it: a refused send (the
+   *  instance ended, no binding) is the answer's `event`, not an error. */
   async finish(
     runId: string,
     gen: string,
     record: RunRecord,
     proposal?: RunPolicyProposal,
-  ): Promise<FenceResult & { stored?: boolean }> {
+  ): Promise<FenceResult & { stored?: boolean; event?: RunFinishedSend["kind"] }> {
     let out: FenceResult & { stored?: boolean } = { ok: true };
     this.ctx.storage.transactionSync(() => {
       const fence = checkFence(this.liveRow(runId), gen);
@@ -1316,9 +1500,13 @@ export class RunHistoryDO extends DurableObject<Env> {
       this.deleteLiveRows([runId]);
       out = { ok: true, stored: put.stored };
     });
+    if (!out.ok) return out;
     if ((await this.ctx.storage.getAlarm()) === null)
       await this.ctx.storage.setAlarm(systemClock() + RUN_SWEEP_INTERVAL_MS);
-    return out;
+    const event = await sendRunFinished(this.env.SHIP_COORDINATOR, record);
+    if (event.kind === "failed")
+      console.warn(`[runs/finish] ${runId} → run finished not delivered to ${event.instance}: ${event.reason}`);
+    return { ...out, event: event.kind };
   }
 
   /** The live rows go with no record (item 42): a reserved run that never
@@ -2270,6 +2458,11 @@ export class RunTranscriptDO extends DurableObject<Env> {
 }
 
 const LEDGER_ROUTES = new Set([
+  "/runs/coordinator/put",
+  "/runs/coordinator/replace",
+  "/runs/coordinator/get",
+  "/runs/coordinator/units/put",
+  "/runs/coordinator/units/list",
   "/runs/claim",
   "/runs/heartbeat",
   "/runs/append",
@@ -2293,14 +2486,15 @@ const LEDGER_ROUTES = new Set([
 
 /** Routes whose bodies may carry a record, a transcript chunk, or an event batch. */
 const WIDE_BODY_ROUTES = new Set(["/runs/put", "/runs/finish", "/runs/append", "/runs/transcript/write"]);
-/** A delivery snapshot: every merged pull request's reviews and its branch's workflow runs over
- *  the window — a busy repository's runs to a few MB (measured: 291 pull requests, 2.1 MB). */
-const MAX_SNAPSHOT_BODY_BYTES = 8 * 1024 * 1024;
+/** A delivery snapshot written whole, or a refresh's patch: every merged pull request's reviews and
+ *  its branch's workflow runs — about 7 KB a pull request (measured: 291 pull requests, 2.1 MB), so
+ *  a first read at the listing cap is under 6 MB and a busy repository's whole window many MB. */
+const MAX_SNAPSHOT_BODY_BYTES = 16 * 1024 * 1024;
 
 /** The request body ceiling per route, decided after routing and before the parse. */
 function bodyFenceFor(pathname: string): number {
   if (WIDE_BODY_ROUTES.has(pathname)) return MAX_RUN_PUT_BODY_BYTES;
-  if (pathname === "/delivery/put") return MAX_SNAPSHOT_BODY_BYTES;
+  if (pathname === "/delivery/put" || pathname === "/delivery/merge") return MAX_SNAPSHOT_BODY_BYTES;
   return MAX_BODY_BYTES;
 }
 
@@ -2332,6 +2526,20 @@ function parseClaim(b: Record<string, unknown>): Validated<ClaimRequest> {
   if (typeof r.startedAt !== "number" || !Number.isFinite(r.startedAt))
     return invalid("run.startedAt must be a number");
   if (typeof r.meta !== "object" || r.meta === null) return invalid("run.meta must be an object");
+  // A coordinator's tag (run-history item 48) is stored at the claim and read
+  // by the finish's send and the refusal a second claim meets: shaped or
+  // refused, and both fields or neither — one alone is no tag.
+  const meta = r.meta as Record<string, unknown>;
+  if ((meta.parentInstanceId === undefined) !== (meta.idempotencyKey === undefined))
+    return invalid("run.meta.parentInstanceId and run.meta.idempotencyKey come together or not at all");
+  if (meta.parentInstanceId !== undefined) {
+    if (typeof meta.parentInstanceId !== "string" || !INSTANCE_ID_PATTERN.test(meta.parentInstanceId))
+      return invalid("run.meta.parentInstanceId must be a Workflow instance id");
+  }
+  if (meta.idempotencyKey !== undefined) {
+    if (typeof meta.idempotencyKey !== "string" || !IDEMPOTENCY_KEY_PATTERN.test(meta.idempotencyKey))
+      return invalid("run.meta.idempotencyKey must be <parentInstanceId>:<step>");
+  }
   if (typeof r.system !== "string") return invalid("run.system must be a string");
   if (!Array.isArray(r.tools)) return invalid("run.tools must be an array");
   if (r.card !== undefined && r.card !== null) {
@@ -2482,6 +2690,44 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
     return json(r);
   }
 
+  // The coordinator's parent records (run-history item 49): the record whole,
+  // validated by the shared contract; a read by instance id.
+  if (pathname === "/runs/coordinator/put") {
+    if (!isCoordinatorInstance(b.instance))
+      return json({ error: "instance must be a coordinator instance record" }, 400);
+    const r = await stub.putInstance(b.instance);
+    console.log(`[runs/coordinator/put] ${key.value} ${b.instance.id} → ${r.ok ? "stored" : r.reason}`);
+    return r.ok ? json(r) : json(r, 409);
+  }
+  if (pathname === "/runs/coordinator/replace") {
+    if (!isCoordinatorInstance(b.instance))
+      return json({ error: "instance must be a coordinator instance record" }, 400);
+    const r = await stub.replaceInstance(b.instance);
+    console.log(`[runs/coordinator/replace] ${key.value} ${b.instance.id} → replaced`);
+    return json(r);
+  }
+  if (pathname === "/runs/coordinator/get") {
+    if (typeof b.id !== "string" || !INSTANCE_ID_PATTERN.test(b.id))
+      return json({ error: "id must be a Workflow instance id" }, 400);
+    return json({ instance: await stub.getInstance(b.id) });
+  }
+  // The units of the plan an instance runs (run-history item 50): rows
+  // validated by the shared contract, each replaced whole; a list by instance.
+  if (pathname === "/runs/coordinator/units/put") {
+    if (!Array.isArray(b.units) || b.units.length === 0 || b.units.length > MAX_UNITS_PER_PUT)
+      return json({ error: `units must be a non-empty array of at most ${MAX_UNITS_PER_PUT} unit rows` }, 400);
+    if (!b.units.every(isCoordinatorUnit)) return json({ error: "every unit must be a coordinator unit row" }, 400);
+    const units = b.units as CoordinatorUnit[];
+    const r = await stub.putUnits(units, now);
+    console.log(`[runs/coordinator/units/put] ${key.value} ${units[0]!.instanceId} ${units.length} row(s)`);
+    return json(r);
+  }
+  if (pathname === "/runs/coordinator/units/list") {
+    if (typeof b.instanceId !== "string" || !INSTANCE_ID_PATTERN.test(b.instanceId))
+      return json({ error: "instanceId must be a Workflow instance id" }, 400);
+    return json({ units: await stub.listUnits(b.instanceId) });
+  }
+
   const runId = parseRunId(b.runId);
   if (!runId.ok) return json({ error: runId.error }, 400);
   if (pathname === "/runs/inbox") {
@@ -2545,7 +2791,9 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
     if (!parsed.ok) return json({ error: parsed.error }, 400);
     if (parsed.value.record.id !== runId.value) return json({ error: "record.id must equal runId" }, 400);
     const r = await stub.finish(runId.value, g.value, parsed.value.record, parsed.value.proposal);
-    console.log(`[runs/finish] ${key.value} ${runId.value} ok=${r.ok}${r.ok ? ` stored=${r.stored}` : ` ${r.reason}`}`);
+    console.log(
+      `[runs/finish] ${key.value} ${runId.value} ok=${r.ok}${r.ok ? ` stored=${r.stored} event=${r.event}` : ` ${r.reason}`}`,
+    );
     return r.ok ? json(r) : json(r, 409);
   }
   return json({ error: "not found" }, 404);

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

@@ -38,6 +38,21 @@
       { "name": "DELIVERY", "class_name": "DeliveryDO" }
     ]
   },
+  // The bot shim's ship coordinator Workflow, bound across scripts by the bot's
+  // script name (docs/reference/specs/run-history.md item 47): `RunHistoryDO.finish`
+  // sends it `run finished:<runId>` for a record carrying `parentInstanceId`.
+  // The name is the bot's own Workflow name (`<bot script>-ship-coordinator`,
+  // deploy/cloudflare/wrangler.template.jsonc). The class is deployed with the
+  // bot, which deploys after this Worker — so this binding lands one release
+  // after the class did, never in the same one.
+  "workflows": [
+    {
+      "name": "{{bot.script}}-ship-coordinator",
+      "binding": "SHIP_COORDINATOR",
+      "class_name": "ShipCoordinator",
+      "script_name": "{{bot.script}}"
+    }
+  ],
   // SQLite-backed DOs (durable across restarts — AGENTS.md invariant 6).
   "migrations": [
     { "tag": "v1", "new_sqlite_classes": ["MemoryDO"] },

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

@@ -1,6 +1,16 @@
 # Resident container image: the @cloudflare/sandbox base (Ubuntu 22.04; already
-# ships git, curl, jq, Node 24, npm, bun, cloudflared) plus GitHub tooling and
-# a pool of unprivileged users.
+# ships git, curl, jq, npm, bun, cloudflared and a Node 22 this image replaces
+# with Node 24 below) plus GitHub tooling and a pool of unprivileged users.
+
+# The Node this image ships (copied in below), at the exact tag every image in
+# this repository shares — its major is .nvmrc's, which is what CI runs and
+# the install script requires. `--platform`: the cloudflare/sandbox base below
+# publishes linux/amd64 only, so the stage the binary is copied from must be
+# amd64 too — a bare FROM on an arm64 host resolves it to arm64 and the copied
+# binary cannot run in the base (check:image on Apple silicon failed exactly
+# so). src/deploy/imageNode.test.ts holds the tag, its major and the platform.
+FROM --platform=linux/amd64 docker.io/library/node:24.21.0-slim AS node
+
 # The tag MUST match the @cloudflare/sandbox version in package.json exactly
 # (no 'latest' tag exists on the @next line) — bump both together.
 FROM docker.io/cloudflare/sandbox:0.13.0-next.751.1
@@ -32,7 +42,29 @@ ENV CI=1 \
     UV_THREADPOOL_SIZE=4 \
     NODE_OPTIONS=--max-old-space-size=1536
 
-# pnpm + yarn: the base ships Node 24 + npm + bun but neither pnpm nor yarn, so a
+# Node 24, not the base's. The 0.13.0-next base ships Node 22.23.2 like the
+# 0.12.9 one (copied from node:22-slim: the binary at /usr/local/bin/node, npm
+# and corepack under /usr/local/lib/node_modules, npm/npx symlinked into it),
+# while this repository builds and tests on Node 24 (.nvmrc, CI) and its
+# published CLI requires `>=24` — so a repository validated here read a
+# different `verify` than CI did. Node comes from the official image at an
+# exact tag, in the `node` stage above, the same way the sandbox image does it
+# (deploy/cloudflare-sandbox/Dockerfile): the base's npm tree removed first,
+# then the binary, npm's tree and the headers at the base's own paths, so its
+# npm/npx symlinks keep resolving; the container server is a bun-compiled
+# binary and does not run on this Node. The grep fails the BUILD if a bump
+# lands another version; src/deploy/imageNode.test.ts holds it equal to the
+# stage's tag. This layer sits before the package managers below so they are
+# installed by this Node's npm, into this tree.
+RUN rm -rf /usr/local/lib/node_modules /usr/local/include/node
+COPY --from=node /usr/local/bin/node /usr/local/bin/node
+COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
+COPY --from=node /usr/local/include/node /usr/local/include/node
+RUN node --version | grep -qx 'v24.21.0' \
+  && npm --version >/dev/null \
+  && npx --version >/dev/null
+
+# pnpm + yarn: the base ships npm + bun but neither pnpm nor yarn, so a
 # repo whose onboard table is detected as pnpm or yarn (resident-repos item 52 —
 # every manager `detectCommands` can emit must exist here, or the table fails
 # deterministically at provision) couldn't be provisioned (install → build).
@@ -74,6 +106,53 @@ RUN apt-get update \
   && rm -rf /var/lib/apt/lists/* \
   && command -v unsquashfs >/dev/null
 
+# The toolchain for what a run BUILDS and LOOKS AT — the same layer as the
+# sandbox image's (deploy/cloudflare-sandbox/Dockerfile);
+# src/deploy/imageToolchain.test.ts holds the two to one shape.
+#   - python3 + make + g++: node-gyp's needs. A cold `npm install` in a repo
+#     with a native module (node-pty) rebuilds it from source, and died on
+#     "no Python". Just the three — no build-essential, no recommends.
+#   - ffmpeg (Ubuntu's, with libx264): an agent pulls frames out of a video
+#     to look at it (`ffmpeg -i in.mp4 -vf fps=1 frame_%03d.png`) and encodes
+#     video from frames or a screen recording.
+#   - a headless Chromium through Playwright at an EXACT pin
+#     (src/deploy/imagePins.test.ts): screenshots, PDFs and `recordVideo`.
+#     Ubuntu 22.04's apt `chromium` is a snap stub that does not run in a
+#     container, so the browser is Playwright's own build — the headless shell
+#     only (`--only-shell`: there is no display), with the system libraries it
+#     needs (`--with-deps`) and the fonts pages render text with.
+#     PLAYWRIGHT_BROWSERS_PATH is set BEFORE the install so the browser lands
+#     under /opt, not root's home, and the tree is opened to every user
+#     (a+rX): every agent command here runs as an unprivileged workerN (the
+#     pool below), through `su` without `-`, which keeps this environment.
+#     NODE_PATH makes `require('playwright')` resolve from any working
+#     directory. Playwright launches Chromium with --no-sandbox
+#     (`chromiumSandbox: false`, its default) — what a process without user
+#     namespaces needs, root or not.
+# Every claim is PROVEN by the layer itself, so the BUILD fails, not a run:
+# the compilers answer --version, ffmpeg encodes a one-second testsrc clip to
+# h264 and decodes a non-empty frame back out of it, the playwright CLI is on
+# PATH at the pin, and a real headless screenshot of a page lands as a
+# non-empty png — here as root; again as worker1 once the pool exists, below.
+# The proof artefacts, the apt lists, apt's .deb archive (this base has no
+# docker-clean hook: 400 MB of archives stayed behind without the `clean`)
+# and npm's cache go in the same layer.
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/ms-playwright \
+    NODE_PATH=/usr/local/lib/node_modules
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends python3 make g++ ffmpeg fonts-liberation fonts-noto-color-emoji \
+  && npm install -g playwright@1.63.0 \
+  && playwright install --with-deps --only-shell chromium \
+  && chmod -R a+rX /opt/ms-playwright \
+  && apt-get clean && rm -rf /var/lib/apt/lists/* && npm cache clean --force \
+  && python3 --version && g++ --version && make --version \
+  && ffmpeg -version \
+  && ffmpeg -hide_banner -loglevel error -f lavfi -i testsrc=duration=1:size=320x240:rate=10 -c:v libx264 -pix_fmt yuv420p /tmp/proof.mp4 \
+  && ffmpeg -hide_banner -loglevel error -i /tmp/proof.mp4 -vf fps=1 /tmp/proof_%03d.png && test -s /tmp/proof_001.png \
+  && 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
+
 # Agent commands never run as root (repo code runs unprivileged, one user per
 # thread — docs/reference/specs/resident-repos.md). The SDK's exec has no user/uid option
 # (verified against 0.13.0-next.751.1), so the container server itself runs as
@@ -89,3 +168,10 @@ RUN set -eux; \
     for i in $(seq 1 17); do useradd -m -u "$((2000 + i))" -s /bin/bash "worker$i"; chmod 700 "/home/worker$i"; done; \
     if dpkg -s sudo >/dev/null 2>&1; then apt-get remove -y --purge sudo; fi; \
     passwd -l root
+
+# The browser proof once more, as worker1 — exactly how a thread's commands
+# run (`su -s /bin/bash workerN -c …`, root's environment kept). The layer
+# above proved it as root; this one proves an unprivileged user can read the
+# browser tree under /opt and launch it, so the BUILD fails if a chmod or the
+# path ever regresses, not a run.
+RUN su -s /bin/bash worker1 -c "playwright screenshot --viewport-size=640,480 'data:text/html,<h1>ok</h1>' /tmp/ok.png && test -s /tmp/ok.png && rm -f /tmp/ok.png"