@nanobpm/nano-workforce 0.56.0 → 0.58.0

package/operations/revertEscalationCompletion.ts

@@ -0,0 +1,44 @@
+// POST /app/api/hooks/revert-completion → operationId `revertEscalationCompletion` (epic #156, slice
+// U6; ADR 0046 reversibility). A completed user task cannot be un-completed in the engine, so an
+// AGENT answer is never a silent irreversible commit: this endpoint lets a human mark a reversible
+// agent completion reverted/overridden, recording who did it and when. Host-side consumers read the
+// `task_completions` ledger to see whether the latest completion is still authoritative. Human
+// completions are not reversible (they are already the authority), and a completion can be reverted
+// only once. Optional shared-secret guard (x-hook-secret), enforced only when NANO_PR_WEBHOOK_SECRET
+// is set.
+
+import { revertAgentCompletion } from "../app/agentCompletion.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const WEBHOOK_SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("revertEscalationCompletion", async ({ req, body }, app) => {
+  if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_SECRET) {
+    app.log.warn("revert-completion rejected: missing/invalid shared secret");
+    return { status: 401, body: { ok: false, error: "unauthorized" } };
+  }
+  if (!body || typeof body !== "object") {
+    app.log.warn("revert-completion rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "completionId and reverterId are required" } };
+  }
+
+  const completionId = typeof body.completionId === "number" ? body.completionId : Number.NaN;
+  const reverterId = str(body.reverterId);
+  const note = str(body.note);
+  if (!Number.isInteger(completionId)) {
+    return { status: 400, body: { ok: false, error: "completionId must be an integer" } };
+  }
+  if (!reverterId) return { status: 400, body: { ok: false, error: "reverterId is required" } };
+
+  const r = await revertAgentCompletion(app.data, completionId, { kind: "human", id: reverterId }, note);
+  if (r.ok) {
+    app.log.info("agent completion reverted", { completionId, reverterId });
+    return { status: 200, body: { ok: true, completionId: r.completionId } };
+  }
+  const status = r.reason === "no such completion" ? 404 : 400;
+  app.log.warn("revert-completion: not reverted", { completionId, reason: r.reason });
+  return { status, body: { ok: false, error: r.reason } };
+});

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);
   });
 });
@@ -162,61 +222,3 @@ test("postMessage → 400 when escalation-answered lacks a correlationKey", asyn
   assertEquals(r.status, 400);
   assertEquals(r.body.error, "correlationKey is required");
 });
-
-function planEscalationMessageApp() {
-  const plans = [{ plan_key: "owner/repo#12", open_plan_escalation_id: 1 }];
-  const escalations = [{
-    id: 1,
-    plan_key: "owner/repo#12",
-    epoch: 0,
-    round: 2,
-    findings: "needs guidance",
-    status: "open",
-    directive: null,
-    note: null,
-  }];
-  const published: any[] = [];
-  const match = (r: Record<string, unknown>, q: Record<string, unknown>) =>
-    Object.entries(q).every(([f, v]) => r[f] === v);
-  const table = (rows: any[], key: string) => ({
-    find: (q: any) => Promise.resolve(rows.filter((r) => match(r, q))),
-    update: (id: any, patch: any) => {
-      const row = rows.find((r) => r[key] === id);
-      if (row) Object.assign(row, patch);
-      return Promise.resolve(row);
-    },
-  });
-  return {
-    app: {
-      data: {
-        table(name: string) {
-          return name === "plans" ? table(plans, "plan_key") : table(escalations, "id");
-        },
-      },
-      engine: {
-        publishMessage: (m: any) => {
-          published.push(m);
-          return Promise.resolve();
-        },
-      },
-      log: noopLog(),
-    } as any as AppApi,
-    escalations,
-    published,
-  };
-}
-
-test("postMessage accepts mixed-case plan escalation directive like the dedicated hook", async () => {
-  const { app: msgApp, escalations, published } = planEscalationMessageApp();
-  const res = await postMessage(input({
-    name: "plan-escalation-answered",
-    correlationKey: "owner/repo#12",
-    variables: { directive: "PrOcEeD", note: "ship it" },
-  }), msgApp);
-  const r = res as any;
-  assertEquals(r.status, 200);
-  assertEquals(r.body.ok, true);
-  assertEquals(r.body.directive, "proceed");
-  assertEquals(escalations[0].directive, "proceed");
-  assertEquals(published[0].variables.planEscalationDirective, "proceed");
-});

package/operations/startFeature.ts

@@ -0,0 +1,127 @@
+// POST /app/api/actions/start/feature → operationId `startFeature` (ADR 0058/0059, base /app/api).
+// The ONE door for starting a SINGLE-issue feature run — the "missing middle" between Epics
+// (startPlanFanout) and PR convergence (startConvergenceLoop): hand one issue to a single
+// implementation agent that raises exactly one PR, then OPTIONALLY converge + merge (issue #172).
+//
+// The request body is FLAT (`{ issue | url, baseBranch, converge?, autoMerge? }`), not wrapped in a
+// `variables` envelope — a purpose-built operation, not a generic engine "start process" call. The
+// body is a `oneOf` — EXACTLY ONE of `issue` or `url` — so an empty or ambiguous target is a 400 at
+// the edge; this delegate narrows the validated variant and keeps the issue-FORMAT parse guard.
+//
+// Base-branch handling is IDENTICAL to the epic path: it reuses `admitPlan` (ADR 0003) verbatim, so
+// a feature run's PR is admitted through the same required+explicit / create-if-missing /
+// confirm-default / shared-base rules, with the same typed-error → HTTP mapping.
+
+import { startFeature } from "../app/feature.ts";
+import { BaseBranchMustExistError } from "../app/github.ts";
+import {
+  admitPlan,
+  DefaultBaseNotConfirmedError,
+  InvalidBaseBranchError,
+  MissingBaseBranchError,
+  parseIssue,
+  SharedBaseError,
+} from "../app/plan.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+export default defineOperation("startFeature", async ({ body }, app) => {
+  // The runtime validates a well-formed body against openapi.yaml, but a directly-invoked delegate
+  // (or a missing body) leaves `body` undefined — guard so that becomes a 400, not a 500 from `in`.
+  if (!body || typeof body !== "object") {
+    app.log.warn("start-feature rejected: missing request body");
+    return { status: 400, body: { error: "request body is required (owner/repo#123 or an issue URL)" } };
+  }
+  // The `oneOf` variant is normally narrowed by OpenAPI validation, but a directly-invoked delegate
+  // can pass a missing/mistyped `issue`/`url` — guard so that stays a 400, not a 500 from `.trim()`.
+  const target = "issue" in body ? body.issue : "url" in body ? body.url : undefined;
+  if (typeof target !== "string") {
+    app.log.warn("start-feature rejected: issue/url must be a string");
+    return { status: 400, body: { error: "issue or url must be a string (owner/repo#123 or an issue URL)" } };
+  }
+  const raw = target.trim();
+  const parsed = parseIssue(raw);
+  if (!parsed) {
+    app.log.warn("start-feature rejected: unparseable issue reference", { raw });
+    return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };
+  }
+  // Base branch (ADR 0003): admit the launch through the same fail-fast `admitPlan` gate the epic
+  // path uses BEFORE starting the run. A feature run also raises a PR against a base, so it honors
+  // the identical admission policy and error → HTTP mapping.
+  const rawBase = "baseBranch" in body && typeof body.baseBranch === "string" ? body.baseBranch : null;
+  const allowSharedBase = "allowSharedBase" in body && body.allowSharedBase === true;
+  const confirmDefaultBase = "confirmDefaultBase" in body && body.confirmDefaultBase === true;
+  const token = process.env.GITHUB_TOKEN ?? "";
+  let normalizedBase: string;
+  try {
+    // No `selfPlanKey`: a feature run creates a `feature_runs` row, NOT a `plans` row, so there is no
+    // own plan to exclude from the shared-base guard (rule 4). Passing `parsed.planKey` here would
+    // exclude an ACTIVE EPIC sharing the same `owner/repo#N` key, silently bypassing shared-base
+    // protection. Feature-run idempotency is enforced separately by `startFeature` on `feature_runs`.
+    normalizedBase = await admitPlan(app.data, parsed.repo, rawBase, token, {
+      allowSharedBase,
+      confirmDefaultBase,
+    });
+  } catch (err) {
+    if (err instanceof MissingBaseBranchError) {
+      app.log.warn("start-feature rejected: missing base branch");
+      return {
+        status: 400,
+        body: { error: "baseBranch is required (name the branch the PR targets, e.g. main or epic/agent-protocol)" },
+      };
+    }
+    if (err instanceof InvalidBaseBranchError) {
+      app.log.warn("start-feature rejected: invalid base branch", { baseBranch: err.value });
+      return {
+        status: 400,
+        body: { error: "invalid baseBranch (must be a plausible git branch name, e.g. main)" },
+      };
+    }
+    if (err instanceof BaseBranchMustExistError) {
+      app.log.warn("start-feature rejected: base branch does not exist", { baseBranch: err.branch });
+      return {
+        status: 400,
+        body: {
+          error:
+            `baseBranch "${err.branch}" does not exist and is not an epic/* branch, so it is not ` +
+            `auto-created — create it first, or use the epic/* convention`,
+        },
+      };
+    }
+    if (err instanceof DefaultBaseNotConfirmedError) {
+      app.log.warn("start-feature rejected: default base not confirmed", { baseBranch: err.branch });
+      return {
+        status: 400,
+        body: {
+          error:
+            `baseBranch "${err.branch}" is the repository default branch — the PR would target it ` +
+            `directly. Re-submit with confirmDefaultBase: true to proceed`,
+        },
+      };
+    }
+    if (err instanceof SharedBaseError) {
+      app.log.warn("start-feature rejected: shared base branch", { baseBranch: err.branch });
+      return {
+        status: 409,
+        body: {
+          error:
+            `baseBranch "${err.branch}" is already in use by another active epic. Re-submit with ` +
+            `allowSharedBase: true to stack on it, or name a distinct branch`,
+        },
+      };
+    }
+    throw err;
+  }
+  const converge = "converge" in body && body.converge === true;
+  // Auto-merge is only meaningful as a follow-on to convergence; pin it off when converge is off so
+  // the persisted row and the process variable can't disagree.
+  const autoMerge = converge && "autoMerge" in body && body.autoMerge === true;
+  const result = await startFeature(app.data, app.engine, parsed, normalizedBase, converge, autoMerge);
+  app.log.info("feature run started", {
+    featureKey: parsed.planKey,
+    requestedBaseBranch: normalizedBase,
+    converge,
+    autoMerge,
+    alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
+  });
+  return { status: 202, body: result };
+});

package/operations/startPlanFanout.admission.integration.test.ts

@@ -0,0 +1,263 @@
+// Integration coverage for the base-branch ADMISSION gate (ADR 0003) driven through the operation
+// EDGE — `startPlanFanout` → `admitPlan` → HTTP status. The unit tests in app/plan.test.ts already
+// prove `admitPlan`'s decision matrix in isolation; this file proves the COMPOSED behaviour at the
+// door: each admission rule maps to the correct HTTP status (400 / 409) and each accept path reaches
+// the 202 fan-out. It runs the real delegate against an in-memory app/data/engine and a faked github
+// transport (token mode + stubbed `globalThis.fetch`) — no network, deterministic on a single run.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { resetDefaultBranchCache } from "../app/github.ts";
+import { noopLog } from "../test/log.ts";
+import startPlanFanout from "./startPlanFanout.ts";
+
+// ── in-memory github model ───────────────────────────────────────────────────
+// A minimal fake of the GitHub REST surface `admitPlan` touches: the repo-meta GET (default branch),
+// the ref GET (branch existence, returning a synthetic per-branch head sha) and the ref-create POST.
+// `default_branch` is `main`; a missing `epic/*` base is auto-created off the default branch's head
+// sha (which `admitPlan` reads via the ref GET, so here that is `main-sha`). `creates` records the
+// full ref-create POST body (`ref` + `sha`) so a test can assert a branch was (or was NOT) created
+// AND that the create payload points the new ref at the resolved base sha, not a stale/blank value.
+interface GithubState {
+  repo: string;
+  defaultBranch: string;
+  branches: Set<string>;
+  creates: { ref: string; sha: string }[];
+}
+
+function githubFetch(state: GithubState) {
+  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;
+    const json = (obj: unknown, status = 200) =>
+      new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } });
+    if (method === "GET" && path === `/repos/${state.repo}`) {
+      return Promise.resolve(json({ default_branch: state.defaultBranch }));
+    }
+    const refPrefix = `/repos/${state.repo}/git/ref/heads/`;
+    if (method === "GET" && path.startsWith(refPrefix)) {
+      const branch = decodeURIComponent(path.slice(refPrefix.length));
+      if (!state.branches.has(branch)) return Promise.resolve(new Response("Not Found", { status: 404 }));
+      return Promise.resolve(json({ ref: `refs/heads/${branch}`, object: { sha: `${branch}-sha` } }));
+    }
+    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(json({ message: "Reference already exists" }, 422));
+      state.creates.push({ ref, sha });
+      state.branches.add(branch);
+      return Promise.resolve(json({ ref }, 201));
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(state: GithubState, fn: () => Promise<T>): Promise<T> {
+  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 another test's default-branch entry
+  globalThis.fetch = githubFetch(state) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    resetDefaultBranchCache();
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    if (prevTok === undefined) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = prevTok;
+  }
+}
+
+// ── in-memory app (data + engine) ────────────────────────────────────────────
+// A generic table over an array, matching the DataLayer surface `startPlan`/`findActivePlansByBase`
+// use (get/find/insert/update/delete). `seedPlans` pre-loads the `plans` table so the shared-base
+// guard has active rows to find. `started` records each engine.createInstance call so an accept path
+// can be asserted to have fanned out.
+function makeApp(seedPlans: Record<string, unknown>[] = []) {
+  const tables = new Map<string, Record<string, unknown>[]>();
+  tables.set("plans", [...seedPlans]);
+  const started: { processDefinitionId: string; variables?: Record<string, unknown> }[] = [];
+  const table = (name: string, key: string) => {
+    const rows = tables.get(name) ?? (() => {
+      const fresh: Record<string, unknown>[] = [];
+      tables.set(name, fresh);
+      return fresh;
+    })();
+    return {
+      get: (k: unknown) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+      find: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+      insert: (r: Record<string, unknown>) => {
+        rows.push(r);
+        return Promise.resolve(r);
+      },
+      update: (k: unknown, patch: Record<string, unknown>) => {
+        const row = rows.find((r) => r[key] === k);
+        if (row) Object.assign(row, patch);
+        return Promise.resolve(row);
+      },
+      delete: (k: unknown) => {
+        const i = rows.findIndex((r) => r[key] === k);
+        if (i >= 0) rows.splice(i, 1);
+        return Promise.resolve();
+      },
+    };
+  };
+  const app = {
+    data: { table },
+    engine: {
+      createInstance: (req: { processDefinitionId: string; variables?: Record<string, unknown> }) => {
+        started.push(req);
+        return Promise.resolve({ processInstanceKey: "PI-1" });
+      },
+    },
+    log: noopLog(),
+  } as any as AppApi;
+  return { app, started };
+}
+
+function input(body: unknown) {
+  return {
+    req: { method: "POST", path: "/", query: new URLSearchParams(), headers: new Headers(), text: async () => "" } as any,
+    params: {},
+    query: {},
+    body,
+  };
+}
+
+function freshGithub(repo: string, extraBranches: string[] = []): GithubState {
+  return { repo, defaultBranch: "main", branches: new Set(["main", ...extraBranches]), creates: [] };
+}
+
+// ── Rule 1 — required + explicit ──────────────────────────────────────────────
+
+// Rule 1 rejects both a MISSING baseBranch field and an explicit blank/whitespace
+// one — the latter is a distinct edge input that must not slip past as a "present"
+// value. Table-drive both so the required-and-explicit rule is covered end to end.
+for (const [label, body] of [
+  ["missing field", { issue: "owner/repo#1" }],
+  ["empty string", { issue: "owner/repo#1", baseBranch: "" }],
+  ["whitespace only", { issue: "owner/repo#1", baseBranch: "   " }],
+] as const) {
+  test(`edge: ${label} baseBranch → 400`, async () => {
+    const gh = freshGithub("owner/repo");
+    await withGithub(gh, async () => {
+      const { app, started } = makeApp();
+      const res = (await startPlanFanout(input(body), app)) as any;
+      assertEquals(res.status, 400);
+      assertEquals(typeof res.body.error, "string");
+      assertEquals(started.length, 0); // rejected before any fan-out
+      assertEquals(gh.creates, []); // no ref created on a rejected input
+    });
+  });
+}
+
+// ── Rule 2 — create-if-missing (epic/* guard), synchronously at the edge ──────
+
+test("edge: non-epic/* base that does not exist → 400 (BaseBranchMustExistError path)", async () => {
+  // A typo'd, non-epic/* base is NOT auto-created — admitPlan throws BaseBranchMustExistError
+  // synchronously, which the delegate maps to a clean 400 at the door (not a late per-task failure).
+  const gh = freshGithub("owner/repo"); // "release-9" absent, not epic/* → must-exist
+  await withGithub(gh, async () => {
+    const { app, started } = makeApp();
+    const res = (await startPlanFanout(input({ issue: "owner/repo#2", baseBranch: "release-9" }), app)) as any;
+    assertEquals(res.status, 400);
+    assertEquals(typeof res.body.error, "string");
+    assertEquals(started.length, 0);
+    assertEquals(gh.creates, []); // never created
+  });
+});
+
+test("edge: missing epic/* base → created off default HEAD, then 202", async () => {
+  const gh = freshGithub("owner/repo"); // epic/new absent → auto-created off main
+  await withGithub(gh, async () => {
+    const { app, started } = makeApp();
+    const res = (await startPlanFanout(input({ issue: "owner/repo#3", baseBranch: "epic/new" }), app)) as any;
+    assertEquals(res.status, 202);
+    // Created off the resolved base sha: the ref-create payload names epic/new AND points it at the
+    // default branch's head sha (`main-sha` here), proving the create body carries the base sha.
+    assertEquals(gh.creates, [{ ref: "refs/heads/epic/new", sha: "main-sha" }]);
+    assertEquals(started.length, 1);
+  });
+});
+
+// ── Rule 3 — confirm-default ──────────────────────────────────────────────────
+
+test("edge: target == default branch WITHOUT confirmDefaultBase → 400", async () => {
+  const gh = freshGithub("owner/repo"); // base "main" IS the default
+  await withGithub(gh, async () => {
+    const { app, started } = makeApp();
+    const res = (await startPlanFanout(input({ issue: "owner/repo#4", baseBranch: "main" }), app)) as any;
+    assertEquals(res.status, 400);
+    assertEquals(typeof res.body.error, "string");
+    assertEquals(started.length, 0);
+  });
+});
+
+test("edge: target == default branch WITH confirmDefaultBase → 202", async () => {
+  const gh = freshGithub("owner/repo");
+  await withGithub(gh, async () => {
+    const { app, started } = makeApp();
+    const res = (await startPlanFanout(
+      input({ issue: "owner/repo#5", baseBranch: "main", confirmDefaultBase: true }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    assertEquals(started.length, 1);
+  });
+});
+
+// ── Rule 4 — shared-base guard ────────────────────────────────────────────────
+
+test("edge: active plan on the same CUSTOM base WITHOUT allowSharedBase → 409", async () => {
+  const gh = freshGithub("owner/repo", ["epic/shared"]); // base exists → ensureBaseBranch no-ops
+  await withGithub(gh, async () => {
+    // A DIFFERENT active plan already targets epic/shared on this repo.
+    const { app, started } = makeApp([
+      { plan_key: "owner/repo#98", repo: "owner/repo", base_branch: "epic/shared", status: "planning" },
+    ]);
+    const res = (await startPlanFanout(input({ issue: "owner/repo#6", baseBranch: "epic/shared" }), app)) as any;
+    assertEquals(res.status, 409);
+    assertEquals(typeof res.body.error, "string");
+    assertEquals(started.length, 0);
+  });
+});
+
+test("edge: same CUSTOM base WITH allowSharedBase → 202", async () => {
+  const gh = freshGithub("owner/repo", ["epic/shared"]);
+  await withGithub(gh, async () => {
+    const { app, started } = makeApp([
+      { plan_key: "owner/repo#98", repo: "owner/repo", base_branch: "epic/shared", status: "planning" },
+    ]);
+    const res = (await startPlanFanout(
+      input({ issue: "owner/repo#7", baseBranch: "epic/shared", allowSharedBase: true }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    assertEquals(started.length, 1);
+  });
+});
+
+test("edge: two plans sharing the DEFAULT branch → 202 (default is exempt from the shared-base guard)", async () => {
+  const gh = freshGithub("owner/repo"); // base "main" == default → exempt
+  await withGithub(gh, async () => {
+    // An active plan already targets main; a second one is still admitted (confirmed default).
+    const { app, started } = makeApp([
+      { plan_key: "owner/repo#97", repo: "owner/repo", base_branch: "main", status: "planning" },
+    ]);
+    const res = (await startPlanFanout(
+      input({ issue: "owner/repo#8", baseBranch: "main", confirmDefaultBase: true }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    assertEquals(started.length, 1);
+  });
+});