@nanobpm/nano-workforce 0.56.0 → 0.58.0

package/app/escalationTaxonomy.ts

@@ -0,0 +1,115 @@
+// Escalation taxonomy — the single canonical source of truth for classifying an
+// escalation raise site into a tier (nano-workforce ADR 0002 §1).
+//
+// The app used to page a human from several independent raise sites, each with its own
+// ad-hoc "should this become an escalation?" logic, and — worst of all — a blank/absent
+// question could FABRICATE an answerable escalation (or, on the plan-fanout arm, wedge an
+// un-remediable incident). This module replaces that scattered logic with ONE classifier so
+// every raise site, and every downstream escalation-conversion slice (U2–U7), asks the same
+// question in the same place.
+//
+// ADR 0002 §1 defines three tiers:
+//   • transient        — handled in-process (retry / re-enter a durable wait / re-request a
+//                        review). Never becomes a task. The empty-status backstop and the
+//                        re-request-review nudge are transient.
+//   • advisory         — recorded on the coordination blackboard for humans/siblings to read.
+//                        Never becomes a task and never blocks a token.
+//   • decision-required — a human (or, per ADR 0046, an agent assignee) must make a call.
+//                        ONLY this tier proceeds toward a user task.
+//
+// A fourth disposition, `none`, means "not an escalation at all": the signal was raised but,
+// on inspection, there is nothing to escalate — most importantly a decision-required kind
+// whose question is blank. A blank question can no longer fabricate an answerable escalation:
+// it is a NON-escalation (no task, no wait).
+
+/** The three escalation tiers of ADR 0002 §1. */
+export type EscalationTier = "transient" | "advisory" | "decision-required";
+
+/** A raise site's disposition: either it is not an escalation at all (`none`), or it falls
+ * into one of the three tiers. Only `decision-required` proceeds toward a user task. */
+export type EscalationDisposition = "none" | EscalationTier;
+
+/** Every escalation raise site in the codebase, tagged by origin so the classifier can apply
+ * that site's policy. */
+export type EscalationKind =
+  // convergence-loop `gw-status` gateway — the review-round "safe default" routing that
+  // `roundResultDefault` mirrors.
+  | "review-round"
+  // `baseGuard` (app/baseGuard.ts) — a PR that targets a dead-end (already-landed) base.
+  | "dead-end-base"
+  // `mergeProtocol` (app/mergeProtocol.ts) — the repo's declared land method.
+  | "merge-protocol"
+  // plan-fanout `w_gw` "escalated?" gateway — an implementation agent reported
+  // `status = "escalated"` with a question.
+  | "task";
+
+/** Everything the classifier may need from any raise site. Each field is consumed only by the
+ * kind(s) it applies to; the rest are ignored. */
+export interface EscalationSignal {
+  kind: EscalationKind;
+  /** The human-facing question / reason. Blank (absent, empty, or whitespace-only) means the
+   * signal can never become a task — see {@link hasAnswerableQuestion}. */
+  question?: string | null;
+  /** `review-round` only: the machine-readable status the review agent reported. */
+  status?: string | null;
+  /** `dead-end-base` only: whether the base is a CONFIRMED dead end (ambiguity is never a
+   * dead end — see {@link import("./baseGuard.ts").isDeadEndBase}). */
+  deadEnd?: boolean;
+  /** `merge-protocol` only: the repo's declared land method (`ui` needs a human). */
+  landMethod?: string | null;
+}
+
+/** True iff `question` is a concrete, human-answerable string — a non-blank value after
+ * trimming. This is the canonical blank-question rule the whole taxonomy shares: an
+ * empty / whitespace-only / absent question is NOT answerable, so it can never fabricate an
+ * escalation. */
+export function hasAnswerableQuestion(question: string | null | undefined): boolean {
+  return typeof question === "string" && question.trim() !== "";
+}
+
+/** The review-round statuses that DEMAND a human decision. Any other status (converged,
+ * addressed, waiting, or an unknown/empty one — the empty-status backstop) is transient: it
+ * re-enters the durable review wait rather than paging a human. */
+const DECISION_STATUSES: ReadonlySet<string> = new Set(["needs_input", "blocked"]);
+
+/** Classify an escalation signal into its disposition. The one place the tiered taxonomy of
+ * ADR 0002 §1 is decided — every raise site and every escalation-conversion slice routes
+ * through here rather than re-deriving tier logic per kind. */
+export function classifyEscalation(signal: EscalationSignal): EscalationDisposition {
+  switch (signal.kind) {
+    case "review-round": {
+      // Exact-token match, mirroring the convergence-loop `gw-status` gateway (whose
+      // status conditions do NOT trim) so this canonical router can never drift from the
+      // deployed model. `status` is a machine-produced enum, not free-form prose, so it is
+      // compared exactly — unlike `question`, whose blank-detection trims (hasAnswerableQuestion).
+      const status = signal.status ?? "";
+      // Only an explicit human-blocking status is even a candidate; everything else is
+      // transient (re-enter the review wait — this is the empty-status backstop).
+      if (!DECISION_STATUSES.has(status)) return "transient";
+      // A human-blocking status with no answerable question is a NON-escalation: a blank
+      // question can no longer fabricate an answerable escalation.
+      return hasAnswerableQuestion(signal.question) ? "decision-required" : "none";
+    }
+    case "dead-end-base":
+      // A confirmed dead-end base needs a human retarget; ambiguity is never raised, so a
+      // non-dead-end signal is simply not an escalation.
+      return signal.deadEnd ? "decision-required" : "none";
+    case "merge-protocol":
+      // Only a `ui` land method needs a human (to click Merge). Every machine-landable method
+      // (gh-merge / admin / mergify-queue) stays in-process — transient.
+      return signal.landMethod === "ui" ? "decision-required" : "transient";
+    case "task":
+      // The agent declared `status = "escalated"`; a blank question is a NON-escalation. This
+      // retires the blank-question fabrication failure mode — no task, no wait.
+      return hasAnswerableQuestion(signal.question) ? "decision-required" : "none";
+    default:
+      return "none";
+  }
+}
+
+/** The guard every raise site and escalation-conversion slice shares: does this signal proceed
+ * toward a user task? Only the `decision-required` tier does — transient and advisory signals,
+ * and non-escalations (`none`, including blank-question signals), never raise a task. */
+export function shouldRaiseTask(signal: EscalationSignal): boolean {
+  return classifyEscalation(signal) === "decision-required";
+}

package/app/feature.test.ts

@@ -0,0 +1,161 @@
+// Unit coverage for the single-issue feature run domain (issue #172).
+//
+// `startFeature` mirrors `startPlan`: it registers/refreshes the `feature_runs` aggregate
+// (idempotent on `feature_key`), starts `feature.bpmn`, and persists the process key. These tests
+// drive it against an in-memory data layer + a stub engine and assert the row shape, the
+// short-circuit on an already-running run, the in-place restart of a settled run, and the seeded
+// process variables (the single `task` slice + the base-branch brief).
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { FEATURE_PROCESS_ID, featureTaskId, startFeature } from "./feature.ts";
+
+function memTable(rows: any[], key: string) {
+  return {
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    find: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    insert: (r: any) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r);
+    },
+    delete: (k: any) => {
+      for (let i = rows.length - 1; i >= 0; i--) if (rows[i][key] === k) rows.splice(i, 1);
+      return Promise.resolve();
+    },
+  };
+}
+
+function memData(stores: Record<string, { rows: any[]; key: string }>) {
+  return {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+  } as any;
+}
+
+const PARSED = {
+  repo: "owner/repo",
+  number: 42,
+  url: "https://github.com/owner/repo/issues/42",
+  planKey: "owner/repo#42",
+};
+
+test("featureTaskId: deterministic branch slug derivable from the issue number alone", () => {
+  assertEquals(featureTaskId(42), "issue-42");
+  assertEquals(featureTaskId(1), "issue-1");
+});
+
+test("startFeature: inserts a running feature_runs row and persists the process key", async () => {
+  const stores = { feature_runs: { rows: [] as any[], key: "feature_key" } };
+  const data = memData(stores);
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-9" }) } as any;
+
+  const result = await startFeature(data, engine, PARSED, "main", false, false);
+
+  assertEquals(result.featureKey, "owner/repo#42");
+  assertEquals(result.processKey, "PI-9");
+  const row = stores.feature_runs.rows[0];
+  assertEquals(row.feature_key, "owner/repo#42");
+  assertEquals(row.repo, "owner/repo");
+  assertEquals(row.issue_number, 42);
+  assertEquals(row.base_branch, "main");
+  assertEquals(row.status, "running");
+  assertEquals(row.process_key, "PI-9");
+  assertEquals(row.converge, 0);
+  assertEquals(row.auto_merge, 0);
+  assertEquals(row.pr_key, null);
+});
+
+test("startFeature: converge/autoMerge flags are persisted as 0/1", async () => {
+  const stores = { feature_runs: { rows: [] as any[], key: "feature_key" } };
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-1" }) } as any;
+  await startFeature(memData(stores), engine, PARSED, "main", true, true);
+  const row = stores.feature_runs.rows[0];
+  assertEquals(row.converge, 1);
+  assertEquals(row.auto_merge, 1);
+});
+
+test("startFeature: seeds the single task slice + base-branch brief onto the instance", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-2" });
+    },
+  } as any;
+  await startFeature(
+    memData({ feature_runs: { rows: [], key: "feature_key" } }),
+    engine,
+    PARSED,
+    "epic/x",
+    true,
+    false,
+  );
+  assertEquals(captured.processDefinitionId, FEATURE_PROCESS_ID);
+  const v = captured.variables;
+  assertEquals(v.featureKey, "owner/repo#42");
+  assertEquals(v.issue, "owner/repo#42");
+  assertEquals(v.task.id, "issue-42");
+  assertEquals(v.task.title, "owner/repo#42");
+  assertEquals(typeof v.task.prompt, "string");
+  assertEquals(v.task.prompt.includes("owner/repo#42"), true);
+  assertEquals(v.converge, true);
+  assertEquals(v.autoMerge, false);
+  assertEquals(v.baseBranch, "epic/x");
+  // The brief is the authoritative base-branch override the agent gets via appendPrompt.
+  assertEquals(v.baseBranchBrief.includes("epic/x"), true);
+  // Agent-result variables are pre-seeded so the escalation loop + record worker can reference them.
+  assertEquals(v.pr, null);
+  assertEquals(v.status, null);
+});
+
+test("startFeature: an already-running run short-circuits (no new instance)", async () => {
+  const stores = {
+    feature_runs: {
+      rows: [{ feature_key: "owner/repo#42", status: "running", process_key: "PI-OLD" }],
+      key: "feature_key",
+    },
+  };
+  let created = 0;
+  const engine = {
+    createInstance: () => {
+      created += 1;
+      return Promise.resolve({ processInstanceKey: "PI-NEW" });
+    },
+  } as any;
+  const result = await startFeature(memData(stores), engine, PARSED, "main", false, false);
+  assertEquals(created, 0);
+  assertEquals("alreadyRunning" in result && (result as any).alreadyRunning, true);
+  assertEquals(result.processKey, "PI-OLD");
+});
+
+test("startFeature: a settled run is restarted in place (status reset, pr/outcome cleared)", async () => {
+  const stores = {
+    feature_runs: {
+      rows: [
+        {
+          feature_key: "owner/repo#42",
+          status: "opened",
+          process_key: "PI-OLD",
+          pr_key: "owner/repo#100",
+          outcome: "prior run",
+          converge: 0,
+          auto_merge: 0,
+        },
+      ],
+      key: "feature_key",
+    },
+  };
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-2" }) } as any;
+  await startFeature(memData(stores), engine, PARSED, "main", true, true);
+  const row = stores.feature_runs.rows[0];
+  assertEquals(row.status, "running");
+  assertEquals(row.pr_key, null);
+  assertEquals(row.outcome, null);
+  assertEquals(row.converge, 1);
+  assertEquals(row.auto_merge, 1);
+  assertEquals(row.process_key, "PI-2");
+});

package/app/feature.ts

@@ -0,0 +1,173 @@
+// nano-workforce — single-issue feature run (issue #172).
+//
+// The "missing middle" dispatch surface, between Epics (plan-fanout: one issue →
+// many PRs) and PR convergence (an already-open PR → review → merge): hand ONE
+// issue to a single implementation agent (`senior:feature`), which raises exactly
+// ONE PR, then OPTIONALLY hand that PR to the convergence loop (and, with
+// auto-merge, the merge-loop).
+//
+// This module is the seam the `startFeature` action and the `feature.bpmn` record
+// workers call: it owns the `feature_runs` row shape, the per-run task derivation,
+// and starting the process. It deliberately REUSES the epic primitives rather than
+// forking them — `parseIssue`/`renderBaseBranchBrief`/`normalizeBaseBranch` and the
+// `ESCALATION_SLA_TIMEOUT` come from app/plan.ts, and the downstream PR lifecycle is
+// the existing convergence loop (`submitPr`), keyed on `pr_key` → `pull_requests`.
+// Data access goes through the record gateway (`data.table`), never hand-written
+// SQL — matching app/plan.ts and app/service.ts.
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
+
+/** The BPMN process this module drives (resources/processes/feature.bpmn). */
+export const FEATURE_PROCESS_ID = "feature";
+
+const now = () => new Date().toISOString();
+
+/** One row per issue handed to a single implementation agent. Keyed on `feature_key`
+ * (`<owner>/<repo>#<issue-number>`, the same string `parseIssue` returns as `planKey`).
+ * The downstream PR lifecycle (review/merge) is NOT duplicated here — once `converge`
+ * hands the opened PR to `submitPr`, its live state lives on the `pull_requests` row
+ * keyed by `pr_key`. */
+export interface FeatureRun {
+  feature_key: string;
+  repo: string;
+  issue_number: number;
+  issue_url: string;
+  base_branch: string;
+  status: FeatureRunStatus;
+  process_key: string | null;
+  pr_key: string | null;
+  converge: number;
+  auto_merge: number;
+  outcome: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export const FEATURE_RUN_STATUSES = [
+  "running", // the agent is implementing (including while parked at an escalation user task)
+  "opened", // a PR was raised and the run ends here (converge was not requested)
+  "converging", // the opened PR was handed to the convergence loop (live state via pr_key → pull_requests)
+  "blocked", // the agent could not open a PR (gave up / escalation abandoned)
+  "skipped", // nothing to do
+  "failed", // an unexpected failure
+  "abandoned", // the process instance was cancelled (set by instanceTracking.onTerminated)
+] as const;
+export type FeatureRunStatus = typeof FEATURE_RUN_STATUSES[number];
+
+/** A feature run is finished once it leaves `running`. Mirrors PLAN_TERMINAL_STATUSES: a
+ * re-dispatch of the same issue restarts only when the prior run has settled. */
+export const FEATURE_TERMINAL_STATUSES: readonly FeatureRunStatus[] = [
+  "opened",
+  "converging",
+  "blocked",
+  "skipped",
+  "failed",
+  "abandoned",
+];
+
+export const featureRuns = (data: DataLayer) => data.table<FeatureRun>("feature_runs", "feature_key");
+
+/** The deterministic task id for a single-issue run — the implementation agent branches
+ * `feat/<task.id>` (see prompts/feature.md), so it MUST be derivable from the issue alone
+ * and stable across a resume. The PR is opened on the target repo, so the issue number
+ * alone is unambiguous within it. */
+export function featureTaskId(issueNumber: number): string {
+  return `issue-${issueNumber}`;
+}
+
+/** Register/refresh the feature-run aggregate (idempotent on `feature_key`) and start
+ * `feature.bpmn`. Mirrors startPlan: an already-running run for the same issue
+ * short-circuits; a settled prior run is restarted in place. `baseBranch` is admitted at
+ * the operation edge (`admitPlan`, ADR 0003) exactly as the epic path — this seam only
+ * normalizes it again defensively before seeding the brief. */
+export async function startFeature(
+  data: DataLayer,
+  engine: EngineClient,
+  parsed: ParsedIssue,
+  baseBranch: string,
+  converge: boolean,
+  autoMerge: boolean,
+) {
+  const table = featureRuns(data);
+  const existing = await table.get(parsed.planKey);
+  if (existing && !FEATURE_TERMINAL_STATUSES.includes(existing.status)) {
+    return { featureKey: parsed.planKey, alreadyRunning: true, processKey: existing.process_key };
+  }
+  const base = normalizeBaseBranch(baseBranch);
+  const ts = now();
+  if (existing) {
+    await table.update(parsed.planKey, {
+      status: "running",
+      base_branch: base,
+      issue_url: parsed.url,
+      pr_key: null,
+      converge: converge ? 1 : 0,
+      auto_merge: autoMerge ? 1 : 0,
+      outcome: null,
+      updated_at: ts,
+    });
+  } else {
+    await table.insert({
+      feature_key: parsed.planKey,
+      repo: parsed.repo,
+      issue_number: parsed.number,
+      issue_url: parsed.url,
+      base_branch: base,
+      status: "running",
+      process_key: null,
+      pr_key: null,
+      converge: converge ? 1 : 0,
+      auto_merge: autoMerge ? 1 : 0,
+      outcome: null,
+      created_at: ts,
+      updated_at: ts,
+    });
+  }
+  const { processInstanceKey } = await engine.createInstance({
+    processDefinitionId: FEATURE_PROCESS_ID,
+    variables: {
+      featureKey: parsed.planKey,
+      repo: parsed.repo,
+      // The parent issue reference (`owner/repo#123`) the agent reads for context (`gh issue view`).
+      issue: parsed.planKey,
+      issueNumber: parsed.number,
+      issueUrl: parsed.url,
+      // The single slice the implementation agent builds. `task.prompt` is its primary instruction
+      // (prompts/feature.md); `task.id` fixes its deterministic branch `feat/<task.id>` across a
+      // resume. Unlike an epic, there is no planner — the whole issue IS the slice.
+      task: {
+        id: featureTaskId(parsed.number),
+        title: parsed.planKey,
+        prompt:
+          `Implement the GitHub issue ${parsed.planKey} end to end. Read it in full first ` +
+          `(\`gh issue view ${parsed.number} -R ${parsed.repo}\`), implement it completely, ` +
+          `and open exactly one pull request that closes it.`,
+      },
+      // Follow-on knobs, read by the record/converge workers. `autoMerge` maps to submitPr's
+      // `convergeOnly` (inverted): converge-only stops at `converged`; auto-merge drives the
+      // merge-loop. `converge=false` ⇒ merge is moot.
+      converge,
+      autoMerge,
+      // Seed the agent-result variables so the escalation loop + record worker can reference them
+      // before the first `senior:feature` job completes (the harness merges the real values in).
+      answer: null,
+      status: null,
+      question: null,
+      summary: null,
+      pr: null,
+      // Escalation SLA + optional assignee — identical to the epic path (plan-fanout), read by the
+      // `feature-escalation` user task's interrupting timer boundary and assignment definition.
+      escalationSlaTimeout: ESCALATION_SLA_TIMEOUT,
+      escalationAssignee: null,
+      // Base branch (ADR 0003): the branch the agent branches off and opens its PR against. The
+      // brief rides `appendPrompt` in the implement task, exactly like the epic implementer.
+      baseBranch: base,
+      baseBranchBrief: renderBaseBranchBrief(base),
+    },
+  });
+  const processKey = processInstanceKey == null ? null : String(processInstanceKey);
+  if (processKey != null) {
+    await table.update(parsed.planKey, { process_key: processKey, updated_at: now() });
+  }
+  return { featureKey: parsed.planKey, processKey };
+}

package/app/github.test.ts

@@ -3,7 +3,7 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { fetchPrFiles } from "./github.ts";
+import { BaseBranchMustExistError, ensureBaseBranch, fetchPrFiles } from "./github.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
 // files (named `f{index}`), setting a `Link: rel="next"` header whenever a later page exists.
@@ -58,3 +58,181 @@ test("fetchPrFiles: throws when the cap genuinely truncates (full last page + ne
     "truncated",
   );
 });
+
+// ── ensureBaseBranch (ADR 0003 rule 2) ──────────────────────────────────────
+// Force the token transport and stub `globalThis.fetch` so the create-if-missing primitive is
+// exercised end-to-end without touching the network: git-ref lookups, default-branch resolution,
+// and ref creation are all served from an in-memory repo model that records every create call.
+interface FakeRepo {
+  repo: string;
+  defaultBranch: string;
+  branches: Map<string, string>; // branch name → head sha (includes the default branch)
+  creates: { ref: string; sha: string }[];
+}
+
+function jsonResponse(obj: unknown, status = 200): Response {
+  return new Response(JSON.stringify(obj), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function githubFetch(state: FakeRepo) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = new URL(String(url));
+    const method = (init?.method ?? "GET").toUpperCase();
+    const path = u.pathname;
+    // Repo metadata → default branch (fetchDefaultBranch token mode).
+    if (method === "GET" && path === `/repos/${state.repo}`) {
+      return Promise.resolve(jsonResponse({ default_branch: state.defaultBranch }));
+    }
+    // Git ref lookup → head sha or 404.
+    const refPrefix = `/repos/${state.repo}/git/ref/heads/`;
+    if (method === "GET" && path.startsWith(refPrefix)) {
+      const branch = decodeURIComponent(path.slice(refPrefix.length));
+      const sha = state.branches.get(branch);
+      if (sha === undefined) return Promise.resolve(new Response("Not Found", { status: 404 }));
+      return Promise.resolve(jsonResponse({ ref: `refs/heads/${branch}`, object: { sha } }));
+    }
+    // Create ref.
+    if (method === "POST" && path === `/repos/${state.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 ref = String(body.ref ?? "");
+      const sha = String(body.sha ?? "");
+      const branch = ref.replace(/^refs\/heads\//, "");
+      if (state.branches.has(branch)) {
+        return Promise.resolve(jsonResponse({ message: "Reference already exists" }, 422));
+      }
+      state.creates.push({ ref, sha });
+      state.branches.set(branch, sha);
+      return Promise.resolve(jsonResponse({ ref }, 201));
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(state: FakeRepo, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = githubFetch(state) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+test("ensureBaseBranch: existing branch is a no-op (never creates/resets the ref)", async () => {
+  const state: FakeRepo = {
+    repo: "o/exists",
+    defaultBranch: "main",
+    branches: new Map([
+      ["main", "mainsha"],
+      ["epic/already-there", "existingsha"],
+    ]),
+    creates: [],
+  };
+  const result = await withGithub(state, () =>
+    ensureBaseBranch(state.repo, "epic/already-there", "tok"),
+  );
+  assertEquals(result, "exists");
+  assertEquals(state.creates.length, 0);
+  // The ref must be left untouched.
+  assertEquals(state.branches.get("epic/already-there"), "existingsha");
+});
+
+test("ensureBaseBranch: missing epic/* branch is created off the default branch HEAD", async () => {
+  const state: FakeRepo = {
+    repo: "o/create-epic",
+    defaultBranch: "main",
+    branches: new Map([["main", "defaulthead"]]),
+    creates: [],
+  };
+  const result = await withGithub(state, () =>
+    ensureBaseBranch(state.repo, "epic/new-feature", "tok"),
+  );
+  assertEquals(result, "created");
+  assertEquals(state.creates, [{ ref: "refs/heads/epic/new-feature", sha: "defaulthead" }]);
+});
+
+test("ensureBaseBranch: idempotent — a second call once the branch exists is a no-op", async () => {
+  const state: FakeRepo = {
+    repo: "o/idempotent",
+    defaultBranch: "main",
+    branches: new Map([["main", "defaulthead"]]),
+    creates: [],
+  };
+  const first = await withGithub(state, () => ensureBaseBranch(state.repo, "epic/twice", "tok"));
+  assertEquals(first, "created");
+  assertEquals(state.creates.length, 1);
+  // Re-plan / durable head-task re-run: the branch now exists → clean no-op, no second create.
+  const second = await withGithub(state, () => ensureBaseBranch(state.repo, "epic/twice", "tok"));
+  assertEquals(second, "exists");
+  assertEquals(state.creates.length, 1);
+});
+
+test(
+  'ensureBaseBranch: concurrent create race (GET 404 then POST 422) reports "exists", not "created"',
+  async () => {
+    // Simulate losing the create race: the ref lookup 404s (so we attempt a create), but by the
+    // time our POST lands another actor has already created the ref → GitHub answers 422. The
+    // 422 is idempotent, and the outcome must be the honest "exists" (we did not create it), not
+    // a misleading "created". This locks in the retriable semantics for a concurrent create.
+    const state: FakeRepo = {
+      repo: "o/race",
+      defaultBranch: "main",
+      branches: new Map([["main", "defaulthead"]]),
+      creates: [],
+    };
+    // The git-ref lookup for the epic branch always 404s (as if it does not exist yet), while a
+    // concurrent actor has "already created" it so our POST sees a 422.
+    const base = githubFetch(state);
+    const racingFetch = (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+      const u = new URL(String(url));
+      const method = (init?.method ?? "GET").toUpperCase();
+      const path = u.pathname;
+      if (method === "GET" && path === `/repos/${state.repo}/git/ref/heads/epic/raced`) {
+        return Promise.resolve(new Response("Not Found", { status: 404 }));
+      }
+      if (method === "POST" && path === `/repos/${state.repo}/git/refs`) {
+        return Promise.resolve(jsonResponse({ message: "Reference already exists" }, 422));
+      }
+      return base(url, init);
+    };
+    const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+    const prevFetch = globalThis.fetch;
+    process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+    globalThis.fetch = racingFetch as typeof fetch;
+    try {
+      const result = await ensureBaseBranch(state.repo, "epic/raced", "tok");
+      assertEquals(result, "exists");
+    } finally {
+      globalThis.fetch = prevFetch;
+      if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+      else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    }
+  },
+);
+
+test("ensureBaseBranch: missing non-epic/* branch throws BaseBranchMustExistError", async () => {
+  const state: FakeRepo = {
+    repo: "o/typo",
+    defaultBranch: "main",
+    branches: new Map([["main", "defaulthead"]]),
+    creates: [],
+  };
+  const err = await withGithub(state, () =>
+    assertRejects(
+      () => ensureBaseBranch(state.repo, "feature/typo", "tok"),
+      BaseBranchMustExistError,
+      "feature/typo",
+    ),
+  );
+  assertEquals(err instanceof BaseBranchMustExistError, true);
+  // A rejected non-epic/* base must never spawn a wrong-rooted branch.
+  assertEquals(state.creates.length, 0);
+});