@nanobpm/nano-workforce 0.55.0 → 0.57.0

package/docs/agentic-cockpit.md

@@ -0,0 +1,135 @@
+# The agentic visibility cockpit — operator guide
+
+> **Scope: SUPPLY side only.** This guide covers the *supply* half of the agentic
+> visibility plane (ADR 0056) — the live worker registry and the drill-into-a-worker
+> terminal. The **demand** side — the demand×supply matrix by network,
+> missing-agent-type reds, and diversity-SLO lights — is a separate concern,
+> deferred to the **enrolment epic #152**. Nothing here shows demand.
+
+## What the cockpit shows you
+
+The cockpit is a read-only, advisory window onto the fleet of agentic workers
+connected to this app. It answers two operator questions:
+
+1. **Who is here?** — every connected worker, grouped by the leaf token it
+   authenticated under, with its declared **family** and **host**, its current
+   **jobs**, the **process instance / plan** each job belongs to, and a
+   **liveness** dot (live / stale / down).
+2. **What is that worker doing right now?** — click a worker (or a specific
+   process/plan) to open its **live terminal**, streamed off the relay.
+
+It is **advisory**: it never gates, locks, or influences any BPMN sequence flow.
+Turning the cockpit off changes nothing about how work runs — it only changes
+what you can *see*.
+
+## The architecture in one breath
+
+The cockpit rides the **agentic channel** — one WebSocket the app serves on its
+*own* port at `/agentic`, alongside its pages and hooks (no sidecar port). Four
+cooperating families sit on that channel, each mounted through a single
+extension **seam** (`app/agentic/registry.ts`) so no family ever touches the boot
+script:
+
+| Family | Module | What it owns |
+| --- | --- | --- |
+| **presence** (H1) | `app/agentic/families/presence.family.ts` | The live worker registry over the app's SQLite store — REGISTER / heartbeat / disconnect. |
+| **relay** (H3) | `app/agentic/families/relay.family.ts` | The bounded replay ring + three-lane QoS scheduler + transcript store — the terminal stream. |
+| **blackboard** (H4) | `app/agentic/families/blackboard.family.ts` | The advisory coordination blackboard. |
+| **correlation** (H6) | `app/agentic/families/correlation.family.ts` | The jobKey ⇄ process-instance / plan join. |
+
+The supply report the cockpit polls is served by
+`GET /app/api/agentic/supply` (`operations/getAgenticSupply.ts`), which projects
+the presence snapshot — enriched with correlation — into the view.
+
+## Reading a worker row
+
+Each row in a leaf-token section is one connected worker:
+
+- **worker** — the worker instance id. Click it to drill into its terminal on its
+  default stream.
+- **family** — the declared agent family (e.g. `senior`, `junior`), or `—`.
+- **host** — where the worker runs, or `—`.
+- **jobs** — the jobKeys the worker is currently processing. Empty (`—`) when the
+  worker is idle *or* when nothing has correlated a job to it yet.
+- **process / plan** — the engine context for each current job: the BPMN process,
+  element, process-instance key, and plan/epic key, rendered as
+  `plan-fanout · implement-task · inst 4612 · owner/repo#142`. **Click it to open
+  that job's live terminal** (`job:<jobKey>`), not just the worker's default
+  stream.
+- **liveness** — `live` (heartbeating), `stale` (no refresh past the threshold,
+  default 15 s), or `down` (disconnected). Rendered as a coloured dot.
+
+### How jobs and process/plan get populated — the correlation seam (H6)
+
+A worker's channel frames don't carry job attribution — the relay only knows a
+*stream id*. So correlation is an explicit, advisory **registry**
+(`app/agentic/correlation.ts`) that the orchestrator populates when it dispatches
+an agentic job:
+
+```ts
+import { currentCorrelation } from "./app/agentic/correlation.ts";
+
+// When a worker instance picks up a Camunda-8 job:
+currentCorrelation()?.link("wk-a", jobKey, {
+  processInstanceKey,
+  bpmnProcessId,
+  elementId,
+  planKey, // e.g. owner/repo#142
+});
+
+// When the job finishes (or the worker disconnects):
+currentCorrelation()?.releaseJob(jobKey);      // one job
+currentCorrelation()?.releaseInstance("wk-a"); // every job the worker held
+```
+
+One `link` write is the single canonical join — it projects to **both**
+directions the cockpit needs:
+
+- `instance → jobKeys` feeds the presence snapshot's `jobKeysFor` seam, so a
+  worker's **jobs** column lights up;
+- `jobKey → context` (with the derived `job:<jobKey>` **stream**) drives the
+  **process / plan** cell and the drill-in.
+
+A jobKey belongs to at most one worker at a time — re-linking it moves it. The
+relay stream a job's terminal rides is always `job:<jobKey>` (see
+`jobStream` / `jobKeyOfStream` in `app/agentic/correlation.ts`); repointing the
+drill stream there is what lets you open the *live job's* terminal from the
+process/plan cell.
+
+If the correlation family is not mounted (or nothing has linked a job), the
+report still serves — jobs stay empty and every worker drills into its default
+instance stream. Correlation is **additive and advisory**; its absence never
+errors.
+
+## Drilling into a worker — resume-from-offset
+
+Clicking a worker (or a process/plan) opens a `TerminalSession`
+(`@nanobpm/agentic/cockpit`) subscribed to the relay stream. The session is
+**resume-from-offset**: it tracks the offset just past the last chunk it applied,
+and on every (re)connect it re-subscribes from there. This means:
+
+- A **cockpit reconnect** replays only the un-applied tail — no lost output, no
+  double-printed lines (within the ring's retained window).
+- A **hub restart** (the ring is in memory and is lost; the app's SQLite store is
+  durable) is survived the same way: the worker reconnects and replays its
+  transcript on a bumped incarnation, and your terminal resumes from its own
+  offset — receiving only what it hadn't already seen. Incarnation fencing stops
+  a stale producer from double-attaching. This exact path is pinned by the
+  end-to-end wiring test (`test/agentic-e2e.test.ts`).
+
+## Liveness and cleanup
+
+Presence rows are kept live by worker heartbeats and removed on disconnect or
+when a worker ages out past the liveness TTL. On (re)mount the presence family
+reconciles the store against live connections, so a worker that vanished while
+the app was down does not linger as a ghost row after a restart.
+
+## What you will NOT find here (and where it lives)
+
+- **Demand×supply matrix, missing-agent-type reds, diversity-SLO lights** →
+  enrolment epic **#152**. They depend on the vocab / capability→SERVE /
+  diversity-SLO machinery this epic deliberately de-scopes. This report carries
+  no demand-side fields and the renderer draws none.
+- **Engine / job-protocol changes** → none. The visibility plane is app-tier
+  only; the Camunda-8 worker⇄engine job protocol is untouched. The agentic
+  channel is the only new conversation.

package/nano.app.json

@@ -63,6 +63,10 @@
     }
   ],
   "workers": [
+    {
+      "taskType": "pr.ensure-base-branch",
+      "handler": "workers/ensure-base-branch/worker.ts"
+    },
     {
       "taskType": "pr.persist-round",
       "handler": "workers/persist-round/worker.ts"

package/openapi.yaml

@@ -127,7 +127,7 @@ components:
           description: Declared host (where the worker runs), if any.
         jobKeys:
           type: array
-          description: The jobKeys this worker is currently processing (empty until the H6 correlation seam lands).
+          description: The jobKeys this worker is currently processing (populated by the H6 correlation registry).
           items:
             type: string
         live:
@@ -149,6 +149,32 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/AgenticSupplyWorker"
+    AgenticJobCorrelation:
+      type: object
+      description: One current job's engine context (H6) — lines a worker's terminal up with its process
+        instance / plan. The relay stream a job's terminal is on is the jobKey-scoped stream `job:<jobKey>`.
+      required:
+        - jobKey
+        - stream
+      properties:
+        jobKey:
+          type: string
+          description: The Camunda-8 job key the worker activated.
+        stream:
+          type: string
+          description: The relay stream id the job's terminal is relayed on (`job:<jobKey>`).
+        processInstanceKey:
+          type: string
+          description: The owning process instance key, if known.
+        bpmnProcessId:
+          type: string
+          description: The BPMN process id the job belongs to, if known.
+        elementId:
+          type: string
+          description: The BPMN element id (activity/task) the job is for, if known.
+        planKey:
+          type: string
+          description: The plan / epic key this job is part of (e.g. owner/repo#142), if known.
     AgenticSupplyReport:
       type: object
       description: The SUPPLY-ONLY visibility report — the live worker list grouped by leaf. No demand-side
@@ -172,6 +198,12 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/AgenticSupplyLeaf"
+        correlations:
+          type: array
+          description: The engine context (process instance / plan) for every jobKey currently being
+            processed, so the cockpit can line each worker's terminal up with its process instance / plan (H6).
+          items:
+            $ref: "#/components/schemas/AgenticJobCorrelation"
     VersionInfo:
       type: object
       description: The running app's identity (which code is actually live).
@@ -329,9 +361,10 @@ components:
             per-request review-only override; defaults to false (the global auto-merge default applies).
     PlanStart:
       description: The start-plan-fanout request body. Names the target issue by EXACTLY ONE of
-        `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL). Modeled as `oneOf`
-        named variants (Camunda REST v2 pattern) so an ambiguous or empty target is a 400 at the
-        edge, not a silent `issue ?? url` coalesce in the delegate.
+        `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a REQUIRED
+        `baseBranch` (ADR 0003) the fleet branches off — a blank/absent base is a 400. Modeled as
+        `oneOf` named variants (Camunda REST v2 pattern) so an ambiguous or empty target is a 400 at
+        the edge, not a silent `issue ?? url` coalesce in the delegate.
       oneOf:
         - $ref: "#/components/schemas/PlanStartByIssue"
         - $ref: "#/components/schemas/PlanStartByUrl"
@@ -340,33 +373,77 @@ components:
       additionalProperties: false
       required:
         - issue
+        - baseBranch
       properties:
         issue:
           type: string
           description: "Issue reference: owner/repo#123."
         baseBranch:
           type: string
+          minLength: 1
+          maxLength: 255
+          pattern: '\S'
+          description: >-
+            REQUIRED target branch the fleet branches off and opens every PR against. Every epic
+            launch must name its base explicitly (ADR 0003): a blank/absent value is rejected with a
+            400, not silently coalesced to the repository default branch. Use it to land an entire
+            epic on a long-lived integration branch (e.g. `epic/agent-protocol`) so nothing reaches
+            the default branch — and any merge-to-default side effect, such as auto-publishing a
+            package — until you deliberately merge the integration branch. NOTE: this slice (B0)
+            only enforces that `baseBranch` is present and a plausible branch name; branch-existence
+            admission (auto-creating a missing `epic/*` base off the default branch HEAD, and
+            rejecting a missing non-`epic/*` base with a 400) is specified by ADR 0003 but NOT yet
+            enforced here — it lands in a later admission slice.
+        allowSharedBase:
+          type: boolean
+          description: >-
+            Reserved for a later ADR 0003 admission slice — NOT yet enforced in this slice (B0). When
+            implemented it will opt in to sharing a custom integration base branch with another
+            already-active plan: admission will otherwise reject (409) when another active plan already
+            targets the same repo + same custom base branch, to stop two epics interleaving commits on
+            one integration branch (the repository default branch is exempt from that guard). Accepted
+            by the schema today but currently has no runtime effect.
+        confirmDefaultBase:
+          type: boolean
           description: >-
-            Optional target branch the fleet branches off and opens every PR against, instead of the
-            repository's default branch. Use this to land an entire epic on a long-lived integration
-            branch (e.g. `epic/agent-protocol`) so nothing reaches the default branch — and any
-            merge-to-default side effect, such as auto-publishing a package — until you deliberately
-            merge the integration branch. Blank/omitted keeps the current behaviour (the repo
-            default branch).
+            Reserved for a later ADR 0003 admission slice — NOT yet enforced in this slice (B0). When
+            implemented it will be the required acknowledgement when `baseBranch` names the repository
+            default branch: targeting the default lands every task directly on it with no integration
+            buffer — and fires any merge-to-default side effect per task — so admission will reject
+            (400) unless confirmed with true (no effect for a non-default base). Accepted by the schema
+            today but currently has no runtime effect.
     PlanStartByUrl:
       type: object
       additionalProperties: false
       required:
         - url
+        - baseBranch
       properties:
         url:
           type: string
           description: A bare issue URL, when no `owner/repo#123` reference is supplied.
         baseBranch:
           type: string
+          minLength: 1
+          maxLength: 255
+          pattern: '\S'
+          description: >-
+            REQUIRED target branch the fleet branches off and opens every PR against. See
+            `PlanStartByIssue.baseBranch`.
+        allowSharedBase:
+          type: boolean
+          description: >-
+            Reserved for a later ADR 0003 admission slice — NOT yet enforced in this slice (B0).
+            Accepted by the schema today but currently has no runtime effect. When implemented it
+            will opt in to sharing a custom integration base branch with another already-active plan.
+            See `PlanStartByIssue.allowSharedBase`.
+        confirmDefaultBase:
+          type: boolean
           description: >-
-            Optional target branch the fleet branches off and opens every PR against, instead of the
-            repository's default branch. See `PlanStartByIssue.baseBranch`.
+            Reserved for a later ADR 0003 admission slice — NOT yet enforced in this slice (B0).
+            Accepted by the schema today but currently has no runtime effect. When implemented it
+            will be the required acknowledgement when `baseBranch` names the repository default
+            branch. See `PlanStartByIssue.confirmDefaultBase`.
     MessageResult:
       type: object
       description: The result of publishing a message / answering an escalation. Shape varies by message

package/operations/getAgenticSupply.test.ts

@@ -12,6 +12,8 @@ import { encodeFrame, type Frame } from "@nanobpm/agentic/protocol";
 import type { SqliteDb } from "@nanobpm/agentic/presence";
 import type { AppApi, DataLayer } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
+import { currentCorrelation } from "../app/agentic/correlation.ts";
+import { family as correlationFamily } from "../app/agentic/families/correlation.family.ts";
 import { family } from "../app/agentic/families/presence.family.ts";
 import type { AgenticContext } from "../app/agentic/registry.ts";
 import { noopLog } from "../test/log.ts";
@@ -151,3 +153,41 @@ test("shared-secret guard rejects a missing secret when configured", async () =>
     else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
   }
 });
+
+test("H6: with the correlation family mounted, jobKeys populate, stream repoints, and correlations are reported", async () => {
+  const hub = await mountPresence(memSqlite());
+  correlationFamily.mount({
+    hub,
+    registry: hub.registry,
+    transport: undefined as never,
+    data: undefined,
+    log: noopLog(),
+  });
+  const correlation = currentCorrelation();
+  assert(correlation !== undefined, "the correlation family installs the singleton");
+  correlation.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "o/r#142" });
+  try {
+    const res = (await handler(input(), app)) as {
+      status: number;
+      body: {
+        workers: Array<Record<string, unknown>>;
+        correlations: Array<Record<string, unknown>>;
+      };
+    };
+    assertEquals(res.status, 200);
+    const w = res.body.workers[0];
+    assertEquals(w.jobKeys, ["6494"], "the correlation registry feeds the jobKeys seam");
+    assertEquals(w.stream, "job:6494", "the drill stream repoints at the live job's stream");
+    assertEquals(res.body.correlations.length, 1);
+    const c = res.body.correlations[0];
+    assertEquals(c.jobKey, "6494");
+    assertEquals(c.stream, "job:6494");
+    assertEquals(c.processInstanceKey, "4612");
+    assertEquals(c.bpmnProcessId, "plan-fanout");
+    assertEquals(c.planKey, "o/r#142");
+  } finally {
+    correlationFamily.teardown?.();
+    family.teardown?.();
+    await hub.close();
+  }
+});

package/operations/getAgenticSupply.ts

@@ -3,6 +3,12 @@
 // worker list — family, host, current jobs, liveness — grouped by leaf token, sourced from the H1
 // presence registry (#144). Read-only projection; it NEVER gates control flow (advisory-only, ADR 0056).
 //
+// H6 (#149) closes the loop: the correlation registry (`app/agentic/correlation.ts`) supplies the
+// `jobKeysFor` resolver the presence snapshot exposes as a seam, so each worker's current jobKeys light
+// up; each worker's drill `stream` is repointed at its jobKey-scoped relay stream (`job:<jobKey>`); and
+// the report carries the `correlations` — the process-instance / plan context for every current job —
+// so the cockpit lines a worker's terminal up with "that process instance / this plan".
+//
 // This is the supply half of the visibility plane only. The demand×supply matrix, missing-agent-type
 // reds, and diversity-SLO lights are DE-SCOPED to the enrolment epic #152 — this report carries no
 // demand-side fields, and the cockpit renders none.
@@ -10,22 +16,24 @@
 // The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`): when
 // NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset → open.
 
+import { type CorrelationRegistry, currentCorrelation, type JobCorrelation } from "../app/agentic/correlation.ts";
 import { currentPresenceRegistry, type SupplyWorker } from "../app/agentic/families/presence.family.ts";
 import { envVar } from "../app/version.ts";
-import type { AgenticSupplyReport, AgenticSupplyWorker } from "../nano-generated/api-io.d.ts";
+import type { AgenticJobCorrelation, AgenticSupplyReport, AgenticSupplyWorker } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 // The optional shared-secret guard: when NANO_PR_WEBHOOK_SECRET is set, callers must present it via
 // the x-hook-secret header. Captured once, at module load.
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
-// The relay stream id to subscribe when drilling into a worker's terminal. Presence keys the relay by
-// worker instance; the H6 correlation slice (#149) may repoint this at a jobKey-scoped stream.
-function toWorker(w: SupplyWorker): AgenticSupplyWorker {
+// Project a presence-registry row to the wire worker. The drill `stream` defaults to the worker
+// instance (H5) but is repointed at the worker's jobKey-scoped relay stream (`job:<jobKey>`) when the
+// correlation registry knows a current job for it (H6) — so drilling in opens the LIVE job's terminal.
+function toWorker(w: SupplyWorker, correlation: CorrelationRegistry | undefined): AgenticSupplyWorker {
   const out: AgenticSupplyWorker = {
     instance: w.instance,
     identity: w.identity,
-    stream: w.instance,
+    stream: correlation?.primaryStreamFor(w.instance) ?? w.instance,
     jobKeys: [...w.jobKeys],
     live: w.live,
     staleMs: w.staleMs,
@@ -35,6 +43,17 @@ function toWorker(w: SupplyWorker): AgenticSupplyWorker {
   return out;
 }
 
+// Project a correlation-registry entry to the wire correlation. Optional fields are only set when
+// known (biome bans `undefined`-valued keys crossing the boundary).
+function toCorrelation(c: JobCorrelation): AgenticJobCorrelation {
+  const out: AgenticJobCorrelation = { jobKey: c.jobKey, stream: c.stream };
+  if (c.processInstanceKey !== undefined) out.processInstanceKey = c.processInstanceKey;
+  if (c.bpmnProcessId !== undefined) out.bpmnProcessId = c.bpmnProcessId;
+  if (c.elementId !== undefined) out.elementId = c.elementId;
+  if (c.planKey !== undefined) out.planKey = c.planKey;
+  return out;
+}
+
 export default defineOperation("getAgenticSupply", async ({ req }, app) => {
   if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
     app.log.warn("getAgenticSupply rejected: missing/invalid shared secret");
@@ -44,16 +63,20 @@ export default defineOperation("getAgenticSupply", async ({ req }, app) => {
   const registry = currentPresenceRegistry();
   if (!registry) {
     // The presence family has not mounted (or has torn down) — no supply to report, not an error.
-    const empty: AgenticSupplyReport = { count: 0, generatedAt: new Date().toISOString(), workers: [], leaves: [] };
+    const empty: AgenticSupplyReport = { count: 0, generatedAt: new Date().toISOString(), workers: [], leaves: [], correlations: [] };
     return { status: 200, body: empty };
   }
 
-  const snapshot = registry.snapshot();
+  // Thread the H6 correlation registry (if mounted) as the presence snapshot's jobKeysFor resolver so a
+  // worker's current jobKeys populate; absent → jobKeys stay empty (advisory, never an error).
+  const correlation = currentCorrelation();
+  const snapshot = registry.snapshot(correlation ? { jobKeysFor: (instance) => correlation.jobKeysFor(instance) } : {});
   const report: AgenticSupplyReport = {
     count: snapshot.count,
     generatedAt: new Date().toISOString(),
-    workers: snapshot.workers.map(toWorker),
-    leaves: snapshot.leaves.map((leaf) => ({ token: leaf.token, workers: leaf.workers.map(toWorker) })),
+    workers: snapshot.workers.map((w) => toWorker(w, correlation)),
+    leaves: snapshot.leaves.map((leaf) => ({ token: leaf.token, workers: leaf.workers.map((w) => toWorker(w, correlation)) })),
+    correlations: correlation ? correlation.snapshot().correlations.map(toCorrelation) : [],
   };
   return { status: 200, body: report };
 });

package/operations/startAndMessage.test.ts

@@ -12,6 +12,7 @@ import { noopLog } from "../test/log.ts";
 import startConvergenceLoop from "./startConvergenceLoop.ts";
 import startPlanFanout from "./startPlanFanout.ts";
 import postMessage from "./postMessage.ts";
+import { resetDefaultBranchCache } from "../app/github.ts";
 
 const app = { log: noopLog() } as any as AppApi;
 
@@ -72,13 +73,60 @@ function withGithubOff(run: () => Promise<void>): Promise<void> {
   const prevTok = process.env["GITHUB_TOKEN"];
   process.env["NANO_PR_GITHUB_TRANSPORT"] = "token"; // no token → meta fetch is skipped
   delete process.env["GITHUB_TOKEN"];
+  resetDefaultBranchCache(); // start cold so a prior warmed cache can't mask the no-transport path
   return run().finally(() => {
+    resetDefaultBranchCache();
     if (prev !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prev;
     else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
     if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
   });
 }
 
+// Force the token transport with a stubbed `globalThis.fetch` that serves a minimal in-memory
+// github model, so `admitPlan` (which now calls `ensureBaseBranch` + `fetchDefaultBranch`) can run
+// without touching the network. The default branch is `main`; an epic/* base is auto-created off it.
+function withGithubStub(run: () => Promise<void>): Promise<void> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "tok";
+  resetDefaultBranchCache(); // isolate: don't inherit or leak the owner/repo default-branch entry
+  const branches = new Map<string, string>([["main", "mainsha"]]);
+  globalThis.fetch = ((url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = new URL(String(url));
+    const method = (init?.method ?? "GET").toUpperCase();
+    const path = u.pathname;
+    const json = (obj: unknown, status = 200) =>
+      new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } });
+    if (method === "GET" && path === "/repos/owner/repo") return Promise.resolve(json({ default_branch: "main" }));
+    const refPrefix = "/repos/owner/repo/git/ref/heads/";
+    if (method === "GET" && path.startsWith(refPrefix)) {
+      const branch = decodeURIComponent(path.slice(refPrefix.length));
+      const sha = branches.get(branch);
+      if (sha === undefined) return Promise.resolve(new Response("Not Found", { status: 404 }));
+      return Promise.resolve(json({ ref: `refs/heads/${branch}`, object: { sha } }));
+    }
+    if (method === "POST" && path === "/repos/owner/repo/git/refs") {
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      const body = JSON.parse(String(init?.body ?? "{}")) as { ref?: string; sha?: string };
+      const branch = String(body.ref ?? "").replace(/^refs\/heads\//, "");
+      if (branches.has(branch)) return Promise.resolve(json({ message: "Reference already exists" }, 422));
+      branches.set(branch, String(body.sha ?? ""));
+      return Promise.resolve(json({ ref: body.ref }, 201));
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  }) as typeof fetch;
+  return run().finally(() => {
+    resetDefaultBranchCache();
+    globalThis.fetch = prevFetch;
+    if (prevMode !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
+    else delete process.env["GITHUB_TOKEN"];
+  });
+}
+
 test("startConvergenceLoop → 400 (not 500) on a missing request body", async () => {
   const res = await startConvergenceLoop(input(undefined), app);
   const r = res as any;
@@ -133,6 +181,15 @@ test("startPlanFanout → 400 on an invalid baseBranch (not persisted/rendered)"
   assertEquals(typeof r.body.error, "string");
 });
 
+test("startPlanFanout → 400 on a missing baseBranch (not persisted/rendered)", async () => {
+  // A blank/absent baseBranch must be rejected at the edge as a 400 (MissingBaseBranchError),
+  // never silently coalesced to the repository default branch (ADR 0003, B0).
+  const res = await startPlanFanout(input({ issue: "owner/repo#123" }), app);
+  const r = res as any;
+  assertEquals(r.status, 400);
+  assertEquals(typeof r.body.error, "string");
+});
+
 test("startConvergenceLoop narrows the `url` variant (no `pr` key)", async () => {
   await withGithubOff(async () => {
     const { app: capApp } = captureApp();
@@ -142,9 +199,12 @@ test("startConvergenceLoop narrows the `url` variant (no `pr` key)", async () =>
 });
 
 test("startPlanFanout narrows the `url` variant (no `issue` key)", async () => {
-  await withGithubOff(async () => {
+  await withGithubStub(async () => {
     const { app: capApp } = captureApp();
-    const res = await startPlanFanout(input({ url: "https://github.com/owner/repo/issues/12" }), capApp);
+    const res = await startPlanFanout(
+      input({ url: "https://github.com/owner/repo/issues/12", baseBranch: "epic/agent-protocol" }),
+      capApp,
+    );
     assertEquals((res as any).status, 202);
   });
 });