@coreplane/switchboard 1.207.1 → 1.209.0

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

@@ -278,20 +278,20 @@ workspaceDir: ./workspaces
 #     tokenEnv: MEMORY_TOKEN    # env var holding the Worker's bearer (default)
 
 # agent:ship pipeline caps (docs/reference/specs/agent-ship.md). `agent:ship in owner/repo:
-# <task>` runs the coding → review → fix loop to LGTM as one pipeline: at most
+# <task>` hands the coding → review → fix loop to LGTM to the plan runner — the
+# ShipCoordinator Workflow in the bot Worker, whose rounds are child runs — which
+# needs the `coordinator` ingress entry, its grants, run history on the state
+# Worker and PUBLIC_BASE_URL (docs/how-to/turn-features-on-and-off.md); without
+# them the request is refused naming what is missing. Per unit: at most
 # `maxRounds` review rounds and `maxMinutes` minutes of wall clock — whichever
-# hits first ends the loop, and each child round's own budget is clipped to the
-# remaining pipeline time. `maxMinutes` is the ship preset's declared budget:
-# a channel or user `boundary.maxMinutes` and a per-message `budget:` directive
-# clip it like any preset's, and the card says so. Defaults shown; both must be
-# integers >= 1.
+# hits first ends the unit, and each child round's own budget is clipped to the
+# remaining time. `maxMinutes` is the ship preset's declared budget: a channel or
+# user `boundary.maxMinutes` and a per-message `budget:` directive clip it like
+# any preset's, and the card says so. Defaults shown; both must be integers >= 1;
+# any other key under `ship` fails the load by name.
 # ship:
-#   maxRounds: 3      # review rounds per pipeline
+#   maxRounds: 3      # review rounds per unit
 #   maxMinutes: 120   # the ship preset's wall-clock budget in minutes (the registry's default)
-#   coordinator: false # true hands every agent:ship request to the plan runner — the ShipCoordinator
-#                      # Workflow in the bot Worker — instead of the in-process round loop; needs the
-#                      # `coordinator` ingress entry, its grant, run history on the state Worker and
-#                      # PUBLIC_BASE_URL (see docs/how-to/turn-features-on-and-off.md)
 
 # The fan-out cap a spawning run meets (docs/reference/specs/agent-conductor.md).
 # `agent:conductor` starts child runs as the person who asked — each an

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.207.1",
+  "version": "1.209.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.207.1",
+      "version": "1.209.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -18999,7 +18999,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.207.1",
+      "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.207.1",
+  "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.207.1",
-  "commit": "a5e85d6a364f558fdf079ec32e85eb6deadf5033",
-  "builtAt": "2026-09-14T01:09:34.713Z"
+  "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/assets/src/core/coordinator/contract.ts

@@ -145,6 +145,11 @@ export interface CoordinatorUnit {
   /** The unit's board issue in the repository, when one titled by the unit id exists — the handoff's destination. */
   issue?: number;
   pr?: { number: number; url: string };
+  /** Resume at review (agent-ship item 10): the open pull request of ship's own
+   *  the requester named, so the unit's pipeline opens at its first review round
+   *  — no pre-check, no branch, no round 0. A task string's row only; written by
+   *  the hand-off, read by the driver into the machine's input. */
+  resume?: { pr: number; headSha?: string; url?: string };
   /** The round boundaries the coordinator reported, oldest first (the `ship_round` vocabulary). */
   rounds: Array<{ index: number; agent: string; outcome: string; at: number }>;
   /** How the unit ended: the ending's kind and the thread's report, when it has. */
@@ -163,6 +168,11 @@ const isOptionalText = (v: unknown): boolean => v === undefined || isText(v);
 const isFinite = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
 const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null;
 const isPr = (v: unknown): boolean => isObject(v) && isFinite(v.number) && isText(v.url, 2048);
+const isResume = (v: unknown): boolean =>
+  isObject(v) &&
+  isFinite(v.pr) &&
+  (v.headSha === undefined || isText(v.headSha)) &&
+  (v.url === undefined || isText(v.url, 2048));
 
 /** Structural check on a record from outside the process (a Worker response, an HTTP body). */
 export function isCoordinatorInstance(v: unknown): v is CoordinatorInstance {
@@ -194,6 +204,7 @@ export function isCoordinatorUnit(v: unknown): v is CoordinatorUnit {
   if (!isOptionalText(r.threadKey) || !isOptionalText(r.sourceUrl)) return false;
   if (r.issue !== undefined && !isFinite(r.issue)) return false;
   if (r.pr !== undefined && !isPr(r.pr)) return false;
+  if (r.resume !== undefined && !isResume(r.resume)) return false;
   if (
     !Array.isArray(r.rounds) ||
     r.rounds.length > MAX_ROUNDS ||

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

@@ -233,7 +233,18 @@ function readRecordReturn(step: string, a: BotAnswer): StepReturn {
   // The typed artifacts as the bot's record carries them — shape-checked where
   // they were written (the run record's validator), read here as they are.
   const facts = run as unknown as Omit<Extract<ChildFacts, { finished: true }>, "finished" | "status">;
-  const { finalReply, pr, headSha, description, verdict, reviewPosted, reviewHead, dispositions, handoff } = facts;
+  const {
+    finalReply,
+    pr,
+    headSha,
+    description,
+    verdict,
+    reviewPosted,
+    reviewPostReason,
+    reviewHead,
+    dispositions,
+    handoff,
+  } = facts;
   return {
     type: "read-record",
     step,
@@ -246,6 +257,7 @@ function readRecordReturn(step: string, a: BotAnswer): StepReturn {
       ...(description !== undefined ? { description } : {}),
       ...(verdict !== undefined ? { verdict } : {}),
       ...(reviewPosted !== undefined ? { reviewPosted } : {}),
+      ...(reviewPostReason !== undefined ? { reviewPostReason } : {}),
       ...(reviewHead !== undefined ? { reviewHead } : {}),
       ...(dispositions !== undefined ? { dispositions } : {}),
       ...(handoff !== undefined ? { handoff } : {}),
@@ -399,6 +411,10 @@ async function runUnit(
   const start = readUnitStart(
     answerOf("unit-start", await step.do(`${unit}/start`, STEP_CONFIG, () => call(bot, "unit-start", tag))),
   );
+  // A resume at review (agent-ship item 10) rides the unit's row: the pull
+  // request of ship's own the requester named opens the pipeline at its first
+  // review round, with no pre-check, no branch and no round 0.
+  const resume = plan.units.find((u) => u.unit === unit)?.resume;
   let state: UnitPipelineState = openUnitPipeline(
     {
       unit: { id: unit, branch: node.branch },
@@ -411,6 +427,7 @@ async function runUnit(
       // approved at its head and the checks are green; any other branch — a
       // task string's ship branch — waits for a person.
       merge: parsePlanBranch(node.branch) !== undefined ? "runner" : "person",
+      ...(resume !== undefined ? { resume } : {}),
     },
     start.at,
   );
@@ -425,10 +442,14 @@ async function runUnit(
         const body = { ...tag, index: note.index, agent: note.agent, outcome: note.outcome };
         await step.do(`${unit}/note/${++notes}`, STEP_CONFIG, () => call(bot, "round", body));
       } else {
+        // The last coding child's run is named so the bot can put its handoff
+        // — the deviations it recorded — on the unit's board issue beside the
+        // ending (agent-ship item 14).
         const body = {
           ...tag,
           ending: { kind: note.ending.kind, report: renderUnitReport(state) },
           ...(state.pr !== undefined ? { pr: state.pr } : {}),
+          ...(state.lastCodingRunId !== undefined ? { codingRunId: state.lastCodingRunId } : {}),
         };
         await step.do(`${unit}/end`, STEP_CONFIG, () => call(bot, "unit-end", body));
       }

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

@@ -259,6 +259,46 @@ export function isReviewVerdictShape(v: unknown): v is ReviewVerdict {
   return true;
 }
 
+/** How a review run's post-step ended, as the run's record carries it
+ *  (docs/reference/specs/agent-review.md item 18; run-history item 2): the verdict
+ *  landed on a named pull request pinned to `head` (the verdict kind rides when
+ *  one was submitted — a review that posted without a verdict posts the
+ *  no-verdict line), or nothing landed and `reason` says why — a guard's
+ *  refusal, an opt-out, no pull request, GitHub's own error. A coordinator's
+ *  `read-record` answers `reviewPosted` from this before it asks GitHub, whose
+ *  review list can lag a post it accepted a second ago. */
+export type ReviewPost =
+  | { posted: true; target: { repo: string; number: number }; head: string; verdict?: ReviewVerdictKind }
+  | { posted: false; reason: string };
+
+const REVIEW_POST_HEAD = /^[0-9a-f]{7,40}$/;
+
+/** Structural check on a review post read back from a stored record: a posted
+ *  outcome names its pull request and a 7-to-40-hex head, its verdict (when
+ *  present) a known kind; a skipped one carries a string reason. */
+export function isReviewPostShape(v: unknown): v is ReviewPost {
+  if (!isRecordLike(v)) return false;
+  if (v.posted === false) return typeof v.reason === "string";
+  if (v.posted !== true) return false;
+  const target = v.target;
+  if (
+    !isRecordLike(target) ||
+    typeof target.repo !== "string" ||
+    typeof target.number !== "number" ||
+    !Number.isInteger(target.number) ||
+    target.number <= 0
+  )
+    return false;
+  if (typeof v.head !== "string" || !REVIEW_POST_HEAD.test(v.head)) return false;
+  return v.verdict === undefined || VERDICT_KINDS.includes(v.verdict as string);
+}
+
+/** The skip's reason through the redaction seam (it may carry GitHub's own
+ *  words); a posted outcome has no free text and is returned as it is. */
+export function redactReviewPost(post: ReviewPost, redact: (s: string) => string = redactSecrets): ReviewPost {
+  return post.posted ? post : { posted: false, reason: redact(post.reason) };
+}
+
 /** Structural check on a disposition set read back from a stored record. */
 export function isFindingDispositionsShape(v: unknown): v is FindingDisposition[] {
   return (

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

@@ -110,7 +110,15 @@ export type RunNoteKind =
    *  request would target (docs/reference/specs/pr-description.md item 5) —
    *  the summary names the branch. Published by the post-step, so a unit
    *  that ends without a pull request says why on the record and the card. */
-  | "pr_not_opened";
+  | "pr_not_opened"
+  /** A review run's post-step posted nothing to the pull request — a guard's
+   *  refusal, an opt-out, no pull request resolved, GitHub's own error — and
+   *  the summary names the pull request (when one was resolved) and the
+   *  reason (docs/reference/specs/agent-review.md item 18). Published by the
+   *  post-step beside the thread's Slack-only note, so the record says the
+   *  verdict is Slack-only and a coordinator reading it never asks GitHub
+   *  for a review that was never sent. */
+  | "review_not_posted";
 
 /** 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). */
@@ -130,6 +138,7 @@ export const RUN_NOTE_KINDS = [
   "description_turn",
   "cold_sandbox",
   "pr_not_opened",
+  "review_not_posted",
 ] as const satisfies readonly RunNoteKind[];
 type _EveryKindListed = [RunNoteKind] extends [(typeof RUN_NOTE_KINDS)[number]] ? true : never;
 const _everyKindListed: _EveryKindListed = true;
@@ -438,6 +447,25 @@ export type RunEvent =
    *  run record carries the PR URL as a fact of the run rather than only the
    *  channel reply's projection of it. Additive: unknown → ignored. */
   | { type: "pr_opened"; url: string; number: number; created: boolean; seq?: number; at?: number }
+  /** The review post-step's outcome when the verdict landed
+   *  (docs/reference/specs/agent-review.md item 18): the pull request it was
+   *  posted to, the head it was pinned to (the carried head after a rebase,
+   *  item 12) and the verdict kind when one was submitted. Published by the
+   *  post-step straight to the registry BEFORE the stream finishes — the
+   *  post-step runs inside the run loop, like the coding one — so the record
+   *  carries the post as a fact of the run and a coordinator woken by the
+   *  finish reads it there instead of asking GitHub, whose review list can
+   *  lag the post it just accepted. A post that did not land is a
+   *  `review_not_posted` note. Additive: unknown → ignored. */
+  | {
+      type: "review_posted";
+      repo: string;
+      number: number;
+      head: string;
+      verdict?: "approve" | "request_changes";
+      seq?: number;
+      at?: number;
+    }
   /** One `agent:ship` round boundary (docs/reference/specs/agent-ship.md item 12): the
    *  pipeline publishes a `started` event when a round's child is dispatched
    *  and one settle event when its outcome is known (`ShipRoundOutcome`), so

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

@@ -370,7 +370,7 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
   // final answer (`answer`) — are the run's story, not its steps: none counts
   // toward `eventCount`.
   let narrativeEvents = 0;
-  let sideFactEvents = 0; // skill_use / review_artifact / pr_description / pr_opened / ship_round: facts about the run, not steps
+  let sideFactEvents = 0; // skill_use / review_artifact / pr_description / pr_opened / review_posted / ship_round: facts about the run, not steps
   let spanEvents = 0; // span_start / span_end (docs/reference/specs/tracing.md): timing records, not steps
   let wrapUp: { index: number; at?: number } | undefined;
   events.forEach((ev, index) => {
@@ -385,14 +385,15 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
     }
     // Side facts about the run, not steps: skill_use rides beside a use_skill
     // call that already produced its own tool pair; review_artifact,
-    // pr_description, pr_opened and the ship_round boundaries are published
-    // by the dispatcher/pipeline outside the model loop entirely. Counting
-    // any of them would distort the story.
+    // pr_description, pr_opened, review_posted and the ship_round boundaries
+    // are published by the dispatcher/pipeline outside the model loop
+    // entirely. Counting any of them would distort the story.
     if (
       ev.type === "skill_use" ||
       ev.type === "review_artifact" ||
       ev.type === "pr_description" ||
       ev.type === "pr_opened" ||
+      ev.type === "review_posted" ||
       ev.type === "ship_round"
     ) {
       sideFactEvents++;

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

@@ -4,9 +4,11 @@ import type { RunEvent } from "./runEvents.js";
 import { isHeadMaterial, isSpanRecord } from "./runEvents.js";
 import { isHandoffShape, type Handoff } from "./ship/handoff.js";
 import {
+  type FindingDisposition,
   isFindingDispositionsShape,
+  isReviewPostShape,
   isReviewVerdictShape,
-  type FindingDisposition,
+  type ReviewPost,
   type ReviewVerdict,
 } from "./reviewVerdict.js";
 import { IDEMPOTENCY_KEY_PATTERN, INSTANCE_ID_PATTERN } from "./coordinator/contract.js";
@@ -114,6 +116,12 @@ export interface RunRecord {
   /** The head a review run reviewed and posted against (7 to 40 lowercase hex),
    *  after the settle; present only on a review run that pinned one. */
   reviewHead?: string;
+  /** How the review run's post-step ended (docs/reference/specs/agent-review.md
+   *  item 18): the verdict posted to a named pull request at a pinned head, or
+   *  not posted with the reason — what a coordinator's `read-record` answers
+   *  `reviewPosted` from before it asks GitHub. Present only on a review run
+   *  that reached its post-step; absent on records written before it existed. */
+  reviewPost?: ReviewPost;
   /** The dispositions a fix round submitted through `submit_dispositions`
    *  (docs/reference/specs/agent-ship.md item 6), the last call's set, redacted;
    *  present only on a coding run dispatched as a fix round that submitted one. */
@@ -502,6 +510,7 @@ export function isRunRecord(v: unknown): v is RunRecord {
   if (r.reviewHead !== undefined && (typeof r.reviewHead !== "string" || !REVIEW_HEAD_PATTERN.test(r.reviewHead)))
     return false;
   if (r.dispositions !== undefined && !isFindingDispositionsShape(r.dispositions)) return false;
+  if (r.reviewPost !== undefined && !isReviewPostShape(r.reviewPost)) return false;
   if (r.profile !== undefined && !isRunProfileRecord(r.profile)) return false;
   // A parent is named by a run id (item 46): the same shape as the record's own.
   if (r.parentRunId !== undefined && (typeof r.parentRunId !== "string" || !RUN_ID_PATTERN.test(r.parentRunId)))

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

@@ -79,6 +79,10 @@ export interface ChildContract {
   issue: { repo: string; number: number } | undefined;
 }
 
+/** The PR-title gate's name, exported so another module can name the same
+ *  gate without a copied string (`npm run check:pr-title`; CI's `title` check). */
+export const PR_TITLE_GUARD = "check:pr-title";
+
 /** The guards a child may not weaken (AGENTS.md's Commands table), one line each on what they refuse. */
 export const GUARDS: readonly Guard[] = [
   {
@@ -96,6 +100,11 @@ export const GUARDS: readonly Guard[] = [
     refuses:
       "a new imprint in the public tree (a company, a person, a tracker reference, a plan id, a platform id, a date); the recorded list only shrinks",
   },
+  {
+    name: PR_TITLE_GUARD,
+    refuses:
+      "a title whose type, scope or grammar is not the changelog line, the scope being one of the code map's Areas",
+  },
   {
     name: "decisions:check",
     refuses:

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

@@ -4,11 +4,10 @@
 // Workflow instance in the bot's shim Worker with no model turn and no
 // credential — decides between the steps it asks the bot for. The Workflow
 // asks `nextAction`, performs it (a bot route, a `waitForEvent`, a sleep) and
-// feeds the answer to `applyReturn`; everything the in-process round loop
-// decides today (`runShipPipeline`: which round is next, what a child's end
-// means, when a cap ends the pipeline, when the pull request is merge-ready)
-// is decided here over the step returns instead, so the same endings hold
-// with the loop's process gone.
+// feeds the answer to `applyReturn`; everything the pipeline decides — which
+// round is next, what a child's end means, when a cap ends the pipeline, when
+// the pull request is merge-ready — is decided here over the step returns, so
+// the endings hold with no process of the pipeline's own to die.
 //
 // Two machines, both pure. The plan cursor walks a plan record's unit graph:
 // which units are ready (their dependencies merged), which one a failure
@@ -345,8 +344,12 @@ export type ChildFacts =
       description?: boolean;
       /** A review child's verdict. */
       verdict?: { verdict: ReviewVerdictKind; summary?: string; findings: Finding[] };
-      /** Whether the review child's verdict landed on the pull request. */
+      /** Whether the review child's verdict landed on the pull request — the
+       *  child's own record of its post, or GitHub's review list when the
+       *  record is silent (http-ingress.md item 9). */
       reviewPosted?: boolean;
+      /** Why the child recorded no post, when it recorded one it chose or failed. */
+      reviewPostReason?: string;
       reviewHead?: string;
       /** A fix child's dispositions. */
       dispositions?: FindingDisposition[];
@@ -375,7 +378,7 @@ export type StepReturn =
   | { type: "merge"; step: string; outcome: "pending" | "refused"; reason: string; at: number }
   | { type: "sleep"; step: string };
 
-/** How one unit's pipeline ended — the truthful vocabulary the in-process loop
+/** How one unit's pipeline ended — the truthful vocabulary the ship pipeline
  *  has, plus the merge's own: `merged` by the runner, or found merged (`by:
  *  other` — a person's merge, or an earlier attempt's that died after it, so
  *  the runner merged nothing), `merge_ready` for a person, `merge_refused` by
@@ -512,7 +515,7 @@ function waitSliceMs(clock: number, until: number): number {
 }
 
 /** The child's budget: its preset's own, clipped to the pipeline's remaining
- *  wall clock (the in-process loop's `clip`), never under the two minutes a
+ *  wall clock (agent-ship item 8's clip), never under the two minutes a
  *  spawn accepts. */
 function budgetMinutesFor(s: UnitPipelineState, preset: ChildPreset): number {
   return Math.max(2, Math.min(s.input.childMinutes[preset], Math.floor(remainingMs(s) / MIN)));
@@ -606,7 +609,7 @@ const roundNote = (round: RoundRef, outcome: ShipRoundOutcome): CoordinatorNote
   outcome,
 });
 
-/** Start a round if the reservation holds (the in-process loop's check: a
+/** Start a round if the reservation holds (agent-ship item 8's check: a
  *  child clipped under the reserve cannot do useful work). */
 function enterRound(s: UnitPipelineState, round: RoundRef, notes: CoordinatorNote[] = []): Transition {
   const remaining = remainingMs(s);
@@ -720,13 +723,15 @@ function settleReview(
   const notes = [roundNote(round, verdict.verdict)];
   if (verdict.verdict === "approve") {
     // Merge-ready stands on the POSTED approval: an approve whose post did
-    // not land left no approving review on the pull request.
+    // not land left no approving review on the pull request. The reason is
+    // the child's own when it recorded one; how to continue is the report's
+    // re-issue line, in the runner's words (`renderUnitReport`).
     if (facts.reviewPosted === false)
       return end(
         next,
         {
           kind: "aborted",
-          reason: `⚠️ The review approved, but the approval could not be posted — the pull request carries no approving review. Re-run ship with the pull request URL to retry the approval.`,
+          reason: `⚠️ The review approved, but the approval could not be posted${facts.reviewPostReason !== undefined ? ` (${facts.reviewPostReason})` : ""} — the pull request carries no approving review.`,
           round,
           reviewRounds: next.reviewRounds,
         },
@@ -1030,7 +1035,7 @@ function splitReport(s: UnitPipelineState): string {
   return lines.join("\n");
 }
 
-/** The thread's report for a unit's ending — the in-process loop's own words
+/** The thread's report for a unit's ending — the ship pipeline's own words
  *  for the endings it has, and the merge's for the ones it gains. */
 export function renderUnitReport(s: UnitPipelineState): string {
   const e = s.ending;

package/dist/assets/src/core/trace/streamSpans.ts

@@ -45,6 +45,7 @@ export const STREAMED_SPANS = [
   "run.description_turn",
   "run.observe_workspace",
   "run.pr_post_step",
+  "run.review_post_step",
   "run.reading_diff_join",
   "run.pr_description_join",
   "model.turn",
@@ -92,6 +93,7 @@ const GETTING_READY: ReadonlySet<string> = new Set([
 const FINISHING_UP: ReadonlySet<string> = new Set([
   "run.observe_workspace",
   "run.pr_post_step",
+  "run.review_post_step",
   "run.reading_diff_join",
   "run.pr_description_join",
 ]);
@@ -150,6 +152,7 @@ export const PARENTS: Readonly<Record<string, readonly string[]>> = {
   "run.description_turn": ["request", "ship.round"],
   "run.observe_workspace": ["request", "ship.round"],
   "run.pr_post_step": ["request", "ship.round"],
+  "run.review_post_step": ["request", "ship.round"],
   "run.reading_diff_join": ["request", "ship.round"],
   "run.pr_description_join": ["request", "ship.round"],
   "model.turn": ["run.agent"],

package/dist/assets/src/core/trace/workerTrace.ts

@@ -52,6 +52,9 @@ export function shimRoute(pathname: string): string | undefined {
   if (pathname === "/costs" || pathname.startsWith("/costs/")) return "costs";
   if (pathname.startsWith("/api/")) return "api";
   if (pathname.startsWith("/admin/")) return "admin";
+  // The model proxy's two routes (docs/reference/specs/model-proxy.md): a bounded
+  // request per model call, forwarded to the container like everything else.
+  if (pathname === "/v1/messages" || pathname === "/v1/chat/completions") return "model-proxy";
   if (pathname === "/docs" || pathname.startsWith("/docs/")) return "docs";
   if (pathname === "/" || pathname === "/index.html") return "page";
   return "other";