@coreplane/switchboard 1.205.0 → 1.206.0

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

@@ -1,5 +1,17 @@
-# Sandbox container image: the @cloudflare/sandbox base plus git + gh, so the
-# coding/review agents work out of the box.
+# Sandbox container image: the @cloudflare/sandbox base plus git + gh, a Docker
+# engine, Node 24 with pnpm, and the toolchain a run builds and looks with
+# (compilers, ffmpeg, a headless Chromium), so the coding/review/explore
+# agents work out of the box.
+
+# 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) — bump both together.
 FROM docker.io/cloudflare/sandbox:0.12.9
@@ -41,14 +53,28 @@ RUN apt-get update \
 # execs the real client. src/deploy/sandboxDocker.test.ts holds its shape.
 COPY --chmod=0755 docker-wrapper.sh /usr/local/bin/docker
 
-# Node comes from the base: the published 0.12.9 image ships Node 22.23 (copied
-# from node:22-slim, with npm; no NodeSource deb), so the retarget-and-upgrade
-# layer the 0.3.x image needed is gone. This repo pins `engines: node
-# >=22` (undici@8 needs Node 22's `webidl.util.markAsUncloneable`), and a
-# review run that falls back off the resident onto a fresh sandbox must load
-# the full vitest suite; the assertion fails the build if a base bump ever
-# lands below 22. (The resident image gets Node 24 from its 0.13.0-next base.)
-RUN node --version | grep -Eq '^v(2[2-9]|[3-9][0-9])\.'
+# Node 24, not the base's. The published 0.12.9 base ships Node 22.23.2
+# (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`. A run that exercised the suite inside this image read a
+# different `verify` than CI did: `npm ci` warned on the CLI package's engines,
+# and tests that pass in CI failed here. So Node comes from the official image
+# at an exact tag, in the `node` stage above: the base's npm tree is removed
+# first (no file of npm 10 survives under npm 11), then the binary, npm's tree
+# and the headers (node-gyp compiles native addons against them without a
+# download) land at the base's own paths, so its npm/npx symlinks keep
+# resolving. The container server (/container-server/sandbox, a bun-compiled
+# binary) does not run on this Node, so only what a run's commands see moves.
+# The grep fails the BUILD, not a run, if a bump ever lands another version
+# here; src/deploy/imageNode.test.ts holds it equal to the stage's tag.
+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: the base image ships Node + npm (corepack is under
 # /usr/local/lib/node_modules but not on PATH) and not pnpm, so coding runs in pnpm repos hit
@@ -65,3 +91,48 @@ RUN node --version | grep -Eq '^v(2[2-9]|[3-9][0-9])\.'
 # `packageManager`, so this is the floor for repos that name none.
 RUN npm install -g pnpm@10.34.5 \
   && pnpm --version | grep -qx '10\.34\.5'
+
+# The toolchain for what a run BUILDS and LOOKS AT — the same layer as the
+# resident image's (deploy/cloudflare-resident/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 here
+#     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): the resident runs each agent command as an unprivileged
+#     workerN, and the two images share this layer. NODE_PATH makes
+#     `require('playwright')` resolve from any working directory. Playwright
+#     launches Chromium with --no-sandbox (`chromiumSandbox: false`, its
+#     default) — what a root process, or one without user namespaces, needs.
+# 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. 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

package/dist/assets/deploy/secrets.manifest.json

@@ -38,7 +38,7 @@
       "name": "SWITCHBOARD_INGRESS_TOKENS",
       "workers": ["bot"],
       "optional": true,
-      "note": "JSON bearer→identity map for POST /ingress and POST /mcp. Self-minted (openssl rand -hex 32 per entry). Optional: without it /ingress and /mcp are disabled and `deploy restart` has no bearer."
+      "note": "JSON bearer→identity map for POST /ingress and POST /mcp. Self-minted (openssl rand -hex 32 per entry). Optional: without it /ingress and /mcp are disabled and `deploy restart` has no bearer. The `cron` entry fires schedules; a `coordinator` entry (granted `coordinator:step`) is the ship coordinator's, rotated apart from cron."
     },
     {
       "name": "SANDBOX_TOKEN",

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.205.0",
+  "version": "1.206.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.205.0",
+      "version": "1.206.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -18999,7 +18999,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.205.0",
+      "version": "1.206.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.205.0",
+  "version": "1.206.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/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.205.0",
-  "commit": "1d5551c7f53bdda247088b7e68ad3130298ff22a",
-  "builtAt": "2026-09-12T03:07:44.096Z"
+  "version": "1.206.0",
+  "commit": "c46066984259fae88e1f242c39cc38c8affe0776",
+  "builtAt": "2026-09-12T15:07:26.252Z"
 }

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

@@ -46,8 +46,8 @@ export interface AgentDef {
   name: string;
   description: string;
   system: string;
-  /** key into TOOLSETS: "full" | "readonly" | "web" | "assistant" | "explore" | "none" */
-  toolset: "full" | "readonly" | "web" | "assistant" | "explore" | "none";
+  /** key into TOOLSETS: "full" | "readonly" | "web" | "assistant" | "explore" | "conductor" | "none" */
+  toolset: "full" | "readonly" | "web" | "assistant" | "explore" | "conductor" | "none";
   /** backstop only — the wall clock below is the real budget */
   maxTurns: number;
   maxTokens: number;
@@ -136,9 +136,19 @@ const UNIT_CONTRACT = `UNIT CONTRACT: when your first user turn carries a \`${CO
 // sandbox and resident children read the same rule.
 const UNIT_HANDOFF = `UNIT HANDOFF: when your first user turn carries a \`${CONTRACT_HEADING}\` block, call the submit_handoff tool once, after submit_pr_description and before your final message, with the typed handoff — deviations: where you departed from the unit as written (from, to, why); followUps: what you found and did not do, and where it belongs (what, where); unproven: which of the unit's test scenarios or criteria you could not prove, and why (criterion, why). Switchboard records it on the run and posts it to the unit's board issue, where a person decides each row's disposition; you never edit the plan's ledger yourself. An empty handoff is submitted as three empty lists, never skipped — a missing handoff reads as an unfinished run, not as nothing to say. Without a \`${CONTRACT_HEADING}\` block, do not call it.`;
 
+// What both execution images carry beyond git and the package managers
+// (docs/reference/specs/execution.md item 10), said in one sentence by every
+// prompt that describes a workspace — the model reaches only for what it has
+// been told is there. The cold sandbox adds a Docker engine; the resident has
+// yarn and bun and no engine (src/agents/registry.test.ts holds each prompt to
+// its image).
+const IMAGE_TOOLCHAIN = `Node 24 with npm and pnpm; python3, make and g++ (native modules build); ffmpeg (frames out of a video — \`ffmpeg -i in.mp4 -vf fps=1 f_%03d.png\` — and video out of frames or a recording); and a headless Chromium through Playwright — \`playwright screenshot <url> out.png\`, \`playwright pdf <url> out.pdf\`, or \`require('playwright')\` for a scripted page and \`recordVideo\``;
+const SANDBOX_TOOLCHAIN = `The sandbox image carries ${IMAGE_TOOLCHAIN}; and Docker (the engine starts on the first \`docker\` call).`;
+const RESIDENT_TOOLCHAIN = `The resident image carries ${IMAGE_TOOLCHAIN}; plus yarn and bun — and no Docker.`;
+
 const CODING_SYSTEM = `You are Switchboard's coding agent, operating from a Slack request.
 
-You work inside a dedicated workspace directory with bash, read_file, and write_file tools.
+You work inside a dedicated workspace directory with bash, read_file, and write_file tools. ${SANDBOX_TOOLCHAIN}
 Typical job: take a task, clone the relevant repository, implement the change, push a branch, and submit a typed PR description — Switchboard opens the pull request from it.
 
 SCOPE FIRST — a hard rule, at most 5 tool calls: identify the target repository and surface before doing anything else.
@@ -176,7 +186,7 @@ Your final message is posted to Slack — keep it readable, lead with the outcom
 // the resident image: git + node only), so this variant replaces it.
 export const CODING_SYSTEM_RESIDENT = `You are Switchboard's coding agent, operating from a Slack request.
 
-You work inside a resident repository environment: your workspace is a ready git worktree of the target repository, already checked out on this thread's bound branch, with dependencies installed and the build warm. Your bash, read_file, and write_file tools run inside that worktree.
+You work inside a resident repository environment: your workspace is a ready git worktree of the target repository, already checked out on this thread's bound branch, with dependencies installed and the build warm. Your bash, read_file, and write_file tools run inside that worktree. ${RESIDENT_TOOLCHAIN}
 
 THE WORKSPACE IS READY — do not clone repositories, do not install dependencies, do not discover or survey other repos. Start from the code in front of you. Orient with a few BATCHED commands (e.g. \`git branch --show-current && git status && ls\` plus the relevant files in one call), not file-by-file exploration.
 
@@ -242,7 +252,7 @@ const REVIEW_WHOLE_CHANGE = `   - READ THE WHOLE CHANGE: the REVIEW TARGET block
 
 const REVIEW_SYSTEM = `You are Switchboard's code review agent, operating from a Slack request.
 
-You have bash and read_file tools in a workspace directory. Do not modify code, commit, or push — you are read-only by convention. Do not run the project's tests or build either: CI runs them as the verify gate and reports on the PR, so running them here only duplicates that and slows the review. Your job is to read the code.
+You have bash and read_file tools in a workspace directory. ${SANDBOX_TOOLCHAIN} Do not modify code, commit, or push — you are read-only by convention. Do not run the project's tests or build either: CI runs them as the verify gate and reports on the PR, so running them here only duplicates that and slows the review. Your job is to read the code.
 
 Strategy — GATHER ONCE, THEN ANALYZE ONCE. Do not explore file-by-file; your context window is large enough to hold the entire change. Speed matters: a review should take minutes, not an hour.
 
@@ -272,7 +282,7 @@ Your final message is posted to Slack. Lead with a one-line verdict, then the fi
 // resident image has no `gh` CLI.
 export const REVIEW_SYSTEM_RESIDENT = `You are Switchboard's code review agent, operating from a Slack request.
 
-You have bash and read_file tools inside a resident repository environment: a ready git worktree of the target repository, already checked out on this thread's bound branch — the PR head named in the REVIEW TARGET block below — with dependencies installed. Do not modify code, commit, or push — you are read-only by convention. Do not run the project's tests or build either: CI runs them as the verify gate and reports on the PR, so running them here only duplicates that and slows the review. Your job is to read the code. THE WORKSPACE IS READY — do not clone repositories, do not install anything, do not survey other repos. The \`gh\` CLI is NOT installed here; use git directly (and the GitHub REST API via curl for PR metadata if you need it — it works unauthenticated for public repos).
+You have bash and read_file tools inside a resident repository environment: a ready git worktree of the target repository, already checked out on this thread's bound branch — the PR head named in the REVIEW TARGET block below — with dependencies installed. Do not modify code, commit, or push — you are read-only by convention. Do not run the project's tests or build either: CI runs them as the verify gate and reports on the PR, so running them here only duplicates that and slows the review. Your job is to read the code. THE WORKSPACE IS READY — do not clone repositories, do not install anything, do not survey other repos. The \`gh\` CLI is NOT installed here; use git directly (and the GitHub REST API via curl for PR metadata if you need it — it works unauthenticated for public repos). ${RESIDENT_TOOLCHAIN}
 
 Strategy — GATHER ONCE, THEN ANALYZE ONCE. Do not explore file-by-file; your context window is large enough to hold the entire change. Speed matters: a review should take minutes, not an hour.
 
@@ -341,7 +351,7 @@ You cannot run commands, clone repositories, edit code, or review pull requests,
 // preset, not a directive.
 const EXPLORE_SYSTEM = `You are Switchboard's explore agent: a long, read-only investigation of a repository, answering a request from Slack.
 
-You work in a fresh sandbox with a shell (bash), read_file, and a read-scoped GitHub credential: git and gh are authenticated for reads, so clone the target repository into your workspace first (\`gh repo clone <owner/name>\` or \`git clone\`; check out the ref the request names), install what you need and run whatever the investigation calls for — builds, test suites, benchmarks, \`act\` (Docker is available). You cannot push. Your other tools: \`web_search\` and \`web_fetch\` (sources and pages), the GitHub reads — \`github_repos\`, \`github_tree\` / \`github_file\` (browse and read our repos at any ref), \`github_search_code\`, \`github_issue_list\` / \`github_issue_get\` — and \`list_skills\` / \`use_skill\`.
+You work in a fresh sandbox with a shell (bash), read_file, and a read-scoped GitHub credential: git and gh are authenticated for reads, so clone the target repository into your workspace first (\`gh repo clone <owner/name>\` or \`git clone\`; check out the ref the request names), install what you need and run whatever the investigation calls for — builds, test suites, benchmarks, \`act\`. ${SANDBOX_TOOLCHAIN} You cannot push. Your other tools: \`web_search\` and \`web_fetch\` (sources and pages), the GitHub reads — \`github_repos\`, \`github_tree\` / \`github_file\` (browse and read our repos at any ref), \`github_search_code\`, \`github_issue_list\` / \`github_issue_get\` — and \`list_skills\` / \`use_skill\`.
 
 THE DELIVERABLE IS A CLAIM TABLE. Turn the request into the claims it makes or asks about — explicit ones ("the suite runs in 4 minutes") and the implicit ones a careful engineer would check — and verify each one by running it, not by reading about it. One row per claim: the claim, the exact command you ran to check it, the number or output it produced, and a verdict (holds / does not hold / could not check — and why). Numbers over adjectives: measure a duration, count the failures, quote the version. Say what you did not get to.
 
@@ -353,6 +363,32 @@ Maintain the user-facing status card with the update_status tool: post your plan
 
 Report outcomes faithfully: a check you could not run is "could not check", never a guess. Use Slack-friendly formatting (no markdown headers; *bold*, bullets, code blocks — render the claim table as aligned rows inside a code block). Your final message is posted to Slack: lead with the overall verdict in one line, then the claim table, then what a follow-up should do.`;
 
+// The conductor (docs/reference/specs/agent-conductor.md): a run that starts
+// other runs instead of doing the work — the spawn/await substrate's first
+// preset. A child is a `dispatch()` run as the requesting user, in a thread of
+// its own, under their permissions (docs/decisions/0002-dispatcher-is-the-only-orchestrator.md,
+// docs/decisions/0007-authorization-policy-table.md): the prompt says exactly
+// that, so the model never expects a child to see this thread or to hold more
+// than its requester does. Machine `none`, identity `none`: it holds no
+// workspace, no shell and no credential of its own; its reach is the three run
+// tools, the GitHub reads and URL reading. The prompt names the limits the
+// spawn stage enforces — one level of depth, the fan-out cap, the parent's
+// remaining clock — so a refusal is never a surprise, and the presets a child
+// can run, so the model picks from the real list.
+const CONDUCTOR_SYSTEM = `You are Switchboard's conductor: you coordinate other runs instead of doing the work yourself, answering a request from Slack.
+
+You have no workspace and no shell. Your tools: \`spawn_run\` (start a child run), \`send_to_run\` (steer a live child: your text reaches it as a follow-up at its next step), \`await_runs\` (wait for your children to end and get each end — its status and final reply — back as data), \`list_runs\` (the runs you may see — your own children by default), \`get_run_status\` (one run: whether it is running, what it is doing, and its final reply once it finished), the GitHub reads — \`github_repos\`, \`github_tree\` / \`github_file\` (browse and read our repositories), \`github_search_code\`, \`github_issue_list\` / \`github_issue_get\` — \`web_fetch\` (read a public URL), and \`update_status\`.
+
+WHAT A CHILD IS. A child is an ordinary Switchboard run started as the person who asked you — exactly the run they could start by hand with \`agent:<preset>\` — in a thread of its own in this channel, visible to everyone there, with its own status card and run page, and under their permissions: a preset they may not run, a repository they may not use, or a profile a boundary caps is refused in the child's thread, and the refusal comes back to you as the tool result naming the gate. Children cannot spawn children. You may have a few live at once (the deployment's \`spawn.maxChildren\`, three by default); a spawn past the cap is refused until one finishes. A child's wall clock is capped by what is left of yours.
+
+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).
+
+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.`;
+
 export const AGENTS: Record<string, AgentDef> = {
   general: {
     name: "general",
@@ -455,6 +491,21 @@ export const AGENTS: Record<string, AgentDef> = {
     cacheTtl: "1h",
     // No built-in effort: the deployment decides, as for coding.
   },
+  conductor: {
+    name: "conductor",
+    description:
+      "Coordinates other runs: spawns child runs as the requester — each in a thread of its own, under their permissions — follows them, and reports. No workspace or shell.",
+    system: CONDUCTOR_SYSTEM,
+    toolset: "conductor",
+    // Nothing is provisioned and no credential minted: the run tools call the
+    // dispatcher, the GitHub reads are REST in the bot process.
+    machine: "none",
+    identity: "none",
+    maxTurns: 40, // a spawn, then a poll per child every few minutes; the wall clock is the budget
+    maxTokens: 32000,
+    maxMinutes: 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.
+  },
 };
 
 export function getAgent(name: string): AgentDef {

package/dist/assets/src/config/profile.ts

@@ -8,15 +8,26 @@ import type { AgentDef, Identity, MachineClass } from "../agents/registry.js";
 
 export type { Identity, MachineClass };
 
-/** Where a cap on the profile came from — named on a clip and on a refusal. */
-export type BoundaryScope = "defaults" | "channel" | "user" | "directive";
-export const BOUNDARY_SCOPES: readonly BoundaryScope[] = ["defaults", "channel", "user", "directive"];
+/** Where a cap on the profile came from — named on a clip and on a refusal.
+ *  `parent` is the wall clock a spawning run had left when it started a child
+ *  (docs/reference/specs/routing-and-config.md item 20): a boundary on the
+ *  minutes axis alone, never on the identity or the class. */
+export type BoundaryScope = "defaults" | "channel" | "user" | "directive" | "parent";
+export const BOUNDARY_SCOPES: readonly BoundaryScope[] = ["defaults", "channel", "user", "directive", "parent"];
 
 /** The clip's source as the card and the config block name it: a scope's cap
  *  is `<scope> boundary`, the caller's own `budget:` directive is `budget
- *  directive` — one wording for every surface that says what clipped a run. */
+ *  directive`, a spawning run's remaining wall clock is `parent run's budget`
+ *  — one wording for every surface that says what clipped a run. */
 export function clipSourceLabel(scope: BoundaryScope): string {
-  return scope === "directive" ? "budget directive" : `${scope} boundary`;
+  switch (scope) {
+    case "directive":
+      return "budget directive";
+    case "parent":
+      return "parent run's budget";
+    default:
+      return `${scope} boundary`;
+  }
 }
 
 /** What one run may have: the three axes, and — when a boundary clipped the
@@ -129,6 +140,24 @@ export function intersectBoundaries(layers: readonly ScopedBoundary[]): Effectiv
   return out.maxMinutes || out.maxIdentity || out.machines ? out : undefined;
 }
 
+/**
+ * The boundaries on a child's path with its parent's remaining wall clock as
+ * one more layer (docs/reference/specs/routing-and-config.md item 20): the
+ * whole minutes the parent has left cap the child's minutes, attributed to
+ * `parent`, when that is tighter than every cap already on the path. The
+ * identity and the class are untouched — a parent hands a child time, never a
+ * credential or a machine. The same object comes back when the parent's clock
+ * is not the tightest cap, so a caller can tell "nothing changed" apart.
+ */
+export function boundedByParent(
+  boundary: EffectiveBoundary | undefined,
+  parentRemainingMs: number,
+): EffectiveBoundary | undefined {
+  const minutes = Math.floor(parentRemainingMs / 60_000);
+  if (boundary?.maxMinutes && boundary.maxMinutes.value <= minutes) return boundary;
+  return { ...boundary, maxMinutes: { value: minutes, scope: "parent" } };
+}
+
 /** Why a profile was refused: the axis, what the preset needs, what the
  *  boundary allows, and the scope(s) that set it — everything the refusal
  *  reply names. */

package/dist/assets/src/core/authz/policy.ts

@@ -175,6 +175,21 @@ export const POLICY: readonly Rule[] = [
   // ── schedules ────────────────────────────────────────────────────────────
   // Only the schedule shim's actor fires a schedule.
   { action: "schedule:fire", resource: "command", actorKinds: ["schedule"], when: [] },
+
+  // ── coordinator ──────────────────────────────────────────────────────────
+  // A coordinator step (`spawn`, `read-record`, `pr-check`, the instance
+  // creation): a machine identity holding the grant — the `coordinator`
+  // ingress bearer, granted `coordinator:step` by name — and never a person,
+  // an admin's `all` included: the steps are a program's, and the child a
+  // spawn starts is authorized as the requesting user the parent record
+  // names, not as whoever holds this grant.
+  { action: "coordinator:step", resource: "command", actorKinds: ["service"], when: [grant("coordinator:step")] },
+  // The plan runner's merge (docs/decisions/0031-the-coordinator-runs-a-plan-not-a-pull-request.md,
+  // "The merge grant"): its own action, held by the same bearer by name and by
+  // no person — what decides a merge is the branch (a plan branch the runner
+  // itself opened) and the guards, never the requester. Withdrawing the grant
+  // returns every merge to a person.
+  { action: "plan:merge", resource: "command", actorKinds: ["service"], when: [grant("plan:merge")] },
 ];
 
 export const ACTOR_KINDS: readonly ActorKind[] = ["user", "service", "schedule", "agent"];

package/dist/assets/src/core/coordinator/contract.ts

@@ -0,0 +1,239 @@
+// The ship coordinator's contract (docs/decisions/0029-durable-objects-store-workflows-schedule.md,
+// docs/decisions/0031-the-coordinator-runs-a-plan-not-a-pull-request.md;
+// docs/reference/specs/run-history.md items 47–48; docs/reference/specs/http-ingress.md
+// item 9): what the state Worker, the bot and the bot's shim Worker agree on
+// about a coordinator instance and its children. Node-free — imported by all
+// three by relative path, the way runRecord.ts is — so the shapes agree by
+// construction: the event a finished child sends, the key a spawn carries, the
+// parent record the spawn route reads the requester from, and the names the
+// routes decide on.
+//
+// A coordinator is a Workflow instance in the shim Worker whose children are
+// ordinary `dispatch()` runs as the requesting user. It holds no credential of
+// its own: every step is a call into the bot with the `coordinator` bearer,
+// whose actor holds `coordinator:step` — the one grant that admits the steps.
+
+/** The ingress subject the coordinator presents (`SWITCHBOARD_INGRESS_TOKENS`
+ *  entry `{ subject: "coordinator" }` → the actor `http:coordinator`). A name,
+ *  not authority: what admits a step is the grant below on that actor. */
+export const COORDINATOR_IDENTITY = "coordinator";
+/** The policy action every coordinator step is decided on (authorization.md item 2). */
+export const COORDINATOR_STEP_ACTION = "coordinator:step";
+/** The plan runner's merge, its own action on the same bearer (record 0031's merge grant): a
+ *  plan branch's pull request is merged by the runner only under it; withdrawn, every merge is a person's. */
+export const PLAN_MERGE_ACTION = "plan:merge";
+/** Where the bot answers the steps: `POST <prefix><step>` on the container, forwarded by the shim like every `/admin/*` path. */
+export const COORDINATOR_STEP_PATH_PREFIX = "/admin/coordinator/";
+
+/** A Workflow instance id: the platform's own alphabet, at most 100 characters. */
+export const INSTANCE_ID_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,99}$/;
+/** A step name: `<unit>/<round>/<kind>` and its kin — no colon, which separates it from the instance in the key. */
+export const STEP_NAME_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_./-]{0,119}$/;
+/** `<parentInstanceId>:<step>` — the idempotency key a spawn carries and the child's claim stores. */
+export const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,99}:[A-Za-z0-9_][A-Za-z0-9_./-]{0,119}$/;
+
+export function idempotencyKeyFor(parentInstanceId: string, step: string): string {
+  return `${parentInstanceId}:${step}`;
+}
+
+/** The event a child's terminal record sends its parent: the type carries the
+ *  run id, so each `waitForEvent` matches its own child and a duplicate is
+ *  buffered harmlessly. */
+export const RUN_FINISHED_EVENT_PREFIX = "run finished:";
+export function runFinishedEventType(runId: string): string {
+  return `${RUN_FINISHED_EVENT_PREFIX}${runId}`;
+}
+
+/** What the event carries — ids, a status and a clock; the parent confirms
+ *  through `read-record` before it acts, so nothing more rides here. */
+export interface RunFinishedPayload {
+  runId: string;
+  status: string;
+  finishedAt: number;
+  parentInstanceId: string;
+}
+
+/** What a coordinator's spawn stamps on the child's every row: the instance
+ *  the child belongs to and the key the spawn carried. */
+export interface CoordinatorTag {
+  parentInstanceId: string;
+  idempotencyKey: string;
+}
+
+/** The tag as the two flat record fields, or nothing — so a row, a summary
+ *  and a record spread the same thing and a run with no coordinator carries no key. */
+export function coordinatorFields(tag: CoordinatorTag | undefined): {
+  parentInstanceId?: string;
+  idempotencyKey?: string;
+} {
+  return tag ? { parentInstanceId: tag.parentInstanceId, idempotencyKey: tag.idempotencyKey } : {};
+}
+
+/** The parent ship record: what the bot writes at an instance's creation and
+ *  the spawn route reads the requester, channel and thread from — so a step
+ *  never takes an actor from its caller. Ids only, never the task text. The
+ *  units the instance runs are rows of their own (`CoordinatorUnit`), so this
+ *  row stays the instance's identity and its two surfaces: the card the bot
+ *  redraws and the run record it writes at the end. */
+export interface CoordinatorInstance {
+  id: string;
+  kind: "ship";
+  /** The requesting user (platform-namespaced), whose grants every child is authorized under. */
+  userId: string;
+  userName?: string;
+  channelId: string;
+  channelName?: string;
+  /** The requesting thread: where the card lives and where a task-string
+   *  instance's one unit runs; a plan's units each open a thread of their own. */
+  threadKey: string;
+  sourceUrl?: string;
+  /** `owner/name`, and the head branch the pipeline works on (a task string's
+   *  deterministic ship branch; for a plan, the first unit's — each unit row names its own). */
+  repo: string;
+  branch: string;
+  /** The pull request's base branch, when the creator knew it. */
+  base?: string;
+  /** Epoch ms. */
+  createdAt: number;
+  /** The plan the instance runs, when it runs one: its id (the file's name) and its path in the repository. */
+  plan?: { id: string; path: string };
+  /** The pipeline's caps as the profile gate clipped them: the rounds cap and the wall clock per unit. */
+  caps?: { maxRounds: number; maxMinutes: number };
+  /** The status card in the requesting thread, when the channel has one — what
+   *  the bot redraws from the coordinator's round events (`StatusHandle.handle`). */
+  card?: { channel: string; ts: string };
+  /** The run id the bot writes the parent's record under when the instance ends, and the card's label. */
+  runId?: string;
+  label?: string;
+  /** Which attempt of the plan this instance runs (a re-issue after an earlier
+   *  attempt ended reruns the units not merged under `plan-<plan-id>-<attempt>`);
+   *  absent for the first. */
+  attempt?: number;
+}
+
+/** One unit of the plan an instance runs (a task string is a plan of one unit,
+ *  `task`): its branch, the units it waits on, and — as the runner reaches it —
+ *  its thread, its pull request, the round boundaries the card drew and how it
+ *  ended. One row a person can read for "what happened to this unit". */
+export interface CoordinatorUnit {
+  instanceId: string;
+  /** `U<n>` as the plan spells it, or `task`. */
+  unit: string;
+  slug: string;
+  title?: string;
+  /** `plan/<plan-id>/<unit-slug>`, or the task string's ship branch. */
+  branch: string;
+  dependsOn: string[];
+  /** The unit's thread, once opened; a task's is the requesting thread from the start. */
+  threadKey?: string;
+  sourceUrl?: string;
+  /** The unit's board issue in the repository, when one titled by the unit id exists — the handoff's destination. */
+  issue?: number;
+  pr?: { number: number; url: string };
+  /** The round boundaries the coordinator reported, oldest first (the `ship_round` vocabulary). */
+  rounds: Array<{ index: number; agent: string; outcome: string; at: number }>;
+  /** How the unit ended: the ending's kind and the thread's report, when it has. */
+  ending?: { kind: string; report: string; at: number };
+  startedAt?: number;
+}
+
+const REPO_SLUG = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const MAX_TEXT = 512;
+/** A unit's report — the loop's words for how it ended, with a cap report's findings — is longer than a name. */
+const MAX_REPORT = 20_000;
+const MAX_ROUNDS = 200;
+
+const isText = (v: unknown, max = MAX_TEXT): v is string => typeof v === "string" && v.length > 0 && v.length <= max;
+const isOptionalText = (v: unknown): boolean => v === undefined || isText(v);
+const isFinite = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null;
+const isPr = (v: unknown): boolean => isObject(v) && isFinite(v.number) && isText(v.url, 2048);
+
+/** Structural check on a record from outside the process (a Worker response, an HTTP body). */
+export function isCoordinatorInstance(v: unknown): v is CoordinatorInstance {
+  if (!isObject(v)) return false;
+  const r = v;
+  if (typeof r.id !== "string" || !INSTANCE_ID_PATTERN.test(r.id)) return false;
+  if (r.kind !== "ship") return false;
+  if (!isText(r.userId) || !isText(r.channelId) || !isText(r.threadKey)) return false;
+  if (!isOptionalText(r.userName) || !isOptionalText(r.channelName) || !isOptionalText(r.sourceUrl)) return false;
+  if (typeof r.repo !== "string" || !REPO_SLUG.test(r.repo)) return false;
+  if (!isText(r.branch) || !isOptionalText(r.base)) return false;
+  if (!isFinite(r.createdAt)) return false;
+  if (r.plan !== undefined && !(isObject(r.plan) && isText(r.plan.id) && isText(r.plan.path, 1024))) return false;
+  if (r.caps !== undefined && !(isObject(r.caps) && isFinite(r.caps.maxRounds) && isFinite(r.caps.maxMinutes)))
+    return false;
+  if (r.card !== undefined && !(isObject(r.card) && isText(r.card.channel) && isText(r.card.ts))) return false;
+  if (!isOptionalText(r.runId) || !isOptionalText(r.label)) return false;
+  if (r.attempt !== undefined && !(Number.isInteger(r.attempt) && (r.attempt as number) >= 2)) return false;
+  return true;
+}
+
+/** Structural check on a unit row from outside the process. */
+export function isCoordinatorUnit(v: unknown): v is CoordinatorUnit {
+  if (!isObject(v)) return false;
+  const r = v;
+  if (typeof r.instanceId !== "string" || !INSTANCE_ID_PATTERN.test(r.instanceId)) return false;
+  if (!isText(r.unit, 32) || !isText(r.slug) || !isText(r.branch) || !isOptionalText(r.title)) return false;
+  if (!Array.isArray(r.dependsOn) || !r.dependsOn.every((d) => isText(d, 32))) return false;
+  if (!isOptionalText(r.threadKey) || !isOptionalText(r.sourceUrl)) return false;
+  if (r.issue !== undefined && !isFinite(r.issue)) return false;
+  if (r.pr !== undefined && !isPr(r.pr)) return false;
+  if (
+    !Array.isArray(r.rounds) ||
+    r.rounds.length > MAX_ROUNDS ||
+    !r.rounds.every((x) => isObject(x) && isFinite(x.index) && isText(x.agent) && isText(x.outcome) && isFinite(x.at))
+  )
+    return false;
+  if (
+    r.ending !== undefined &&
+    !(isObject(r.ending) && isText(r.ending.kind) && isText(r.ending.report, MAX_REPORT) && isFinite(r.ending.at))
+  )
+    return false;
+  if (r.startedAt !== undefined && !isFinite(r.startedAt)) return false;
+  return true;
+}
+
+/** The slice of a Workflow binding the send needs (`Workflow.get` →
+ *  `WorkflowInstance.sendEvent`), so the state Worker's handler is testable
+ *  with a double and the contract names no platform type. */
+export interface WorkflowInstanceSender {
+  sendEvent(event: { type: string; payload: unknown }): Promise<void>;
+}
+export interface WorkflowSender {
+  get(id: string): Promise<WorkflowInstanceSender>;
+}
+
+/** How a send ended. `none`: the record names no instance. `no-binding`: the
+ *  Worker has no coordinator binding. `failed`: the engine refused (the
+ *  instance ended, or is unknown) — swallowed, never thrown: the commit stands,
+ *  and the parent's `waitForEvent` timeout falls back to `read-record`. */
+export type RunFinishedSend =
+  | { kind: "sent"; instance: string; type: string }
+  | { kind: "none" }
+  | { kind: "no-binding"; instance: string }
+  | { kind: "failed"; instance: string; type: string; reason: string };
+
+/** The one send per committed terminal record (run-history item 47). */
+export async function sendRunFinished(
+  workflow: WorkflowSender | undefined,
+  record: { id: string; status: string; finishedAt: number; parentInstanceId?: string },
+): Promise<RunFinishedSend> {
+  const instance = record.parentInstanceId;
+  if (instance === undefined) return { kind: "none" };
+  if (!workflow) return { kind: "no-binding", instance };
+  const type = runFinishedEventType(record.id);
+  const payload: RunFinishedPayload = {
+    runId: record.id,
+    status: record.status,
+    finishedAt: record.finishedAt,
+    parentInstanceId: instance,
+  };
+  try {
+    const handle = await workflow.get(instance);
+    await handle.sendEvent({ type, payload });
+    return { kind: "sent", instance, type };
+  } catch (err) {
+    return { kind: "failed", instance, type, reason: err instanceof Error ? err.message : String(err) };
+  }
+}