@coreplane/switchboard 1.208.0 → 1.209.0

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.208.0",
+  "version": "1.209.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.208.0",
+      "version": "1.209.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -18999,7 +18999,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.208.0",
+      "version": "1.209.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.208.0",
+  "version": "1.209.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.208.0",
-  "commit": "348d6f6ebbf7cf242f39951c0a81585527f49181",
-  "builtAt": "2026-09-14T03:37:32.458Z"
+  "version": "1.209.0",
+  "commit": "921bd6b7bd8c7cd979c68435a47bc7ad169a3893",
+  "builtAt": "2026-09-14T05:12:19.226Z"
 }

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

@@ -1,8 +1,8 @@
-// Agent definitions. An agent is a system prompt + toolset + machine class + turn budget.
+// Agent definitions. An agent is a system prompt + toolset + machine class + wall-clock budget.
 import type { Effort } from "../effort.js";
 import type { CacheTtl } from "../providers/types.js";
 import { BASH_TIMEOUT_MAX_MS } from "../execution/bashTimeout.js";
-import { CONTRACT_HEADING, CONTRACT_SECTION_HEADINGS } from "../core/ship/contract.js";
+import { CONTRACT_HEADING, CONTRACT_SECTION_HEADINGS, PR_TITLE_GUARD } from "../core/ship/contract.js";
 // Which model runs it is resolved separately by the config layers, so any
 // agent can run on any configured provider/model.
 
@@ -42,13 +42,37 @@ export function machineNeedsRepo(machine: MachineClass): boolean {
 export const IDENTITIES = ["none", "read", "write"] as const;
 export type Identity = (typeof IDENTITIES)[number];
 
+/** The pace that marks a run as looping rather than working: a model turn
+ *  every ten seconds, sustained for the whole wall clock. A busy run takes
+ *  20–40 s a turn (a model think plus a tool call), so a run that averages six
+ *  a minute from start to end is re-issuing calls, not making progress — and
+ *  its turn cap ends it before the wall clock would, with a write-up that
+ *  says so (docs/reference/specs/run-loop.md item 1). */
+export const RUNAWAY_TURNS_PER_MINUTE = 6;
+
+/** The turn cap a wall clock implies: `maxMinutes × RUNAWAY_TURNS_PER_MINUTE`.
+ *  Every preset that runs the loop derives its `maxTurns` from this, so the
+ *  cap is never a number a good run reaches — the minutes are the budget. */
+export function runawayTurnCap(maxMinutes: number): number {
+  return maxMinutes * RUNAWAY_TURNS_PER_MINUTE;
+}
+
+/** A loop-running preset's budget as one fact: the wall clock, and the runaway
+ *  guard derived from it. */
+function loopBudget(maxMinutes: number): Pick<AgentDef, "maxMinutes" | "maxTurns"> {
+  return { maxMinutes, maxTurns: runawayTurnCap(maxMinutes) };
+}
+
 export interface AgentDef {
   name: string;
   description: string;
   system: string;
   /** 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 */
+  /** The runaway guard, not a budget: `runawayTurnCap(maxMinutes)` for every
+   *  preset that runs the loop (`loopBudget`). The wall clock below is the
+   *  budget; a run that reaches this cap first was pacing like a loop, and its
+   *  write-up says so. The proxy refuses model calls past it too. */
   maxTurns: number;
   maxTokens: number;
   /** hard wall-clock budget for the tool loop; at the deadline the agent is
@@ -97,7 +121,7 @@ export interface AgentDef {
 // and rendered against the head sha at render time, so a repush is a
 // re-render by Switchboard — the agent only resubmits when the CONTENT (line
 // numbers included) changed.
-const PR_DESCRIPTION_TEMPLATE = `PR description — submit it with the submit_pr_description tool for EVERY PR (this is the default, not something to wait to be asked for). Switchboard renders the GitHub body from the object you submit, so never author PR-body markdown yourself. Content contract per field (each renders as its own section): prose is unwrapped — no hard line breaks inside a paragraph. Always hyperlink the triggering issue/request. Never fabricate validation — state exactly what you ran and the real result. Keep each field concise, not padded.
+const PR_DESCRIPTION_TEMPLATE = `PR description — submit it with the submit_pr_description tool for EVERY PR (this is the default, not something to wait to be asked for). Switchboard renders the GitHub body from the object you submit, so never author PR-body markdown yourself. Before submitting, judge your title with the ${PR_TITLE_GUARD} gate — \`npm run check:pr-title -- "<title>"\` — and submit only a title it accepts; the same gate refuses the PR in CI. Content contract per field (each renders as its own section): prose is unwrapped — no hard line breaks inside a paragraph. Always hyperlink the triggering issue/request. Never fabricate validation — state exactly what you ran and the real result. Keep each field concise, not padded.
 EVERY PR includes one that already exists when you push — opened by a person, by dependabot, or by an earlier run. After EVERY push to such a PR: read its current title and body (\`github_issue_get\` with the PR number works for pull requests; \`gh pr view\` where gh exists), judge them against the change as it now stands at the pushed head, and submit the object that describes the PR as it is NOW — carry forward what the existing body says that is still true (a dependency bump's release notes belong in whatWhy), add what you changed, and anchor the Tour at the new head. Switchboard replaces the PR's title and body with your rendering. A description that describes an earlier state of its branch is a bug; "it is someone else's PR" is never a reason to leave it.
 - **title**: the PR title — one line naming the change, specific enough to pick out of a PR list.
 - **TL;DR** (\`tldr\`, rendered first): two sentences for a naive reader with zero context — what this PR does and why it matters.
@@ -401,9 +425,8 @@ export const AGENTS: Record<string, AgentDef> = {
     // and mints no credential of its own.
     machine: "none",
     identity: "none",
-    maxTurns: 8, // a repo read is 2-3 calls (repos → tree → file); an issue action 1-2; still fast
     maxTokens: 16000,
-    maxMinutes: 5,
+    ...loopBudget(5),
   },
   coding: {
     name: "coding",
@@ -411,9 +434,8 @@ export const AGENTS: Record<string, AgentDef> = {
     system: CODING_SYSTEM,
     residentSystem: CODING_SYSTEM_RESIDENT,
     toolset: "full",
-    maxTurns: 60, // scoping is capped at ~5 calls by the prompt; this is implementation room
     maxTokens: 64000,
-    maxMinutes: 45,
+    ...loopBudget(45),
     // Coding steps run long: a single model turn can take 5-6 minutes and
     // installs/tests add more — a 5m cache entry would expire between
     // requests, so the 2× write buys reads for the whole run.
@@ -431,9 +453,8 @@ export const AGENTS: Record<string, AgentDef> = {
     toolset: "readonly",
     machine: "repo-resident",
     identity: "read", // a read-scoped token and a read-only worktree: it cannot post or push from inside
-    maxTurns: 30, // backstop only; wall clock is the real budget (12 bound at ~4 min in practice)
     maxTokens: 64000,
-    maxMinutes: 25, // safety net, not the mechanism — typical reviews land in ~5
+    ...loopBudget(25), // a safety net — typical reviews land in ~5 minutes
     effort: "medium", // fast turns; one big-context pass does the deep work
   },
   ship: {
@@ -468,9 +489,8 @@ export const AGENTS: Record<string, AgentDef> = {
     toolset: "web",
     machine: "none", // web I/O only; no workspace is provisioned
     identity: "none",
-    maxTurns: 12,
     maxTokens: 24000,
-    maxMinutes: 8,
+    ...loopBudget(8),
     effort: "medium",
   },
   explore: {
@@ -483,9 +503,8 @@ export const AGENTS: Record<string, AgentDef> = {
     // review depends on: a two-hour job shares no container with anyone.
     machine: "repo-cold",
     identity: "read", // a read-scoped token: it can clone and read, never push — whatever the caller holds
-    maxTurns: 150, // a backstop for a two-hour loop of batched checks; the wall clock is the budget
     maxTokens: 64000,
-    maxMinutes: 120,
+    ...loopBudget(120),
     // A detached job polled across calls makes long steps: a 5m cache entry
     // would expire between them, so the 2× write buys reads for the whole run.
     cacheTtl: "1h",
@@ -501,9 +520,8 @@ export const AGENTS: Record<string, AgentDef> = {
     // 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
+    ...loopBudget(120), // long enough to outlast a coding child; every child is capped by what remains of it
     // No built-in effort: the deployment decides, as for coding.
   },
 };

package/dist/cli.js

@@ -1560,6 +1560,12 @@ var init_contract = __esm({
 function machineNeedsRepo(machine) {
   return machine === "repo-cold" || machine === "repo-resident";
 }
+function runawayTurnCap(maxMinutes) {
+  return maxMinutes * RUNAWAY_TURNS_PER_MINUTE;
+}
+function loopBudget(maxMinutes) {
+  return { maxMinutes, maxTurns: runawayTurnCap(maxMinutes) };
+}
 function getAgent(name) {
   const a = AGENTS[name];
   if (!a) {
@@ -1567,7 +1573,7 @@ function getAgent(name) {
   }
   return a;
 }
-var MACHINE_CLASSES, IDENTITIES, PR_DESCRIPTION_TEMPLATE, NEVER_MERGE, CONTRACT_HEADINGS_LIST, UNIT_CONTRACT, UNIT_HANDOFF, IMAGE_TOOLCHAIN, SANDBOX_TOOLCHAIN, RESIDENT_TOOLCHAIN, CODING_SYSTEM, CODING_SYSTEM_RESIDENT, REVIEW_VERDICT_INSTRUCTION, REVIEW_SPEC_CHECK, REVIEW_UNIT_CONTRACT, REVIEW_WHOLE_CHANGE, REVIEW_SYSTEM, REVIEW_SYSTEM_RESIDENT, RESEARCH_SYSTEM, GENERAL_SYSTEM, EXPLORE_SYSTEM, CONDUCTOR_SYSTEM, AGENTS;
+var MACHINE_CLASSES, IDENTITIES, RUNAWAY_TURNS_PER_MINUTE, PR_DESCRIPTION_TEMPLATE, NEVER_MERGE, CONTRACT_HEADINGS_LIST, UNIT_CONTRACT, UNIT_HANDOFF, IMAGE_TOOLCHAIN, SANDBOX_TOOLCHAIN, RESIDENT_TOOLCHAIN, CODING_SYSTEM, CODING_SYSTEM_RESIDENT, REVIEW_VERDICT_INSTRUCTION, REVIEW_SPEC_CHECK, REVIEW_UNIT_CONTRACT, REVIEW_WHOLE_CHANGE, REVIEW_SYSTEM, REVIEW_SYSTEM_RESIDENT, RESEARCH_SYSTEM, GENERAL_SYSTEM, EXPLORE_SYSTEM, CONDUCTOR_SYSTEM, AGENTS;
 var init_registry = __esm({
   "../../src/agents/registry.ts"() {
     "use strict";
@@ -1575,7 +1581,8 @@ var init_registry = __esm({
     init_contract();
     MACHINE_CLASSES = ["none", "blank", "repo-cold", "repo-resident"];
     IDENTITIES = ["none", "read", "write"];
-    PR_DESCRIPTION_TEMPLATE = `PR description \u2014 submit it with the submit_pr_description tool for EVERY PR (this is the default, not something to wait to be asked for). Switchboard renders the GitHub body from the object you submit, so never author PR-body markdown yourself. Content contract per field (each renders as its own section): prose is unwrapped \u2014 no hard line breaks inside a paragraph. Always hyperlink the triggering issue/request. Never fabricate validation \u2014 state exactly what you ran and the real result. Keep each field concise, not padded.
+    RUNAWAY_TURNS_PER_MINUTE = 6;
+    PR_DESCRIPTION_TEMPLATE = `PR description \u2014 submit it with the submit_pr_description tool for EVERY PR (this is the default, not something to wait to be asked for). Switchboard renders the GitHub body from the object you submit, so never author PR-body markdown yourself. Before submitting, judge your title with the ${PR_TITLE_GUARD} gate \u2014 \`npm run check:pr-title -- "<title>"\` \u2014 and submit only a title it accepts; the same gate refuses the PR in CI. Content contract per field (each renders as its own section): prose is unwrapped \u2014 no hard line breaks inside a paragraph. Always hyperlink the triggering issue/request. Never fabricate validation \u2014 state exactly what you ran and the real result. Keep each field concise, not padded.
 EVERY PR includes one that already exists when you push \u2014 opened by a person, by dependabot, or by an earlier run. After EVERY push to such a PR: read its current title and body (\`github_issue_get\` with the PR number works for pull requests; \`gh pr view\` where gh exists), judge them against the change as it now stands at the pushed head, and submit the object that describes the PR as it is NOW \u2014 carry forward what the existing body says that is still true (a dependency bump's release notes belong in whatWhy), add what you changed, and anchor the Tour at the new head. Switchboard replaces the PR's title and body with your rendering. A description that describes an earlier state of its branch is a bug; "it is someone else's PR" is never a reason to leave it.
 - **title**: the PR title \u2014 one line naming the change, specific enough to pick out of a PR list.
 - **TL;DR** (\`tldr\`, rendered first): two sentences for a naive reader with zero context \u2014 what this PR does and why it matters.
@@ -1766,10 +1773,8 @@ Use Slack-friendly formatting (no markdown headers; *bold*, bullets, code blocks
         // and mints no credential of its own.
         machine: "none",
         identity: "none",
-        maxTurns: 8,
-        // a repo read is 2-3 calls (repos → tree → file); an issue action 1-2; still fast
         maxTokens: 16e3,
-        maxMinutes: 5
+        ...loopBudget(5)
       },
       coding: {
         name: "coding",
@@ -1777,10 +1782,8 @@ Use Slack-friendly formatting (no markdown headers; *bold*, bullets, code blocks
         system: CODING_SYSTEM,
         residentSystem: CODING_SYSTEM_RESIDENT,
         toolset: "full",
-        maxTurns: 60,
-        // scoping is capped at ~5 calls by the prompt; this is implementation room
         maxTokens: 64e3,
-        maxMinutes: 45,
+        ...loopBudget(45),
         // Coding steps run long: a single model turn can take 5-6 minutes and
         // installs/tests add more — a 5m cache entry would expire between
         // requests, so the 2× write buys reads for the whole run.
@@ -1800,11 +1803,9 @@ Use Slack-friendly formatting (no markdown headers; *bold*, bullets, code blocks
         machine: "repo-resident",
         identity: "read",
         // a read-scoped token and a read-only worktree: it cannot post or push from inside
-        maxTurns: 30,
-        // backstop only; wall clock is the real budget (12 bound at ~4 min in practice)
         maxTokens: 64e3,
-        maxMinutes: 25,
-        // safety net, not the mechanism — typical reviews land in ~5
+        ...loopBudget(25),
+        // a safety net — typical reviews land in ~5 minutes
         effort: "medium"
         // fast turns; one big-context pass does the deep work
       },
@@ -1838,9 +1839,8 @@ Use Slack-friendly formatting (no markdown headers; *bold*, bullets, code blocks
         machine: "none",
         // web I/O only; no workspace is provisioned
         identity: "none",
-        maxTurns: 12,
         maxTokens: 24e3,
-        maxMinutes: 8,
+        ...loopBudget(8),
         effort: "medium"
       },
       explore: {
@@ -1853,10 +1853,8 @@ Use Slack-friendly formatting (no markdown headers; *bold*, bullets, code blocks
         machine: "repo-cold",
         identity: "read",
         // a read-scoped token: it can clone and read, never push — whatever the caller holds
-        maxTurns: 150,
-        // a backstop for a two-hour loop of batched checks; the wall clock is the budget
         maxTokens: 64e3,
-        maxMinutes: 120,
+        ...loopBudget(120),
         // A detached job polled across calls makes long steps: a 5m cache entry
         // would expire between them, so the 2× write buys reads for the whole run.
         cacheTtl: "1h"
@@ -1871,10 +1869,8 @@ Use Slack-friendly formatting (no markdown headers; *bold*, bullets, code blocks
         // 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: 32e3,
-        maxMinutes: 120
+        ...loopBudget(120)
         // long enough to outlast a coding child; every child is capped by what remains of it
         // No built-in effort: the deployment decides, as for coding.
       }
@@ -14526,7 +14522,7 @@ ${evidence}`);
     case "wrap_up":
       return `Runs keep reaching the wrap-up warning (${p.runIds.length} runs; ${formatDuration(p.durationMs, "report")} spent winding down). Either the affected agent's \`maxMinutes\` (\`src/agents/registry.ts\`) is too tight for this shape of work, or the prompt should push batching (fewer, larger tool calls) \u2014 the evidence rows say which agent and how close to the deadline each run got.`;
     case "budget_hit":
-      return p.signature === "turns" ? `Runs exhaust the TURN budget. Raise \`maxTurns\` for the affected agent (\`src/agents/registry.ts\`) or have its prompt batch tool calls (several commands per \`bash\` call) so the same work takes fewer turns.` : `Runs exhaust the TIME budget and are cut off mid-work. Raise \`maxMinutes\` for the affected agent (\`src/agents/registry.ts\`), or split the task shape that triggers it \u2014 a run that is forced to write up findings is a run whose work was wasted.`;
+      return p.signature === "turns" ? `Runs outpace the runaway guard: the turn cap is \`RUNAWAY_TURNS_PER_MINUTE\` (${RUNAWAY_TURNS_PER_MINUTE} turns a minute) over the affected agent's wall clock, a pace a working run does not sustain \u2014 so a run that reaches it is looping, not working. Read the evidence rows for a retry loop (the same call re-issued turn after turn) and fix its cause where the agent reads before acting (the target repo's AGENTS.md, the resident command table), or have the prompt batch tool calls (several commands per \`bash\` call). The cap is derived from \`maxMinutes\` (\`src/agents/registry.ts\`), not a knob to turn.` : `Runs exhaust the TIME budget and are cut off mid-work. Raise \`maxMinutes\` for the affected agent (\`src/agents/registry.ts\`), or split the task shape that triggers it \u2014 a run that is forced to write up findings is a run whose work was wasted.`;
     case "infra_failure":
       if (p.signature === "sandbox_dead") {
         return `The sandbox died mid-run in ${p.runIds.length} runs. Check container sizing first (the \`deploy/cloudflare-*/wrangler.template.jsonc\` comments: the 1 GiB \`basic\` tier died running vitest; thread sandboxes are \`standard-4\` \u2014 4 vCPU / 12 GiB / 20 GB, the platform's largest \u2014 and residents a custom type of the same size), then the memory footprint of the failing command, then the sandbox/resident Worker logs (\`deploy/bin/cf-logs\`) around the affected runs.`;
@@ -14559,6 +14555,7 @@ var init_frictionProposals = __esm({
   "../../src/core/frictionProposals.ts"() {
     "use strict";
     init_runFriction();
+    init_registry();
     init_formatDuration();
     DEFAULT_MIN_RUNS = 2;
     MAX_EXAMPLES = 5;
@@ -26248,21 +26245,33 @@ async function runLoop(opts, now, note, emit, agentSpan) {
     return await finishSandboxDead(complete2, opts, messages, system, diagnosis);
   }
   const wasTimeout = now() >= deadline;
+  const elapsedMs = opts.agent.maxMinutes * 6e4 - (deadline - now());
+  const pace = `${turn} model turn${turn === 1 ? "" : "s"} in ${elapsedMinutes(elapsedMs)}`;
   note(
     wasTimeout ? "time_budget_exhausted" : "turn_budget_exhausted",
-    `${wasTimeout ? "time" : "turn"} budget exhausted \u2014 writing up findings so far`
+    wasTimeout ? "time budget exhausted \u2014 writing up findings so far" : `turn guard fired: ${pace}, a pace that looks like a loop \u2014 writing up findings so far`
   );
+  const writeUp = "Write your final answer now from what you have learned so far: report your findings/results to date, then state plainly which parts of the task you did not get to and what a follow-up (in this thread, to reuse this workspace) should focus on.";
   const text = await runFinale(
     complete2,
     opts,
     messages,
     system,
-    "You have reached the turn budget and can make no more tool calls. Write your final answer now from what you have learned so far: report your findings/results to date, then state plainly which parts of the task you did not get to and what a follow-up (in this thread, to reuse this workspace) should focus on."
+    wasTimeout ? `You have reached the time budget and can make no more tool calls. ${writeUp}` : `You have hit the run's turn guard \u2014 ${pace}, a pace that looks like a loop \u2014 and can make no more tool calls. ${writeUp}`
   );
-  const budgetLabel = wasTimeout ? `${opts.agent.maxMinutes}-minute` : `${opts.agent.maxTurns}-turn`;
-  return text ? `\u26A0\uFE0F _Hit the ${budgetLabel} budget before finishing \u2014 findings so far:_
+  if (wasTimeout) {
+    return text ? `\u26A0\uFE0F _Hit the ${opts.agent.maxMinutes}-minute budget before finishing \u2014 findings so far:_
 
-${text}` : `Stopped at the ${budgetLabel} budget without finishing. Partial work may exist in the workspace \u2014 narrow the task and try again.`;
+${text}` : `Stopped at the ${opts.agent.maxMinutes}-minute budget without finishing. Partial work may exist in the workspace \u2014 narrow the task and try again.`;
+  }
+  return text ? `\u26A0\uFE0F _Stopped after ${pace} \u2014 that pace looks like a loop; findings so far:_
+
+${text}` : `Stopped after ${pace} \u2014 that pace looks like a loop \u2014 without finishing. Partial work may exist in the workspace \u2014 look for a retry loop in the run's events before trying again.`;
+}
+function elapsedMinutes(ms) {
+  const minutes = Math.round(ms / 6e4);
+  if (minutes < 1) return "under a minute";
+  return `${minutes} minute${minutes === 1 ? "" : "s"}`;
 }
 async function runFinale(complete2, opts, messages, system, instruction) {
   messages.push({ role: "user", content: [{ type: "text", text: instruction }] });
@@ -37004,7 +37013,7 @@ async function handleAdmitted(door, req, deps) {
     grant2.publish({
       type: "run_note",
       kind: "turn_budget_exhausted",
-      summary: `model proxy refused a call past the ${turn.maxTurns}-turn budget (${used})`,
+      summary: `model proxy refused a call past the run's ${turn.maxTurns}-turn guard (${used})`,
       at: deps.clock()
     });
     log(`[model-proxy] 403 turn_budget_exhausted run=${grant2.runId} turns=${turn.turns}/${turn.maxTurns}`);
@@ -37012,7 +37021,7 @@ async function handleAdmitted(door, req, deps) {
       shape,
       403,
       "turn_budget_exhausted",
-      `the run's ${turn.maxTurns}-turn budget is spent (${used})`
+      `the run is past its ${turn.maxTurns}-turn guard (${used})`
     );
   }
   const payload = JSON.stringify(pinRequest(shape, body, grant2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coreplane/switchboard",
-  "version": "1.208.0",
+  "version": "1.209.0",
   "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",
   "homepage": "https://openswitchboard.dev",