@coreplane/switchboard 1.242.0 → 1.243.0

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

@@ -1,6 +1,7 @@
 // Agent definitions. An agent is a system prompt + toolset + machine class + wall-clock budget.
 import type { Effort } from "../effort.js";
 import { BASH_TIMEOUT_MAX_MS } from "../execution/bashTimeout.js";
+import { ASKS, RUNAWAY_TURNS_PER_MINUTE, runawayTurnCap, type LoopPreset } from "../core/budgets.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.
@@ -41,24 +42,16 @@ 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/harness-pi.md item 15). */
-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;
-}
+/** The wall clocks live in `src/core/budgets.ts` (docs/decisions/0046): a
+ *  preset's ask, the turn cap derived from it and every allowance are rows
+ *  there, and this registry reads them. Re-exported for the readers that
+ *  learned them here. */
+export { RUNAWAY_TURNS_PER_MINUTE, runawayTurnCap };
 
-/** 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"> {
+/** A loop-running preset's budget as one fact read from the module: the wall
+ *  clock it asks for, and the runaway guard derived from it. */
+function loopBudget(preset: LoopPreset): Pick<AgentDef, "maxMinutes" | "maxTurns"> {
+  const maxMinutes = ASKS[preset];
   return { maxMinutes, maxTurns: runawayTurnCap(maxMinutes) };
 }
 
@@ -150,15 +143,18 @@ export function statusCardRule(examples = '"Implement the fix", "Run the test su
   );
 }
 
-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.
+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. The body is a fixed-size MAP for the reader with everything for agents collapsed under it; every field is capped in visible characters (a link's URL is not counted) and the tool refuses an object over a cap naming the field and the count — cut and resubmit. 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. BEFORE authoring the pointers, load the \`pr-description\` skill with use_skill — it defines how to choose at most seven pointers, the mechanical anchor rules and what goes below the fold; follow it for every PR.
+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 why), add what you changed, and anchor the pointers 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.
-- **What & why** (\`whatWhy\`): the change and its motivation, linked to the triggering issue/request.
-- **Tour** (\`tour\` + \`remaining\`): the guided walkthrough of the change, replacing any prose list of changes — ordered steps of { title, description, optional lookFor, anchor }, each anchor a { path, from, to } line range at your pushed head; every touched file no step covers goes in \`remaining\` as { path, note }. BEFORE authoring the Tour steps, load the \`pr-tour\` skill with use_skill — it defines the reader-first step shape, the anchor rules, and the Remaining-changes catch-all. Follow it for every PR; if a later push changes what the steps point at, resubmit the description with corrected anchors.
-- **Decisions** (\`decisions\`): non-obvious choices as { title, rationale } — alternatives considered and rejected, trade-offs.
-- **Risks & implications** (\`risks\`): what could break, the blast radius, and any migration/rollout/compatibility concerns (or "none" — and why).
-- **Validation** (\`validation\`): what you tested and the actual results as { criterion, proof } rows (commands run, pass/fail), plus how the reviewer can verify it themselves; the optional summary line carries the overall result.`;
+- **TL;DR** (\`tldr\`, rendered first, ≤300): two sentences for a reader with zero context — what this PR does and why it matters.
+- **Why** (\`why\`, ≤400): the problem and the motivation, with the triggering issue/request, the record and the stack position hyperlinked. Why, never what: the diff shows what.
+- **Where to look** (\`pointers\`, 1 to 7): the files a reviewer would open first, in reading order, each { label ≤60, text ≤160, optional risk ≤100, anchor } with the anchor a { path, from, to } line range at your pushed head, rendered as a link (never embedded code). One pointer per idea, never per file; when the change has more ideas than seven, keep the seven whose mistake would cost most.
+- **Feedback wanted** (\`feedbackWanted\`, ≤200): the one or two things you want the reviewer's judgement on.
+- **Risk** (\`risk\`, ≤300): what breaks if this is wrong, the blast radius, the rollback; over 400 changed lines, say so and name the split you considered.
+- **Verified** (\`verified\`, ≤200): one line for a person — which suites ran and passed, what is still human-gated.
+- **Decisions** (\`decisions\`, 0 to 10, collapsed): non-obvious choices as { title, rationale ≤400 } — the alternative rejected and the fact that decided it.
+- **Validation** (\`validation\`, 1 to 30 criteria, collapsed): what you tested and the actual results as { criterion ≤200, proof ≤300 } rows (test ids, commands run, pass/fail), plus how the reviewer can verify it.
+- **For agents** (\`agentNotes\`, optional, ≤2000, collapsed): what a reviewing agent needs that a person does not — the rebase you did, generated files to skip, the command that reproduces the bug.`;
 
 // Both coding prompts carry this verbatim: coding runs hold a write-scoped
 // token where a merge is one command away, so the boundary is spelled out the
@@ -521,7 +517,7 @@ Your tools work without a workspace: the GitHub tools — \`github_repos\` (the
 
 ${statusCardRule('"Read the issue and its thread", "Post the comment"')} A one-step answer needs no checklist; post one when the request has steps the person would wait on.
 
-You cannot run commands, clone repositories, edit code, or review pull requests, and you cannot search the web. Other Switchboard agents can: for code changes or PRs tell the user to re-send with \`agent:coding\`; for a PR review, \`agent:review\`; for a web-research question, \`agent:research\` (e.g. "\`agent:coding fix the failing login test in acme/api\`", "\`agent:research compare X and Y\`"). Delete an issue only when the user explicitly asked to delete it (closing is an update).`;
+You cannot run commands, clone repositories, edit code, or review pull requests, and you cannot search the web. Other Switchboard agents can: for a code change or a pull request tell the user to re-send with \`agent:ship\` (it makes the change, opens the PR and loops review); for a PR review, \`agent:review\`; for a web-research question, \`agent:research\` (e.g. "\`agent:ship in acme/api: fix the failing login test\`", "\`agent:research compare X and Y\`"). Delete an issue only when the user explicitly asked to delete it (closing is an update).`;
 
 // The explore agent (docs/reference/specs/agent-explore.md): a long, read-only
 // investigation — "run our CI locally and validate the claims", "how long does
@@ -544,7 +540,7 @@ THE DELIVERABLE IS A CLAIM TABLE. Turn the request into the claims it makes or a
 
 TIME. Your budget is up to two hours — less when a boundary or the request's \`budget:\` directive clipped it, which the runtime-config block above says — and the wrap-up warning tells you when to stop starting new checks. A single command is capped at ${BASH_TIMEOUT_MAX_MS / 60_000} minutes (pass the bash tool's \`timeoutMs\`, up to ${BASH_TIMEOUT_MAX_MS} ms, for a long one). A job that needs longer — a full suite, a build, a pipeline run — is started detached and polled across tool calls: \`setsid -f sh -c '<command> > /tmp/job.log 2>&1; echo $? > /tmp/job.exit'\`, then \`tail -n 40 /tmp/job.log\` and \`cat /tmp/job.exit\` on later calls (a plain background job dies with the command that started it; a \`setsid -f\` job outlives it). Batch commands into few tool calls; never explore file by file.
 
-READ-ONLY: NEVER open a pull request, and never commit or push — no branch, no \`gh pr create\`, no PR or issue write of any kind. You hold a read credential and your job is to find out, not to change. If the investigation shows a change is needed, say exactly what and where in your write-up and point the user at \`agent:coding\`.
+READ-ONLY: NEVER open a pull request, and never commit or push — no branch, no \`gh pr create\`, no PR or issue write of any kind. You hold a read credential and your job is to find out, not to change. If the investigation shows a change is needed, say exactly what and where in your write-up and point the user at \`agent:ship\` (it makes the change, opens the PR and loops review).
 
 You cannot attach or post files: your whole answer is text. Never say a file is attached or below — name its path in the workspace and describe it (what it shows, its size) instead; a person who needs the file itself asks \`agent:coding\`, which can attach.
 
@@ -638,7 +634,7 @@ const WORK_PRESETS = {
     machine: "none",
     identity: "none",
     maxTokens: 16000,
-    ...loopBudget(5),
+    ...loopBudget("general"),
   },
   coding: {
     name: "coding",
@@ -648,7 +644,7 @@ const WORK_PRESETS = {
     seededSystem: CODING_SYSTEM_SEEDED,
     toolset: "full",
     maxTokens: 64000,
-    ...loopBudget(45),
+    ...loopBudget("coding"),
     // No built-in effort: the deployment decides (`defaults.efforts.coding`,
     // `config set channel efforts.coding=…`, or `effort:` per request).
     machine: "repo-resident",
@@ -669,7 +665,7 @@ const WORK_PRESETS = {
     machine: "repo-resident",
     identity: "read", // a read-scoped token and a read-only worktree: it cannot post or push from inside
     maxTokens: 64000,
-    ...loopBudget(25), // a safety net — typical reviews land in ~5 minutes
+    ...loopBudget("review"), // a safety net — typical reviews land in ~5 minutes
     effort: "medium", // fast turns; one big-context pass does the deep work
   },
   ship: {
@@ -698,7 +694,7 @@ const WORK_PRESETS = {
     // reviewed pull request, never code landing on main.
     maxTurns: 1,
     maxTokens: 16000,
-    maxMinutes: 120,
+    maxMinutes: ASKS.ship,
   },
   research: {
     name: "research",
@@ -709,7 +705,7 @@ const WORK_PRESETS = {
     machine: "none", // web I/O only; no workspace is provisioned
     identity: "none",
     maxTokens: 24000,
-    ...loopBudget(8),
+    ...loopBudget("research"),
     effort: "medium",
   },
   explore: {
@@ -723,7 +719,7 @@ const WORK_PRESETS = {
     machine: "repo-cold",
     identity: "read", // a read-scoped token: it can clone and read, never push — whatever the caller holds
     maxTokens: 64000,
-    ...loopBudget(120),
+    ...loopBudget("explore"),
     // No built-in effort: the deployment decides, as for coding.
   },
 } satisfies Record<string, AgentDef>;
@@ -748,7 +744,7 @@ export const AGENTS: Record<string, AgentDef> = {
     // spawn exactly those — so no child runs that the record did not name.
     routable: false,
     maxTokens: 32000,
-    ...loopBudget(120), // long enough to outlast a coding child; every child is capped by what remains of it
+    ...loopBudget("conductor"), // 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/assets/src/config/profile.ts

@@ -73,10 +73,40 @@ export function budgetedAgent(agent: AgentDef, profile: RunProfile): AgentDef {
 
 // ---- boundaries: a scope caps, never grants -----------------------------------
 
+/** The blast-radius classes a scope may name as its `confirm`
+ *  (docs/decisions/0044-a-routed-write-is-confirmed-in-proportion-to-its-blast-radius.md):
+ *  the first class on the ladder the door hands back instead of running.
+ *  `exec` is on the ladder for the comparison but not settable — a test or
+ *  build never asks — and `never` is refused until the door's write misbind
+ *  rate has been measured; the validator names both reasons. */
+export type ConfirmClass = "write" | "destructive";
+export const CONFIRM_CLASSES: readonly ConfirmClass[] = ["write", "destructive"];
+
+/** The classes on the door's ladder — the command registry's `BlastRadius`,
+ *  spelled here rather than imported: a type import still drags the registry's
+ *  whole graph into every program that compiles this near-leaf module, the
+ *  Workers included. The door indexes the ladder with the registry's type
+ *  (`routedRunsAtOnce`), so a class added there without a rung here fails to
+ *  compile at the one place the two vocabularies meet. */
+export type ConfirmLadderClass = "read" | "exec" | "write" | "destructive";
+
+/** The ladder the door compares on, `read < exec < write < destructive`: among
+ *  the last three, from asking most to asking least — a `confirm` of `write`
+ *  hands back every write and every destructive write, `destructive` only the
+ *  destructive ones. A read is on the order so the comparison is total, but the
+ *  door never asks for one. */
+export const CONFIRM_ORDER: Record<ConfirmLadderClass, number> = { read: 0, exec: 1, write: 2, destructive: 3 };
+
+/** The door's confirm class when no scope sets one: every routed write is
+ *  handed back, a read or a test run at once — the door as it was before the
+ *  axis existed. Attributed to `built-in`, a word that appears in no config. */
+export const BUILT_IN_CONFIRM: ConfirmClass = "write";
+
 /** A cap on the three axes that any scope may set (`defaults`, `channels.<id>`,
- *  `users.<id>`; docs/reference/specs/routing-and-config.md item 2). An absent
- *  axis caps nothing. A boundary never grants: it is not a fourth grants axis,
- *  and the policy table's one question (who may run a preset) is unchanged. */
+ *  `users.<id>`; docs/reference/specs/routing-and-config.md item 2), and the
+ *  door's `confirm` beside them. An absent axis caps nothing. A boundary never
+ *  grants: it is not a fourth grants axis, and the policy table's one question
+ *  (who may run a preset) is unchanged. */
 export interface Boundary {
   /** The most a run may have, in minutes; at least 2 (the bash tool keeps a 60 s reserve). */
   maxMinutes?: number;
@@ -84,6 +114,11 @@ export interface Boundary {
   maxIdentity?: Identity;
   /** The machine classes a run may execute on; a preset's class must be in every layer's set. */
   machines?: MachineClass[];
+  /** The first blast-radius class a command the router bound is handed back
+   *  at instead of run (record 0044). Not a run cap: it rides the boundary for
+   *  its scopes and its intersection-toward-caution, is read by the door alone
+   *  (`effectiveConfirm`), and never enters `intersectBoundaries` or a profile. */
+  confirm?: ConfirmClass;
 }
 
 /** One layer's boundary with the scope it came from, in resolution order:
@@ -143,6 +178,36 @@ export function intersectBoundaries(layers: readonly ScopedBoundary[]): Effectiv
   return out.maxMinutes || out.maxIdentity || out.machines ? out : undefined;
 }
 
+/** Where the door's confirm class came from: a scope that set it, or the
+ *  built-in default when none did. Local to the confirm axis — `BoundaryScope`
+ *  itself is unchanged, since no run cap is ever attributed to `built-in`. */
+export type ConfirmScope = BoundaryScope | "built-in";
+
+/** The door's decision on the confirm axis: the class and the scope it names. */
+export interface EffectiveConfirm {
+  value: ConfirmClass;
+  scope: ConfirmScope;
+}
+
+/**
+ * The confirm axis intersected over a request's path, apart from the run caps:
+ * the earliest class on `CONFIRM_ORDER` any layer named — the most cautious,
+ * since a scope's value is the most permissive answer it allows and the org's
+ * is therefore a floor no layer below it can loosen — attributed to the layer
+ * that set it (on a tie the first layer named keeps it, the least specific
+ * scope, as `intersectBoundaries` does). No layer set one: the built-in
+ * `write`, attributed to `built-in`. Pure over the same layers `intersectBoundaries` takes.
+ */
+export function effectiveConfirm(layers: readonly ScopedBoundary[]): EffectiveConfirm {
+  let out: EffectiveConfirm | undefined;
+  for (const { scope, boundary } of layers) {
+    if (boundary.confirm !== undefined && (!out || CONFIRM_ORDER[boundary.confirm] < CONFIRM_ORDER[out.value])) {
+      out = { value: boundary.confirm, scope };
+    }
+  }
+  return out ?? { value: BUILT_IN_CONFIRM, scope: "built-in" };
+}
+
 /**
  * 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

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

@@ -82,6 +82,10 @@ export const POLICY: readonly Rule[] = [
   { action: "friction:write", resource: "command", when: [grant("friction:write")] },
 
   // ── costs ────────────────────────────────────────────────────────────────
+  // `costs by` reads the snapshot's arithmetic: what every browser session
+  // holds (every group's read) and what a Slack user or a token is granted —
+  // never a chat baseline, since a by-user table names who spent what.
+  { action: "costs:read", resource: "command", when: [grant("costs:read")] },
   // `costs snapshot` reads both billing providers and replaces what every
   // viewer of the costs page sees: the grant, never a baseline (the admins'
   // `all` and a named `grants` entry hold it).

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

@@ -0,0 +1,313 @@
+// Every wall clock in Switchboard as one table (docs/decisions/0046; docs/reference/specs/harness-pi.md
+// item 15; docs/reference/specs/agent-ship.md item 8). A budget is a LEASE a
+// parent carves from its own remainder, never a constant a file holds on its
+// own: a preset ASKS for a lease and does useful work above a FLOOR; a parent
+// that runs a loop holds back a RESERVE, derived from the floors and the
+// provisioning of every round that must still follow, plus the merge wait's
+// floor; and the lease covers everything the run does, the loop, the write-up
+// and the post-step, each an ALLOWANCE named here. The registry reads its
+// `maxMinutes` and `maxTurns` from this module and `budgets.check.test.ts`
+// asserts the fits, so a number that breaks another's assumption is a red
+// build. `carve` is called by the ship coordinator for every round (agent-ship
+// item 8), `fit` by the config validator at load and by the fork over a clipped
+// request, and `carveChildOfParent` by the conductor's spawn.
+//
+// Deliberately free of node: imports and of the agent registry, so the
+// Workflow-driven coordinator and the deploy Workers can bundle it — the
+// dependency runs registry → budgets, never the reverse.
+
+export const MINUTE_MS = 60_000;
+
+/** The presets that run the tool loop, and the one pipeline preset. */
+export const LOOP_PRESETS = ["general", "coding", "review", "research", "explore", "conductor"] as const;
+export type LoopPreset = (typeof LOOP_PRESETS)[number];
+export type Preset = LoopPreset | "ship";
+
+/** What each preset asks for when nothing above it is tighter, in minutes. The
+ *  pipeline's (`ship`) is the wall clock one segment of its loop runs under;
+ *  a deployment's `ship.maxMinutes` replaces it, held to `fit` below. */
+export const ASKS: Readonly<Record<Preset, number>> = {
+  general: 5,
+  coding: 45,
+  review: 25,
+  ship: 120,
+  research: 8,
+  explore: 120,
+  conductor: 120,
+};
+
+/** The rounds a ship loop is made of. `fix` is a coding child handed the
+ *  review's findings; `merge` is the runner's wait on the guards. */
+export type RoundKind = "coding" | "review" | "fix" | "merge";
+
+/** The least lease in which a round does useful work, in minutes. A carve that
+ *  falls under the floor is refused rather than dispatched: a two-minute
+ *  review or fix costs an attach and a model turn and finishes nothing.
+ *  Review's is the ledger's 90th percentile of completed reviews (5.1 min over
+ *  181); coding's and the merge wait's are guesses until the ledger says. */
+export const PRESET_FLOORS: Readonly<Record<LoopPreset, number>> = {
+  general: 2,
+  coding: 10,
+  review: 5,
+  research: 3,
+  explore: 15,
+  conductor: 15,
+};
+export const FLOORS: Readonly<Record<RoundKind, number>> = {
+  coding: PRESET_FLOORS.coding,
+  fix: PRESET_FLOORS.coding,
+  review: PRESET_FLOORS.review,
+  merge: 10,
+};
+
+/** The merge wait's own ask: how long the runner waits on the guards at most
+ *  when the remainder allows it. */
+export const MERGE_WAIT_ASK_MINUTES = 60;
+
+/** The ship runner's waits, in minutes: the margin a child's wait allows past
+ *  its budget, the slice a wait is asked in, the merge door's re-ask cadence,
+ *  and the pause before a busy spawn is asked again. */
+export const SHIP_WAIT = { marginMinutes: 5, chunkMinutes: 5, mergeChunkMinutes: 5, busyRetryMinutes: 2 } as const;
+
+/** The named amounts a lease holds back, in minutes. Each stands for a step
+ *  every run or round pays: `provision` is attach and restore before the
+ *  harness's clock starts; `writeUp` is the final answer after the loop ends;
+ *  `commandWriteUp` is what the last command leaves for that answer; `execCall`
+ *  is the exec client's wait past a command's own budget; `bearerGrace` is how
+ *  far past the lease the model bearer stays valid for the last call's tail. */
+export const ALLOWANCES = {
+  provision: 3,
+  writeUp: 3,
+  commandWriteUp: 1,
+  execCall: 0.5,
+  bearerGrace: 1,
+} as const;
+
+/** The post-step turn a preset runs after its loop, in minutes: the coding
+ *  run's description turn, the review's verdict turn, none for the rest. */
+export const POST_STEP_MINUTES: Readonly<Record<Preset, number>> = {
+  coding: 5,
+  review: 3,
+  general: 0,
+  research: 0,
+  explore: 0,
+  conductor: 0,
+  ship: 0,
+};
+
+/** The post-step allowance of a preset named by its def's `name`: a name
+ *  outside the table (a test's, a command run's) runs no post-step. */
+export function postStepMinutes(preset: string): number {
+  return (POST_STEP_MINUTES as Readonly<Record<string, number>>)[preset] ?? 0;
+}
+
+/** The post-step turn's lease, in minutes (fractional when the remainder is:
+ *  the harness turns it back into ms): the preset's allowance, or the lease's
+ *  remainder when that is less — never under a minute, so a turn the loop's
+ *  write-up crowded still gets its one chance. The bearer's grace covers that
+ *  floor for a turn that starts at or before the lease's end; a turn that
+ *  starts later runs on a bearer that may expire under it, and its refused
+ *  call fails soft — the run's answer already stands. Without a remainder
+ *  (no harness session says) the allowance stands. */
+export function postStepLease(preset: string, remainingMs: number | undefined): number {
+  const allowance = postStepMinutes(preset);
+  if (remainingMs === undefined) return allowance;
+  return Math.min(allowance, Math.max(1, remainingMs / MINUTE_MS));
+}
+
+/** A follow-up turn's lease, in ms: the lesser of what it asks and what the
+ *  run's lease still holds, never under a minute — the grace covers that floor
+ *  when the turn starts by the lease's end; later, the bearer may expire under
+ *  the turn and its call is refused, failing soft. */
+export function turnLeaseMs(askMinutes: number, remainingMs: number): number {
+  return Math.min(askMinutes * MINUTE_MS, Math.max(MINUTE_MS, remainingMs));
+}
+
+/** The wrap-up warning's place before the loop's end: three minutes, or a
+ *  quarter of the loop when the loop is shorter than twelve. */
+export const WRAP_UP_WARNING = { minutes: 3, fraction: 0.25 } as const;
+
+/** The clocks a harness keeps for one lease (docs/reference/specs/harness-pi.md
+ *  items 6 and 15). The lease ENDS at `deadline`; the LOOP ENDS at `loopEnd`,
+ *  the write-up allowance and the preset's post-step earlier, so both run
+ *  inside the lease; the WARNING is steered at `warnAt`; the write-up is
+ *  BOUNDED by `finaleMs`. A follow-up turn on the session (`kind: "turn"`)
+ *  holds nothing back — its deliverable is a tool call, not a write-up — and
+ *  its loop ends at its deadline. A lease shorter than its hold-back has no
+ *  loop time: the loop ends at its start, never before it. */
+export interface LoopClock {
+  startedAt: number;
+  deadline: number;
+  loopEnd: number;
+  warnAt: number;
+  finaleMs: number;
+}
+
+export function loopClock(
+  startedAt: number,
+  remainingMs: number,
+  preset: string,
+  kind: "loop" | "turn" = "loop",
+): LoopClock {
+  const deadline = startedAt + remainingMs;
+  const holdBackMs = kind === "loop" ? (ALLOWANCES.writeUp + postStepMinutes(preset)) * MINUTE_MS : 0;
+  const loopEnd = Math.max(startedAt, deadline - holdBackMs);
+  const warnAt =
+    loopEnd - Math.min(WRAP_UP_WARNING.minutes * MINUTE_MS, (loopEnd - startedAt) * WRAP_UP_WARNING.fraction);
+  return { startedAt, deadline, loopEnd, warnAt, finaleMs: ALLOWANCES.writeUp * MINUTE_MS };
+}
+
+/** When a run's model-proxy bearer expires: the lease's end plus the grace
+ *  (docs/reference/specs/model-proxy.md item 2). */
+export function bearerExpiresAt(leaseEndsAt: number): number {
+  return leaseEndsAt + ALLOWANCES.bearerGrace * MINUTE_MS;
+}
+
+/** The bearer's expiry as the mint at provisioning sets it, before the lease
+ *  has started: the provisioning allowance, the lease and the grace — replaced
+ *  by `bearerExpiresAt` the moment the harness starts the lease. */
+export function provisionalBearerExpiresAt(now: number, leaseMinutes: number): number {
+  return now + (ALLOWANCES.provision + leaseMinutes + ALLOWANCES.bearerGrace) * MINUTE_MS;
+}
+
+/** The per-command bash budget's rows: the default when a call names none, the
+ *  ceiling a call may raise it to, and the floor under which a number is a
+ *  typo (docs/reference/specs/execution.md item 11). */
+export const BASH_COMMAND = { defaultMinutes: 5, maxMinutes: 20, minMs: 1_000 } as const;
+
+/** 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/harness-pi.md item 15). */
+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 pipeline's loop as the config allows it: `maxRounds` counts review rounds. */
+export interface Loop {
+  maxRounds: number;
+}
+
+/** A round's position in its loop: its kind and its index, so the reserve is
+ *  the rounds after that index, never a table keyed by kind alone. */
+export interface RoundPosition {
+  kind: RoundKind;
+  index: number;
+}
+
+/** The rounds of a loop in order: the coding round, then a review and, after
+ *  every review but the last, a fix, then the merge wait. */
+export function loopRounds(loop: Loop): RoundKind[] {
+  const rounds: RoundKind[] = ["coding"];
+  for (let i = 0; i < loop.maxRounds; i++) {
+    rounds.push("review");
+    if (i < loop.maxRounds - 1) rounds.push("fix");
+  }
+  rounds.push("merge");
+  return rounds;
+}
+
+/** Where a round sits in `loopRounds`: the coding round first; review round
+ *  `n` (counted from 1) and the fix that follows it at `2n − 1` and `2n`; the
+ *  merge wait last. The ship coordinator numbers its rounds this way, so the
+ *  reserve it carves with is the one the fit assumed. */
+export function loopPosition(loop: Loop, kind: RoundKind, n = 0): number {
+  switch (kind) {
+    case "coding":
+      return 0;
+    case "review":
+      return 2 * n - 1;
+    case "fix":
+      return 2 * n;
+    case "merge":
+      return 2 * loop.maxRounds;
+  }
+}
+
+/** A child spawned outside any loop (a conductor's): the parent's whole
+ *  remainder in whole minutes, refused under the child preset's floor — a
+ *  child under its floor costs a thread and a model turn and finishes nothing. */
+export function carveChildOfParent(
+  remainingMs: number,
+  preset: LoopPreset,
+): { kind: "carved"; minutes: number } | { kind: "refused"; reason: "under floor"; minutes: number; floor: number } {
+  const minutes = Math.max(0, Math.floor(remainingMs / MINUTE_MS));
+  const floor = PRESET_FLOORS[preset];
+  if (minutes < floor) return { kind: "refused", reason: "under floor", minutes, floor };
+  return { kind: "carved", minutes };
+}
+
+/** The minutes a round holds back for what must follow it in the loop: the
+ *  floor plus provisioning of every later review and fix, and the merge
+ *  wait's floor. A merge holds nothing back; a round with no loop (a
+ *  conductor's child) holds nothing back either. */
+export function reserveMinutes(
+  round: RoundPosition,
+  loop: Loop | undefined,
+  floors: Readonly<Record<RoundKind, number>> = FLOORS,
+): number {
+  if (!loop) return 0;
+  let reserve = 0;
+  for (const kind of loopRounds(loop).slice(round.index + 1)) {
+    reserve += kind === "merge" ? floors.merge : floors[kind] + ALLOWANCES.provision;
+  }
+  return reserve;
+}
+
+/** What a round asks for: the preset's ask for a coding or fix round, the
+ *  review's for a review, the merge wait's own for the merge. */
+export function roundAskMinutes(kind: RoundKind): number {
+  switch (kind) {
+    case "coding":
+    case "fix":
+      return ASKS.coding;
+    case "review":
+      return ASKS.review;
+    case "merge":
+      return MERGE_WAIT_ASK_MINUTES;
+  }
+}
+
+/** A carve's result: the minutes with what bounded them (`ask` when the round
+ *  got its whole ask, `parent` when the remainder minus the reserve was
+ *  tighter) and what the parent holds back, or a refusal when the minutes the
+ *  remainder leaves fall under the round's floor. */
+export type Carve =
+  | { kind: "carved"; minutes: number; boundedBy: "ask" | "parent"; holds: number }
+  | { kind: "refused"; reason: "under floor"; minutes: number; floor: number; holds: number };
+
+/** The only place a round's minutes are computed: the parent's remainder in
+ *  whole minutes minus the round's reserve, capped at the round's ask, refused
+ *  under the round's floor. `loop` is undefined for a child outside any loop. */
+export function carve(remainingMs: number, round: RoundPosition, loop: Loop | undefined): Carve {
+  const holds = reserveMinutes(round, loop);
+  const ask = roundAskMinutes(round.kind);
+  const headroom = Math.floor(remainingMs / MINUTE_MS) - holds;
+  const minutes = Math.min(ask, headroom);
+  const floor = FLOORS[round.kind];
+  // A refusal reports what the remainder left, never a negative number.
+  if (minutes < floor) return { kind: "refused", reason: "under floor", minutes: Math.max(0, minutes), floor, holds };
+  return { kind: "carved", minutes, boundedBy: minutes === ask ? "ask" : "parent", holds };
+}
+
+/** A pipeline's wall clock and its loop: what `fit` judges. */
+export interface Pipeline extends Loop {
+  maxMinutes: number;
+}
+
+/** The fit: a pipeline holds its first child at its ask and every later round
+ *  at its floor — `provision + ask(coding) + reserve(coding, loop) ≤
+ *  maxMinutes`. Asserted at verify over the registry, at config load over the
+ *  deployment's `ship` block (`validateShip`), and at the fork over a request a
+ *  boundary or a `budget:` directive clipped. `need` is the sum a refusal names. */
+export function fit(pipeline: Pipeline): { ok: boolean; need: number; have: number } {
+  const need = ALLOWANCES.provision + ASKS.coding + reserveMinutes({ kind: "coding", index: 0 }, pipeline);
+  return { ok: pipeline.maxMinutes >= need, need, have: pipeline.maxMinutes };
+}

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

@@ -54,7 +54,6 @@ import {
   type ShipCaps,
   type StepReturn,
   type UnitEnding,
-  type UnitPipelineInput,
   type UnitPipelineState,
 } from "../ship/coordinator.js";
 import { checksSettledEventType, isCoordinatorUnit, runFinishedEventType, type CoordinatorUnit } from "./contract.js";
@@ -170,7 +169,6 @@ interface PlanFacts {
   repo: string;
   base: string;
   caps: ShipCaps;
-  childMinutes: UnitPipelineInput["childMinutes"];
   units: CoordinatorUnit[];
 }
 
@@ -184,12 +182,6 @@ function readPlan(a: BotAnswer): PlanFacts {
   if (typeof b.repo !== "string" || typeof b.base !== "string") throw new UnreadableAnswer("plan", a, "repo and base");
   if (!isMinutes(b.caps) || typeof b.caps.maxRounds !== "number" || typeof b.caps.maxMinutes !== "number")
     throw new UnreadableAnswer("plan", a, "caps");
-  if (
-    !isMinutes(b.childMinutes) ||
-    typeof b.childMinutes.coding !== "number" ||
-    typeof b.childMinutes.review !== "number"
-  )
-    throw new UnreadableAnswer("plan", a, "childMinutes");
   const units: unknown = b.units;
   if (!Array.isArray(units) || !units.every(isCoordinatorUnit)) throw new UnreadableAnswer("plan", a, "units");
   return {
@@ -204,7 +196,6 @@ function readPlan(a: BotAnswer): PlanFacts {
     repo: b.repo,
     base: b.base,
     caps: { maxRounds: b.caps.maxRounds, maxMinutes: b.caps.maxMinutes },
-    childMinutes: { coding: b.childMinutes.coding, review: b.childMinutes.review },
     units,
   };
 }
@@ -486,7 +477,6 @@ async function runUnit(
       repo: plan.repo,
       base: plan.base,
       caps: plan.caps,
-      childMinutes: plan.childMinutes,
       // The instance's field decides who merges (record 0031's merge grant),
       // carried here by the plan route: the hand-off wrote `runner` on a
       // seeded plan and `person` on a task, and the door re-checks it — the