@coreplane/switchboard 1.213.0 → 1.214.0

package/dist/assets/config/config.example.yaml

@@ -341,10 +341,14 @@ workspaceDir: ./workspaces
 # preset, the card saying why (`routed: <reason>`) and how to run it another way.
 # `ship` is never routed. The one way off, so every plain message runs
 # `defaults.agent` as before the router: `auto: false`. `model` is the router's
-# model; default `defaults.models.general`.
+# model; default `defaults.models.general`. `answer` is how that model answers:
+# `tool` (default) forces a call to the router's `route` tool, whose schema is
+# the answer, so prose cannot occur; `text` is the one-JSON-object text contract
+# alone — set it for a provider or model that cannot take a forced tool call.
 # routing:
 #   auto: false
 #   model: anthropic/claude-haiku-4-5
+#   answer: text
 
 # Spend reporting: GET /costs (Access-gated). Optional. See docs/reference/specs/costs.md.
 # costs:

package/dist/assets/deploy/cloudflare/artifactsCopy.ts

@@ -0,0 +1,180 @@
+// The artifact copy route (docs/reference/specs/execution.md item 20, record
+// 0033): `POST /artifacts/copy { url, size, key }` streams a Slack file into
+// the artifacts bucket without the bot's container ever holding the bytes.
+// The bot asks (`R2ArtifactStore.copyFromUrl`, bearer ARTIFACTS_COPY_TOKEN);
+// this Worker holds the two things the copy needs — the R2 binding and the
+// Slack bot token that `url_private` requires — and answers `{ key, size }`
+// only once the bucket holds exactly `size` bytes under `key`.
+//
+// Pure over its deps so it is tested in plain Node (this directory's tests
+// run no workerd): the bucket, the upstream fetch, the length pipe (workerd's
+// `FixedLengthStream`, which refuses a body of another length) and the tokens
+// are handed in; `worker.ts` binds them from `env`.
+
+/** What the route needs from the bucket: R2's `put` with a stream and the object's type. */
+export interface CopyBucket {
+  put(
+    key: string,
+    value: ReadableStream<Uint8Array>,
+    options?: { httpMetadata?: { contentType?: string } },
+  ): Promise<unknown>;
+}
+
+export interface CopyDeps {
+  /** The `ARTIFACTS` R2 binding; absent when the deployment configures no bucket. */
+  bucket: CopyBucket | undefined;
+  /** The bucket's name as the Worker was deployed with (`ARTIFACTS_BUCKET_NAME`), for `GET`. */
+  bucketName: string | undefined;
+  /** The bearer the bot presents (`ARTIFACTS_COPY_TOKEN`). */
+  copyToken: string | undefined;
+  /** The Slack bot token `url_private` requires. Read from the Worker's env, never from the request. */
+  slackToken: string | undefined;
+  fetch: typeof fetch;
+  /** A pipe that carries exactly `size` bytes and fails on any other count:
+   *  `new FixedLengthStream(size)` in workerd, whose reader R2 accepts as a
+   *  stream of known length; a `TransformStream` in tests. */
+  lengthPipe: (size: number) => { readable: ReadableStream<Uint8Array>; writable: WritableStream<Uint8Array> };
+  /** The largest copy accepted; default `MAX_COPY_BYTES`. */
+  maxBytes?: number;
+}
+
+export const COPY_PATH = "/artifacts/copy";
+
+/** Slack's own per-file ceiling; a larger declared size is refused before any fetch. */
+export const MAX_COPY_BYTES = 1_073_741_824;
+
+/** The hosts a `url_private` may name: Slack's file host and the workspace's own. */
+export function slackFileHost(hostname: string): boolean {
+  return hostname === "files.slack.com" || hostname === "slack.com" || hostname.endsWith(".slack.com");
+}
+
+/** Inbound keys as `inboundKey` (src/artifacts/keys.ts) builds them and nothing
+ *  else: under `threads/`, one character class, no empty or dot segments. */
+const KEY_RE = /^threads\/[A-Za-z0-9._-]+\/in\/[A-Za-z0-9._-]+\/\d+-[A-Za-z0-9._-]+$/;
+export function validCopyKey(key: string): boolean {
+  return KEY_RE.test(key) && !key.split("/").some((s) => s === "" || /^\.+$/.test(s));
+}
+
+/** Constant-time equality over the two strings' UTF-8 bytes (a length difference is a mismatch). */
+export function sameToken(a: string, b: string): boolean {
+  const x = new TextEncoder().encode(a);
+  const y = new TextEncoder().encode(b);
+  let diff = x.length ^ y.length;
+  for (let i = 0; i < Math.max(x.length, y.length); i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
+  return diff === 0;
+}
+
+export type CopyRequest = { url: URL; size: number; key: string };
+
+/** Pure: the body parsed and checked, or the 4xx that refuses it — before any fetch. */
+export function parseCopyRequest(
+  raw: string,
+  maxBytes: number,
+): { ok: true; value: CopyRequest } | { ok: false; status: 400 | 413; reason: string } {
+  let body: unknown;
+  try {
+    body = JSON.parse(raw);
+  } catch {
+    return { ok: false, status: 400, reason: "body is not JSON" };
+  }
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    return { ok: false, status: 400, reason: "body is not an object" };
+  }
+  const { url, size, key } = body as Record<string, unknown>;
+  if (typeof url !== "string") return { ok: false, status: 400, reason: "url must be a string" };
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { ok: false, status: 400, reason: "url is not a URL" };
+  }
+  if (parsed.protocol !== "https:" || !slackFileHost(parsed.hostname)) {
+    return { ok: false, status: 400, reason: `url host ${parsed.hostname} is not a Slack file host` };
+  }
+  if (typeof size !== "number" || !Number.isInteger(size) || size < 1) {
+    return { ok: false, status: 400, reason: "size must be a positive integer" };
+  }
+  if (size > maxBytes) return { ok: false, status: 413, reason: `size ${size} is over the ${maxBytes}-byte ceiling` };
+  if (typeof key !== "string" || !validCopyKey(key)) {
+    return { ok: false, status: 400, reason: "key is not an inbound artifact key" };
+  }
+  return { ok: true, value: { url: parsed, size, key } };
+}
+
+const json = (status: number, body: Record<string, unknown>) =>
+  new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+
+/** The route. WHO: the copy bearer, checked in constant time before anything
+ *  else (401, and never the bucket's existence). WHAT: a Slack `url_private`,
+ *  a positive size within the ceiling and an inbound key (400/413, before any
+ *  fetch). THEN the upstream: Slack answers the login page (`text/html`) when
+ *  the token does not reach the file — refused as unauthorized, nothing put;
+ *  a status other than 200 is Slack's word (502); a `Content-Length` absent or
+ *  other than `size` is a 409 before any `put`. The body flows through the
+ *  length pipe into one `put` with Slack's content type; a stream that ends
+ *  short fails the pipe, the put rejects and the bucket keeps nothing (502). */
+export async function handleArtifactsCopy(request: Request, deps: CopyDeps): Promise<Response> {
+  const bearer = /^Bearer\s+(\S+)$/.exec(request.headers.get("authorization") ?? "")?.[1];
+  if (!deps.copyToken || !bearer || !sameToken(bearer, deps.copyToken)) {
+    return json(401, { ok: false, error: "artifacts copy: bearer refused" });
+  }
+  if (request.method === "GET") {
+    return deps.bucket && deps.bucketName
+      ? json(200, { ok: true, bucket: deps.bucketName })
+      : json(503, { ok: false, error: "artifacts copy: this Worker has no ARTIFACTS bucket binding" });
+  }
+  if (request.method !== "POST") return json(405, { ok: false, error: `method not allowed: POST ${COPY_PATH}` });
+  if (!deps.bucket)
+    return json(503, { ok: false, error: "artifacts copy: this Worker has no ARTIFACTS bucket binding" });
+  if (!deps.slackToken)
+    return json(503, { ok: false, error: "artifacts copy: SLACK_BOT_TOKEN is not set on this Worker" });
+  const parsed = parseCopyRequest(await request.text().catch(() => ""), deps.maxBytes ?? MAX_COPY_BYTES);
+  if (!parsed.ok) return json(parsed.status, { ok: false, error: `artifacts copy: ${parsed.reason}` });
+  const { url, size, key } = parsed.value;
+
+  let upstream: Response;
+  try {
+    upstream = await deps.fetch(url.toString(), {
+      headers: { authorization: `Bearer ${deps.slackToken}` },
+      redirect: "manual",
+    });
+  } catch (err) {
+    return json(502, { ok: false, error: `artifacts copy: slack did not answer: ${describe(err)}` });
+  }
+  const contentType = upstream.headers.get("content-type") ?? "application/octet-stream";
+  if (upstream.status === 200 && /^text\/html\b/i.test(contentType)) {
+    await upstream.body?.cancel().catch(() => {});
+    return json(502, {
+      ok: false,
+      error: "artifacts copy: slack answered its login page — the bot token is not authorized for this file",
+    });
+  }
+  if (upstream.status !== 200 || !upstream.body) {
+    await upstream.body?.cancel().catch(() => {});
+    return json(502, { ok: false, error: `artifacts copy: slack answered HTTP ${upstream.status}` });
+  }
+  const declared = Number(upstream.headers.get("content-length"));
+  if (!upstream.headers.has("content-length") || !Number.isInteger(declared)) {
+    await upstream.body.cancel().catch(() => {});
+    return json(409, { ok: false, error: "artifacts copy: slack stated no length for the file" });
+  }
+  if (declared !== size) {
+    await upstream.body.cancel().catch(() => {});
+    return json(409, { ok: false, error: `artifacts copy: slack states ${declared} bytes, not the ${size} declared` });
+  }
+
+  // The bytes: upstream → the fixed-length pipe → one put. Either side failing
+  // rejects the whole copy; R2 keeps nothing for a stream that did not complete.
+  const { readable, writable } = deps.lengthPipe(size);
+  try {
+    await Promise.all([
+      upstream.body.pipeTo(writable),
+      deps.bucket.put(key, readable, { httpMetadata: { contentType } }),
+    ]);
+  } catch (err) {
+    return json(502, { ok: false, error: `artifacts copy: the copy of ${key} failed mid-stream: ${describe(err)}` });
+  }
+  return json(200, { ok: true, key, size });
+}
+
+const describe = (err: unknown): string => (err instanceof Error ? err.message : String(err));

package/dist/assets/deploy/cloudflare/ensure-bucket.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Create the R2 buckets this Worker's wrangler.jsonc binds, before `wrangler
+// deploy` validates the bindings (docs/reference/specs/execution.md item 20,
+// record 0033). wrangler refuses a deploy whose `r2_buckets` names a bucket
+// that does not exist, and creating one by hand is the step an installation
+// forgets; `npm run deploy` runs this after the preflight. Idempotent: a bucket
+// that already exists is success (wrangler's own words for it are matched),
+// any other refusal is wrangler's, verbatim, and the deploy stops.
+//
+// Dependency-free Node. `bucketNamesOf()` and `decide()` are pure and
+// unit-tested (ensure-bucket.test.mjs); `main()` only does I/O around them.
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/** Every `bucket_name` the rendered config binds — the template renders the
+ *  block only when the deployment profile names a bucket, so an installation
+ *  without artifacts has none here and this script does nothing. */
+export function bucketNamesOf(wranglerJsonc) {
+  const names = [];
+  for (const m of wranglerJsonc.matchAll(/"bucket_name"\s*:\s*"([^"]+)"/g)) names.push(m[1]);
+  return [...new Set(names)];
+}
+
+/** Pure: what `wrangler r2 bucket create <name>` meant. Exit 0 → created; a
+ *  non-zero exit whose output says the bucket exists → already there (success);
+ *  anything else → wrangler's refusal, to print and stop on. */
+export function decide(name, code, output) {
+  if (code === 0) return { ok: true, kind: "created", name };
+  if (/already exists|10004/i.test(output)) return { ok: true, kind: "exists", name };
+  return { ok: false, name, reason: output.trim() || `wrangler exited ${code}` };
+}
+
+function wrangler(args, cwd) {
+  return new Promise((resolve) => {
+    execFile("npx", ["wrangler", ...args], { cwd, env: process.env, maxBuffer: 4 << 20 }, (err, stdout, stderr) => {
+      const code = err && typeof err.code === "number" ? err.code : err ? 1 : 0;
+      resolve({ code, output: `${stdout ?? ""}\n${stderr ?? ""}` });
+    });
+  });
+}
+
+export async function main(dir = dirname(fileURLToPath(import.meta.url))) {
+  let rendered;
+  try {
+    rendered = readFileSync(join(dir, "wrangler.jsonc"), "utf8");
+  } catch {
+    console.error("[ensure-bucket] wrangler.jsonc is not rendered — run `npm run deploy:gen` first");
+    return 2;
+  }
+  const names = bucketNamesOf(rendered);
+  if (names.length === 0) {
+    console.log("[ensure-bucket] no R2 buckets bound — nothing to create");
+    return 0;
+  }
+  for (const name of names) {
+    const r = await wrangler(["r2", "bucket", "create", name], dir);
+    const d = decide(name, r.code, r.output);
+    if (!d.ok) {
+      console.error(`[ensure-bucket] could not create bucket ${name}:\n${d.reason}`);
+      return 1;
+    }
+    console.log(`[ensure-bucket] bucket ${name} ${d.kind === "created" ? "created" : "already exists"}`);
+  }
+  return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await main();
+}

package/dist/assets/deploy/cloudflare/package.json

@@ -7,7 +7,7 @@
   },
   "scripts": {
     "check:image": "docker build ../..",
-    "deploy": "node preflight.mjs && node write-build.mjs && wrangler deploy",
+    "deploy": "node preflight.mjs && node ensure-bucket.mjs && node write-build.mjs && wrangler deploy",
     "preflight": "node preflight.mjs",
     "test": "vitest run",
     "verify": "npm --prefix ../.. run --silent deploy:gen && npm run typecheck && npm test",

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

@@ -46,6 +46,7 @@ import {
 import { systemClock } from "../../src/core/trace/clock.ts";
 import { createTracer } from "../../src/core/trace/tracer.ts";
 import { shimRoute, stripTraceContext, withTraceContext, workerLogSink } from "../../src/core/trace/workerTrace.ts";
+import { COPY_PATH, handleArtifactsCopy } from "./artifactsCopy.ts";
 import type { ShipCoordinatorParams } from "./coordinator";
 import { INSTANCE, INTERNAL } from "./shared";
 
@@ -93,6 +94,12 @@ export interface Env {
   ARTIFACTS_R2_ACCESS_KEY_ID?: string; // artifact store: the bucket-scoped S3 token the bot signs presigned URLs with
   ARTIFACTS_R2_SECRET_ACCESS_KEY?: string; // artifact store: the secret half of that token
   ARTIFACTS_COPY_TOKEN?: string; // artifact store: the bearer the bot presents to this Worker's /artifacts/copy route
+  /** The artifacts bucket (artifactsCopy.ts), bound only when the deployment profile names one
+   *  (`artifacts.bucket` → the template's `r2_buckets` block); `ARTIFACTS_BUCKET_NAME` is the same
+   *  name as a var, what `GET /artifacts/copy` reports so `artifacts check` can hold it against the
+   *  bot's config. Worker-side only: neither reaches the container. */
+  ARTIFACTS?: R2Bucket;
+  ARTIFACTS_BUCKET_NAME?: string;
 }
 
 /** Every secret/var the Worker forwards into the container. Optional entries
@@ -429,7 +436,18 @@ export default {
             ? await handleCoordinatorInstances(forwarded, env)
             : statusId !== undefined
               ? await handleCoordinatorInstanceStatus(forwarded, env, statusId)
-              : await getContainer(env.SWITCHBOARD, INSTANCE).fetch(forwarded);
+              : pathname === COPY_PATH
+                ? // The artifact copy (artifactsCopy.ts): the R2 binding and the Slack
+                  // token are this Worker's; the bot only asks, with its copy bearer.
+                  await handleArtifactsCopy(inbound, {
+                    bucket: env.ARTIFACTS,
+                    bucketName: env.ARTIFACTS_BUCKET_NAME,
+                    copyToken: env.ARTIFACTS_COPY_TOKEN,
+                    slackToken: env.SLACK_BOT_TOKEN,
+                    fetch: (input, init) => fetch(input, init),
+                    lengthPipe: (size) => new FixedLengthStream(size),
+                  })
+                : await getContainer(env.SWITCHBOARD, INSTANCE).fetch(forwarded);
       root.end(res.status >= 500 ? "error" : "ok", { httpStatus: res.status });
       return res;
     } catch (err) {

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

@@ -34,6 +34,10 @@
     // The state Worker (deploy/cloudflare-memory/): where worker.ts records each
     // scheduled firing for the /runs Scheduled panel, with MEMORY_TOKEN.
     // A profile without a memory Worker renders no var: firings go unrecorded.
+    // The artifacts bucket's name, beside its binding below (rendered together).
+    // {{#if artifacts}}
+    "ARTIFACTS_BUCKET_NAME": "{{artifacts.bucket}}",
+    // {{/if}}
     // {{#if urls.stateWorkerUrl}}
     "STATE_WORKER_URL": "{{urls.stateWorkerUrl}}"
     // {{/if}}
@@ -54,6 +58,17 @@
   "durable_objects": {
     "bindings": [{ "name": "SWITCHBOARD", "class_name": "SwitchboardServer" }]
   },
+  // The artifacts bucket (docs/reference/specs/execution.md item 20, record
+  // 0033): where a run's files live by reference. Rendered only when the
+  // deployment profile names a bucket (`artifacts.bucket`) — the bot's
+  // config `artifacts.r2.bucket` must say the same name, and `artifacts
+  // check` holds the two against each other through `GET /artifacts/copy`.
+  // `npm run deploy` creates the bucket first (ensure-bucket.mjs); wrangler
+  // validates the binding on deploy. `ARTIFACTS_BUCKET_NAME` above is the
+  // same name as a var, so the Worker can say which bucket it binds.
+  // {{#if artifacts}}
+  "r2_buckets": [{ "binding": "ARTIFACTS", "bucket_name": "{{artifacts.bucket}}" }],
+  // {{/if}}
   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["SwitchboardServer"] }],
   // The ship coordinator as a Workflow (coordinator.ts, re-exported by
   // worker.ts; docs/reference/specs/http-ingress.md item 9): `POST

package/dist/assets/deploy/profile.example.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "The deployment profile: where THIS installation runs. Copy to deploy/profile.json and fill it in (or run `switchboard deploy init`). The account is your Cloudflare account id; every hostname must be under `zone`, a zone in that account, unless the Worker names its own `zone` (also in the account); `workers.bot` is the one required Worker — leave `memory`, `resident` or `sandbox` out and `deploy plan` has no step for them (a bot-only profile is a one-step plan; without `memory` the config is not pushed anywhere). The project's docs site is not a Worker of an installation: it is the project's website, deployed by the project's own CI from project.json, so there is no `docs` entry. `configSource` is where `deploy all` reads the bot's runtime config from before building the image — a path, `github://owner/repo/path@ref` (needs CONFIG_REPO_TOKEN), or `op://Vault/Item/field` (needs OP_SERVICE_ACCOUNT_TOKEN); `secretsSource` is where `secrets put` reads values from — a directory of <NAME> files (the default when absent) or `op://Vault/Item`. `images` is where the bot, resident and sandbox container images come from: `registry` — the release's published images, copied once per version into your account registry by `deploy all` itself (or `deploy images` ahead of it) over HTTPS and referenced from there — no Docker anywhere, a Cloudflare API token with Containers Edit in CLOUDFLARE_API_TOKEN for the copy (an installation deploying published images; what `init` writes from the published package); or `build` (the default when absent) — each Worker's Dockerfile, built by wrangler where `deploy all` runs (a checkout; the project's own production). `deploy plan` reads this example when no profile exists; `deploy all` refuses it.",
+  "$comment": "The deployment profile: where THIS installation runs. Copy to deploy/profile.json and fill it in (or run `switchboard deploy init`). The account is your Cloudflare account id; every hostname must be under `zone`, a zone in that account, unless the Worker names its own `zone` (also in the account); `workers.bot` is the one required Worker — leave `memory`, `resident` or `sandbox` out and `deploy plan` has no step for them (a bot-only profile is a one-step plan; without `memory` the config is not pushed anywhere). The project's docs site is not a Worker of an installation: it is the project's website, deployed by the project's own CI from project.json, so there is no `docs` entry. `configSource` is where `deploy all` reads the bot's runtime config from before building the image — a path, `github://owner/repo/path@ref` (needs CONFIG_REPO_TOKEN), or `op://Vault/Item/field` (needs OP_SERVICE_ACCOUNT_TOKEN); `secretsSource` is where `secrets put` reads values from — a directory of <NAME> files (the default when absent) or `op://Vault/Item`. `images` is where the bot, resident and sandbox container images come from: `registry` — the release's published images, copied once per version into your account registry by `deploy all` itself (or `deploy images` ahead of it) over HTTPS and referenced from there — no Docker anywhere, a Cloudflare API token with Containers Edit in CLOUDFLARE_API_TOKEN for the copy (an installation deploying published images; what `init` writes from the published package); or `build` (the default when absent) — each Worker's Dockerfile, built by wrangler where `deploy all` runs (a checkout; the project's own production). `artifacts` (optional) names the R2 bucket a run's files move through (docs/reference/specs/execution.md item 20): with it the bot Worker binds the bucket and `deploy` creates it before the upload (the credential then needs Workers R2 Storage: Edit); the bot's runtime config `artifacts.r2.bucket` must say the same name. `deploy plan` reads this example when no profile exists; `deploy all` refuses it.",
   "account": "00000000000000000000000000000000",
   "zone": "example.com",
   "workers": {

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.213.0",
+  "version": "1.214.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.213.0",
+      "version": "1.214.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -19000,7 +19000,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.213.0",
+      "version": "1.214.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.213.0",
+  "version": "1.214.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.213.0",
-  "commit": "e6d1e5ef45c220f43d4a956547c3f55458fbf3ab",
-  "builtAt": "2026-09-14T17:32:11.100Z"
+  "version": "1.214.0",
+  "commit": "5f594682c5b0a24cb11929a33cd6ef28a085634c",
+  "builtAt": "2026-09-14T19:50:00.483Z"
 }

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

@@ -198,6 +198,8 @@ const RESIDENT_TOOLCHAIN = `The resident image carries ${IMAGE_TOOLCHAIN}; plus
 // the sandbox and resident variants cannot drift on it.
 const SHOW_FILES = `Files the person should SEE go through the attach_file tool: a screenshot from \`playwright screenshot\`, a rendered PDF, a recording — it posts the workspace file into this conversation, where an image renders inline. Use it whenever you produce an image worth showing (a visual change, a rendered page, a before/after); a link to a file on GitHub is not a picture.
 SCREENSHOTS GO TO BOTH PLACES, ALL OF THEM: when the request asks for screenshots, or the change is visual, every capture is attached here with attach_file AND published on the pull request — commit the images to an assets branch (never the PR's own diff) and reference them from the description's validation section or a PR comment so they render inline there too — unless the request names one destination. Never attach a subset and link the rest.
+Whole files: up to 1 GiB where the artifact store is configured (a recording, a large PDF), 10 MiB otherwise — the tool's result says which applies; over the limit, link to the file.
+Files the person dropped on the thread that were too large to show you inline are already in ./attachments/ in your workspace when the turn's text names them (a video for ffmpeg, a large PDF, a zip); read them from there — never ask for a re-upload.
 Text stays in your message; do not attach what you can say.`;
 
 const CODING_SYSTEM = `You are Switchboard's coding agent, operating from a Slack request.
@@ -426,28 +428,43 @@ Report outcomes faithfully: a check you could not run is "could not check", neve
 // 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.
+// that, so the model never expects a child to hold more than its requester
+// does. A child is a reader of this conversation: it starts from the text so
+// far plus the prompt, and the prompt says so. Machine `none`, identity
+// `none`: it holds no workspace, no shell and no credential of its own; its
+// reach is the 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 renders
+// the presets a child can run from the registry the way `help` renders its
+// rows: every sibling whose identity is not `write`, with its own description,
+// so the model picks from the real list and a preset that crosses the identity
+// line moves the day its def does; the write presets are named as what a child
+// never is, with the refusal's name.
+function conductorSystem(siblings: readonly AgentDef[]): string {
+  const readers = siblings.filter((a) => a.identity !== "write");
+  const writers = siblings.filter((a) => a.identity === "write");
+  const rows = readers.map(
+    (a) => `- \`${a.name}\`${machineNeedsRepo(a.machine) ? " (needs the repository)" : ""}: ${a.description}`,
+  );
+  return `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).
+THE PRESETS a child can run — a child reads, so only a preset whose identity is \`none\` or \`read\`:
+${rows.join("\n")}
+
+A preset that writes — ${writers.map((a) => `\`${a.name}\``).join(", ")} — is refused by name (\`spawn_identity\`): a spawned child never holds a write credential, so pushing a branch or opening a pull request is the requester's to start by hand with \`agent:<preset>\`; say so in your answer instead of spawning it.
 
 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\`.
+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 prompt that says what it should do, and the repository where the preset needs one: a child starts from this conversation's text so far — every user and assistant turn before your call, never your tool calls, their results or your thinking — and your prompt is its one new turn, so tell it what to do rather than repeat what was said. 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
@@ -469,11 +486,15 @@ export function presetDoor(def: AgentDef): PresetDoor {
   return def.name === COMPOUND_PRESET ? "compound" : "directive";
 }
 
-export const AGENTS: Record<string, AgentDef> = {
+/** Every preset that does the work: the ones a conductor's children are drawn
+ *  from (those that read) and the ones it names as refused (those that write).
+ *  The conductor is built from this list below, so its prompt renders its
+ *  siblings and never itself. */
+const WORK_PRESETS = {
   general: {
     name: "general",
     description:
-      "Default assistant on the configured model: answers directly, reads the org's repos and manages their issues over GitHub, reads URLs. No workspace or shell.",
+      "Default assistant: answers directly, reads URLs, manages issues; the preset for any question the org's GitHub answers. No workspace or shell.",
     system: GENERAL_SYSTEM,
     toolset: "assistant",
     // The GitHub tools are REST in the bot process, so a general ask never
@@ -547,7 +568,7 @@ export const AGENTS: Record<string, AgentDef> = {
   research: {
     name: "research",
     description:
-      "Answers questions with web search, URL reading, and read access to the org's repos and issues over GitHub. No workspace.",
+      "Answers questions that need the web (search, URL reading); GitHub for context, not for a question GitHub alone answers. No workspace.",
     system: RESEARCH_SYSTEM,
     toolset: "web",
     machine: "none", // web I/O only; no workspace is provisioned
@@ -573,11 +594,15 @@ export const AGENTS: Record<string, AgentDef> = {
     cacheTtl: "1h",
     // No built-in effort: the deployment decides, as for coding.
   },
+} satisfies Record<string, AgentDef>;
+
+export const AGENTS: Record<string, AgentDef> = {
+  ...WORK_PRESETS,
   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,
+    system: conductorSystem(Object.values(WORK_PRESETS)),
     toolset: "conductor",
     // Nothing is provisioned and no credential minted: the run tools call the
     // dispatcher, the GitHub reads are REST in the bot process.

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

@@ -2,9 +2,9 @@
 // the machine class its tools execute on, the identity it acts as, and the
 // minutes it may run. A preset declares one; the run's EFFECTIVE profile is
 // what the pipeline hands the factory, the ledger and the runner — never the
-// preset's fields read again downstream. Pure and leaf: type-only imports, so
-// the node-free record contract and the state Worker can name the shape.
-import type { AgentDef, Identity, MachineClass } from "../agents/registry.js";
+// preset's fields read again downstream. Pure and near-leaf: the only value
+// import is the registry's `runawayTurnCap`, itself pure.
+import { runawayTurnCap, type AgentDef, type Identity, type MachineClass } from "../agents/registry.js";
 
 export type { Identity, MachineClass };
 
@@ -63,9 +63,12 @@ export function declaredProfile(preset: Pick<AgentDef, "machine" | "identity" |
 /** The preset with its budget replaced by the effective profile's — the def
  *  the runner is handed, since its deadline, wrap-up warning and budget label
  *  read `maxMinutes` (the same clipped copy the ship pipeline hands its child
- *  rounds). Always a copy: the shared `AgentDef` is never mutated. */
+ *  rounds). `maxTurns` is re-derived from the clipped minutes with the
+ *  registry's own `runawayTurnCap`, so the six-per-minute runaway guard holds
+ *  for the budget the run actually has, not the preset's declared one.
+ *  Always a copy: the shared `AgentDef` is never mutated. */
 export function budgetedAgent(agent: AgentDef, profile: RunProfile): AgentDef {
-  return { ...agent, maxMinutes: profile.minutes };
+  return { ...agent, maxMinutes: profile.minutes, maxTurns: runawayTurnCap(profile.minutes) };
 }
 
 // ---- boundaries: a scope caps, never grants -----------------------------------

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

@@ -134,7 +134,11 @@ export type RunNoteKind =
   /** 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";
+  | "tool_refused"
+  /** The stuck-loop guard fired (docs/reference/specs/run-loop.md item 18):
+   *  the same tool call failed identically six times in a row, so the run is
+   *  forced into its write-up instead of looping to the wall clock. */
+  | "stuck_loop";
 
 /** 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). */
@@ -158,6 +162,7 @@ export const RUN_NOTE_KINDS = [
   "compacted",
   "harness_error",
   "tool_refused",
+  "stuck_loop",
 ] as const satisfies readonly RunNoteKind[];
 type _EveryKindListed = [RunNoteKind] extends [(typeof RUN_NOTE_KINDS)[number]] ? true : never;
 const _everyKindListed: _EveryKindListed = true;

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

@@ -254,6 +254,13 @@ function unionMs(intervals: ReadonlyArray<{ start: number; end: number }>): numb
   return total;
 }
 
+/** One tool call's identity for retry/streak accounting: the tool name plus
+ *  the call's one-line summary (which carries the arguments — a bash command,
+ *  a path, a url). Shared with the runner's stuck-loop guard
+ *  (docs/reference/specs/run-loop.md item 18), so both count "the same call"
+ *  identically. */
+export const callSignature = (tool: string, summary: string): string => `${tool} ${summary}`;
+
 /** Analyze a run's event stream. Pure and deterministic; never mutates `events`. */
 export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOptions = {}): FrictionDiagnosis {
   const slowToolMs = opts.slowToolMs ?? DEFAULT_SLOW_TOOL_MS;
@@ -405,7 +412,7 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
 
     if (ev.type === "tool_call") {
       toolCalls++;
-      if (failedCalls.has(`${ev.tool} ${ev.summary}`)) {
+      if (failedCalls.has(callSignature(ev.tool, ev.summary))) {
         findings.push({
           category: "retry",
           severity: "low",
@@ -432,7 +439,7 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
           ? { interval: { start: span.startedAt, end: span.startedAt + durationMs } }
           : {};
 
-      if (!ev.ok) failedCalls.add(`${ev.tool} ${callSummary}`);
+      if (!ev.ok) failedCalls.add(callSignature(ev.tool, callSummary));
 
       if (ev.infra) {
         // An infra-level failure is the sandbox, not the command: classify once,

package/dist/assets/src/core/runLedger/types.ts

@@ -7,6 +7,7 @@ import type { ChatMessage, ToolDef } from "../../providers/types.js";
 import type { ChannelVisibility } from "../authz/types.js";
 import type { RunProfile } from "../../config/profile.js";
 import type { RunEvent } from "../runEvents.js";
+import type { RunSeed } from "../runRecord.js";
 
 /** How long a generation's claim on a run lasts without a heartbeat. */
 export const LEASE_MS = 30_000;
@@ -69,6 +70,9 @@ export interface LiveRunMeta {
    *  still sends the parent its event and a retried spawn finds its run. */
   parentInstanceId?: string;
   idempotencyKey?: string;
+  /** Where the run's conversation started (item 52), so a reclaimed run's
+   *  record still says so: `parent` for a spawned child, `channel` otherwise. */
+  seed?: RunSeed;
   /** Which executor the run attached: what `makeExecutor` chose. */
   selection?: "resident" | "sandbox" | "local" | "none";
   /** The worktree path the system prompt names. */