@nanobpm/nano-workforce 0.57.0 → 0.58.0

package/e2e/plan-fanout.e2e.ts

@@ -0,0 +1,303 @@
+// End-to-end proof for the plan-fanout escalations migrated to native user tasks + forms
+// (epic #156, slice U2). Boots the whole app against the WASM engine and drives the REAL
+// plan-fanout.bpmn to each of its three human-decision points — the implementation-phase task
+// escalation, the plan-review cap escalation, and the trial-merge escalation — by registering stub
+// `senior:*` agent workers that steer the process. At each park it asserts the escalation is a
+// native `userTask`, then completes it via the engine's user-task API and asserts the TYPED
+// completion variables routed the downstream decision gateway.
+//
+// The gateway assertions are the falsifiable core (mirroring the U0 spine): the WASM engine folds a
+// completed instance's variables away, so we assert on the cumulative taken sequence flows instead
+// — an empty/wrong completion would take a different (default) branch. Each scenario boots its own
+// app so `takenSequenceFlows` (engine-global, cumulative) reflects exactly one instance's routing.
+//
+// Run with `npm run e2e`.
+
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { after, before, describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import type { EngineJob } from "@nanobpm/urban/runtime";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
+
+const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const GITHUB_ENV_OVERRIDES: Record<string, string> = {
+  NANO_PR_GITHUB_TRANSPORT: "token",
+  GITHUB_TOKEN: "",
+};
+
+interface InboxTask {
+  userTaskKey: string;
+  elementId?: string;
+  variables?: Record<string, unknown>;
+}
+
+interface TakenFlow {
+  from: string;
+  to: string;
+}
+
+function takenFlows(app: TestApp): string[] {
+  const snapshot = app.snapshot();
+  const flows = Array.isArray(snapshot.takenSequenceFlows) ? snapshot.takenSequenceFlows : [];
+  return flows
+    .filter((f): f is TakenFlow => typeof f === "object" && f !== null && "from" in f && "to" in f)
+    .map((f) => `${f.from}->${f.to}`);
+}
+
+/** A stub `senior:*` agent worker. Handlers are keyed by job type; each returns the process
+ *  variables the real agent would emit. */
+type Stub = (job: EngineJob) => Record<string, unknown> | void;
+
+describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → userTask + form)", () => {
+  const savedEnv = new Map<string, string | undefined>();
+  let restoreGithub: (() => void) | undefined;
+
+  before(() => {
+    for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
+      savedEnv.set(k, process.env[k]);
+      process.env[k] = v;
+    }
+    // ADR 0003: `startPlanFanout` + the `pr.ensure-base-branch` head task now pass through base
+    // admission, which reads/creates the base ref. Pin the hermetic `token` transport + fetch stub.
+    restoreGithub = installAdmitGithub(admitGithubState("owner/repo", "main"));
+  });
+
+  after(() => {
+    restoreGithub?.();
+    for (const [k, v] of savedEnv) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+  });
+
+  /** Boot a fresh app (isolated engine + DB), register the given `senior:*` stubs, run `body`, and
+   *  tear down. Each scenario gets its own engine so `takenSequenceFlows` is that run's alone. */
+  async function withApp(
+    stubs: Record<string, Stub>,
+    body: (ctx: { app: TestApp; planKey: string; processKey: string }) => Promise<void>,
+  ): Promise<void> {
+    const dbDir = mkdtempSync(join(tmpdir(), "nwf-u2-"));
+    const app = await bootTestApp(APP_ROOT, {
+      env: { NANO_APP_DB_URL: `file:${join(dbDir, "app.db")}` },
+    });
+    try {
+      for (const [jobType, stub] of Object.entries(stubs)) {
+        await app.engine.registerWorker(jobType, async (job) => stub(job) ?? undefined);
+      }
+      const planKey = "owner/repo#1";
+      const started = await app.api?.call("startPlanFanout", { body: { issue: planKey, baseBranch: "epic/e2e" } });
+      assert.equal(started?.status, 202, "startPlanFanout accepted the issue");
+      await app.settle();
+      const plan = await app.db
+        .table<{ plan_key: string; process_key: string | null }>("plans", "plan_key")
+        .findOne({ plan_key: planKey });
+      assert.ok(plan?.process_key, "the plan row carries the engine process-instance key");
+      await body({ app, planKey, processKey: plan!.process_key! });
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  }
+
+  async function openTask(app: TestApp, processKey: string, elementId: string): Promise<InboxTask> {
+    const tasks = await app.engine.searchUserTasks({ processInstanceKey: processKey });
+    const match = tasks.find((t) => t.elementId === elementId);
+    assert.ok(match, `expected an open ${elementId} user task (open: ${tasks.map((t) => t.elementId).join(", ")})`);
+    return match!;
+  }
+
+  // A planner that emits a single independent task, and a reviewer that approves — the shortest
+  // path to the implementation phase where the task escalation lives.
+  const singleTaskPlan: Stub = () => ({ tasks: [{ id: "t1", title: "T1", prompt: "do t1" }] });
+  const approveReview: Stub = () => ({ approved: true, findings: "" });
+
+  test("task escalation: a native userTask parks the child; answering routes back to implement-task", async () => {
+    let featureCalls = 0;
+    await withApp(
+      {
+        "senior:plan": singleTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": () => {
+          featureCalls += 1;
+          return featureCalls === 1
+            ? { status: "escalated", question: "Which API should I use?", summary: "parked for a human" }
+            : { status: "blocked", summary: "resumed after answer" };
+        },
+      },
+      async ({ app, processKey }) => {
+        const task = await openTask(app, processKey, "feature-escalation");
+        assert.ok(task.userTaskKey, "the feature escalation carries a completable userTaskKey");
+
+        // Answer it: the typed resolution loops the child back to re-dispatch the SAME task.
+        await app.engine.completeUserTask(task.userTaskKey, { resolution: "answer", answer: "use v2" });
+        await app.settle();
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("w_gw_answer->implement-task"),
+          `answer routed back to implement-task (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(
+          !flows.includes("w_gw_answer->w_end"),
+          "the abandon (default) flow was NOT taken",
+        );
+      },
+    );
+  });
+
+  test("task escalation: abandoning routes to the task-done end (default flow)", async () => {
+    await withApp(
+      {
+        "senior:plan": singleTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": () => ({
+          status: "escalated",
+          question: "Blocked — abandon?",
+          summary: "parked",
+        }),
+      },
+      async ({ app, processKey }) => {
+        const task = await openTask(app, processKey, "feature-escalation");
+        await app.engine.completeUserTask(task.userTaskKey, { resolution: "abandon" });
+        await app.settle();
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("w_gw_answer->w_end"),
+          `abandon routed to the task-done end (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(
+          !flows.includes("w_gw_answer->implement-task"),
+          "the answer loop was NOT taken",
+        );
+      },
+    );
+  });
+
+  test("plan-review escalation: proceed overrides the gate and routes to select-wave", async () => {
+    await withApp(
+      {
+        "senior:plan": singleTaskPlan,
+        "senior:plan-review": () => ({ approved: false, findings: "not good enough" }),
+        "senior:feature": () => ({ status: "blocked", summary: "n/a" }),
+      },
+      async ({ app, processKey }) => {
+        const task = await openTask(app, processKey, "plan-review-decision");
+        await app.engine.completeUserTask(task.userTaskKey, { directive: "proceed", notes: "ship it" });
+        await app.settle();
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("gw-plan-answer->select-wave"),
+          `proceed routed to select-wave (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(
+          !flows.includes("gw-plan-answer->plan"),
+          "the revise (default) flow was NOT taken",
+        );
+      },
+    );
+  });
+
+  test("plan-review escalation: revise loops back to plan and resets the review epoch", async () => {
+    await withApp(
+      {
+        "senior:plan": singleTaskPlan,
+        "senior:plan-review": () => ({ approved: false, findings: "still not good" }),
+        "senior:feature": () => ({ status: "blocked", summary: "n/a" }),
+      },
+      async ({ app, planKey, processKey }) => {
+        const task = await openTask(app, processKey, "plan-review-decision");
+        await app.engine.completeUserTask(task.userTaskKey, { directive: "revise", notes: "narrow scope" });
+        await app.settle();
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("gw-plan-answer->plan"),
+          `revise routed back to plan (flows: ${flows.join(", ")})`,
+        );
+
+        // The user task bumped `planReviewEpoch`; record-plan-review derived the fresh epoch and
+        // reset the round budget — proving the epoch is computed from completed plan-review tasks
+        // across rounds (epoch 0's rounds, then a fresh epoch 1 round 0 after the human revise).
+        const reviews = await app.db
+          .table<{ plan_key: string; epoch: number; round: number }>("plan_reviews", "plan_key")
+          .find({ plan_key: planKey });
+        assert.ok(
+          reviews.some((r) => r.epoch === 0),
+          "the first review epoch (0) was recorded",
+        );
+        assert.ok(
+          reviews.some((r) => r.epoch === 1 && r.round === 0),
+          `a fresh epoch 1 round 0 was recorded after revise (epochs: ${reviews.map((r) => `${r.epoch}.${r.round}`).join(", ")})`,
+        );
+      },
+    );
+  });
+
+  // A two-task wave whose PRs both open triggers the D3 trial-merge gate; a suite-failed trial
+  // parks on the trial-merge decision user task.
+  const twoTaskPlan: Stub = () => ({
+    tasks: [
+      { id: "t1", title: "T1", prompt: "do t1" },
+      { id: "t2", title: "T2", prompt: "do t2" },
+    ],
+  });
+  const openBothPrs: Stub = (job) => {
+    const taskId = (job.variables as { task?: { id?: string } }).task?.id;
+    return taskId === "t2"
+      ? { status: "opened", pr: "owner/repo#102", summary: "opened t2" }
+      : { status: "opened", pr: "owner/repo#101", summary: "opened t1" };
+  };
+  const trialSuiteFailed: Stub = () => ({ result: "suite-failed", failing: "combined suite red" });
+
+  async function driveToTrialDecision(
+    action: string,
+  ): Promise<string[]> {
+    let flows: string[] = [];
+    await withApp(
+      {
+        "senior:plan": twoTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": openBothPrs,
+        "senior:trial-merge": trialSuiteFailed,
+      },
+      async ({ app, processKey }) => {
+        const task = await openTask(app, processKey, "trial-merge-decision");
+        await app.engine.completeUserTask(task.userTaskKey, { action, notes: `chose ${action}` });
+        await app.settle();
+        flows = takenFlows(app);
+      },
+    );
+    return flows;
+  }
+
+  test("trial-merge escalation: proceed routes to the more-waves gate", async () => {
+    const flows = await driveToTrialDecision("proceed");
+    assert.ok(
+      flows.includes("gw-trial-answer->gw-more"),
+      `proceed routed to gw-more (flows: ${flows.join(", ")})`,
+    );
+  });
+
+  test("trial-merge escalation: rebase re-runs the trial merge (default flow)", async () => {
+    const flows = await driveToTrialDecision("rebase");
+    assert.ok(
+      flows.includes("gw-trial-answer->trial-merge"),
+      `rebase routed back to trial-merge (flows: ${flows.join(", ")})`,
+    );
+  });
+
+  test("trial-merge escalation: abandon finalizes the plan", async () => {
+    const flows = await driveToTrialDecision("abandon");
+    assert.ok(
+      flows.includes("gw-trial-answer->record-results"),
+      `abandon routed to record-results (flows: ${flows.join(", ")})`,
+    );
+  });
+});

package/e2e/retire-escalation-subsystem.e2e.ts

@@ -0,0 +1,223 @@
+// Migration-path regression proof for retiring the bespoke escalation subsystem (epic #156, slice
+// U7 — the destructive CONTRACT phase). Boots the whole app against the WASM engine so migration
+// `027_retire_escalation_subsystem.sql` is applied on top of the full ledger, then proves three
+// things about the retired surface:
+//
+//   1. Schema contract — the superseded tables (`plan_escalations`, `plan_review_escalations`) and
+//      the denormalised pointer columns (`pull_requests.open_escalation_*`, `plans.open_task_*` /
+//      `open_plan_*`) are GONE, while the kept audit surface (`escalations`) survives intact. This
+//      is the falsifiable core of the contract phase — an over-drop or an un-applied migration
+//      fails here.
+//   2. No resurrected answer surface — the retired out-of-band answer webhooks
+//      (`/app/api/hooks/feature-answer`, `/app/api/hooks/plan-answer`) 404. The task inbox is now
+//      the single answer place; a stray bespoke route must not linger.
+//   3. Post-migration round-trip — an escalation still round-trips through a native `userTask` + the
+//      task inbox with the drained-old / re-issued-new path intact: the open escalation is DERIVED
+//      from the `escalations` audit row (no denormalised pointer resurfaces), answering it via the
+//      inbox resumes the loop, and no addressed escalation lingers afterwards.
+//
+// Run with `npm run e2e`.
+
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { after, before, describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+
+const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const DB_DIR = mkdtempSync(join(tmpdir(), "nwf-u7-"));
+
+const GITHUB_ENV_OVERRIDES: Record<string, string> = {
+  NANO_PR_GITHUB_TRANSPORT: "token",
+  GITHUB_TOKEN: "",
+};
+const savedEnv = new Map<string, string | undefined>();
+
+const HARNESS_ENV = {
+  NANO_APP_DB_URL: `file:${join(DB_DIR, "app.db")}`,
+} as const;
+
+interface InboxTask {
+  userTaskKey: string;
+  elementId?: string;
+  variables?: Record<string, unknown>;
+}
+
+interface StatusBody {
+  prs: Array<{ prKey: string; status: string; openEscalation: string | null }>;
+}
+
+interface TableInfoRow {
+  name: string;
+}
+
+interface MasterRow {
+  name: string;
+}
+
+async function columnNames(app: TestApp, table: string): Promise<string[]> {
+  const rows = await app.db.open().query<TableInfoRow>(`PRAGMA table_info(${table})`);
+  return rows.map((r) => r.name);
+}
+
+async function tableExists(app: TestApp, table: string): Promise<boolean> {
+  const rows = await app.db
+    .open()
+    .query<MasterRow>("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?", [table]);
+  return rows.length > 0;
+}
+
+describe("retire escalation subsystem (U7 — destructive contract phase)", () => {
+  let app: TestApp;
+  let reviewCalls = 0;
+  let capturedAnswer: unknown;
+
+  before(async () => {
+    for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
+      savedEnv.set(k, process.env[k]);
+      process.env[k] = v;
+    }
+    app = await bootTestApp(APP_ROOT, { env: HARNESS_ENV });
+    await app.engine.registerWorker("senior:pr-review", (job) => {
+      reviewCalls += 1;
+      if (reviewCalls === 1) {
+        return { status: "needs_input", summary: "need a human decision", question: "Which retry cap?" };
+      }
+      capturedAnswer = (job.variables as Record<string, unknown>).answer;
+      return { status: "converged", summary: "resolved after the human answer" };
+    });
+  });
+
+  after(async () => {
+    await app?.stop();
+    for (const [k, v] of savedEnv) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+    rmSync(DB_DIR, { recursive: true, force: true });
+  });
+
+  test("migration 023 drops the superseded tables and denormalised columns but keeps the audit surface", async () => {
+    // The retirement migration is recorded in the ledger (it actually ran on top of the full stack).
+    const applied = app.db.source().migrationsApplied;
+    assert.ok(
+      applied.some((m) => m.includes("027_retire_escalation_subsystem")),
+      `migration 023 is in the applied ledger (applied: ${applied.join(", ")})`,
+    );
+
+    // Superseded escalation tables are gone.
+    assert.equal(await tableExists(app, "plan_escalations"), false, "plan_escalations table dropped");
+    assert.equal(
+      await tableExists(app, "plan_review_escalations"),
+      false,
+      "plan_review_escalations table dropped",
+    );
+
+    // Denormalised pointer columns on pull_requests are gone (the open escalation is derived, not stored).
+    const prCols = await columnNames(app, "pull_requests");
+    assert.ok(prCols.length > 0, "pull_requests table still exists");
+    for (const dropped of ["open_escalation_id", "open_escalation_question"]) {
+      assert.ok(!prCols.includes(dropped), `pull_requests.${dropped} column dropped`);
+    }
+
+    // Denormalised pointer columns on plans are gone.
+    const planCols = await columnNames(app, "plans");
+    assert.ok(planCols.length > 0, "plans table still exists");
+    for (const dropped of [
+      "open_task_escalation_id",
+      "open_task_question",
+      "open_task_corr_key",
+      "open_task_id",
+      "open_plan_escalation_id",
+      "open_plan_findings",
+      "open_plan_round",
+    ]) {
+      assert.ok(!planCols.includes(dropped), `plans.${dropped} column dropped`);
+    }
+
+    // The kept audit surface survives — over-dropping it would break the merge-loop escalation.
+    assert.equal(await tableExists(app, "escalations"), true, "escalations audit table is retained");
+    const escCols = await columnNames(app, "escalations");
+    assert.ok(escCols.includes("pr_key"), "escalations retains its pr_key column");
+    assert.ok(escCols.includes("question"), "escalations retains its question column");
+  });
+
+  test("the retired out-of-band answer webhooks are gone — the task inbox is the single answer place", async () => {
+    for (const path of ["/app/api/hooks/feature-answer", "/app/api/hooks/plan-answer"]) {
+      const res = await app.callRoute({
+        method: "POST",
+        path,
+        body: JSON.stringify({ answer: "x" }),
+      });
+      assert.equal(res.status, 404, `retired webhook ${path} is unmounted (404)`);
+    }
+  });
+
+  test("an escalation still round-trips via userTask + inbox with no denormalised pointer or dead form", async () => {
+    const api = app.api;
+    assert.ok(api, "the OpenAPI driver is available");
+
+    const prKey = "acme/widgets#701";
+    const started = await api.call<{ prKey: string }>("startConvergenceLoop", {
+      body: { pr: prKey, convergeOnly: true },
+    });
+    assert.equal(started.status, 202, "start returns 202 Accepted");
+
+    const prs = app.db.table<{ pr_key: string; status: string; process_key: string | null }>(
+      "pull_requests",
+      "pr_key",
+    );
+    const row = await prs.findOne({ pr_key: prKey });
+    assert.ok(row?.process_key, "the PR row carries the engine process-instance key");
+    const processInstanceKey = row!.process_key!;
+
+    // Drain the first review round: it parks on the native `wait-answer` userTask.
+    await app.settle();
+
+    // The escalation is a native userTask surfaced through the inbox — not a bespoke answer form.
+    const listed = await app.callRoute<InboxTask[]>({
+      method: "GET",
+      path: "/tasks/api/tasks",
+      query: { processInstanceKey },
+    });
+    assert.equal(listed.status, 200, "the taskInbox surface serves the task list");
+    assert.equal(listed.body.length, 1, "exactly one escalation userTask is open");
+    const task = listed.body[0];
+    assert.equal(task.elementId, "wait-answer", "the open task is the review-loop escalation userTask");
+    assert.ok(task.userTaskKey, "the task carries a completable userTaskKey");
+
+    // The open escalation is DERIVED from the durable audit row — no denormalised pointer is written.
+    const status = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
+    const statusRow = status.body.prs.find((p) => p.prKey === prKey);
+    assert.equal(statusRow?.status, "escalated", "the PR reads as escalated");
+    assert.equal(
+      statusRow?.openEscalation,
+      "Which retry cap?",
+      "the open escalation question is derived from the escalations audit row",
+    );
+
+    // Answer through the inbox completion route with the typed `answer` (the re-issued-new path).
+    const answer = "Cap the retries at 5 and proceed.";
+    const completed = await app.callRoute<{ ok: boolean }>({
+      method: "POST",
+      path: "/tasks/api/complete",
+      body: JSON.stringify({ userTaskKey: task.userTaskKey, variables: { answer } }),
+    });
+    assert.equal(completed.status, 200, "the completion route accepts the typed submission");
+    assert.equal(completed.body.ok, true, "the userTask was completed");
+
+    // The answer resumed the loop and reached the resumed review round (drained-old path).
+    await app.settle();
+    assert.equal(reviewCalls, 2, "the review agent ran a second round after the answer");
+    assert.equal(capturedAnswer, answer, "the typed answer reached the resumed review round");
+
+    // No addressed escalation lingers — the audit row is the single source of truth.
+    const afterStatus = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
+    const afterRow = afterStatus.body.prs.find((p) => p.prKey === prKey);
+    if (afterRow) {
+      assert.equal(afterRow.openEscalation, null, "no open escalation lingers after the answer");
+    }
+  });
+});

package/e2e/support/github-admit.ts

@@ -0,0 +1,99 @@
+// Shared hermetic GitHub stub for the ADR-0003 base-branch admission (`admitPlan` +
+// the `pr.ensure-base-branch` head task). The e2e suites that drive `startPlanFanout` now
+// pass through admission, which reads the default branch, checks the base ref, and creates a
+// missing `epic/*` base off default HEAD. There is no network in e2e, so we pin the `token`
+// transport (`useGh()` is always false in `token` mode → every call routes through `fetch`,
+// never the `gh` subprocess) and intercept `globalThis.fetch` for the three admission
+// endpoints. This mirrors `workers/ensure-base-branch/head-task.integration.test.ts`.
+//
+// The live nightly exercises the real `gh` transport against GitHub; this stub deliberately
+// only covers the hermetic `token` path.
+import { resetDefaultBranchCache } from "../../app/github.ts";
+
+export interface AdmitGithubState {
+  repo: string;
+  defaultBranch: string;
+  branches: Map<string, string>; // branch → head sha
+  creates: { ref: string; sha: string }[];
+  resets: string[]; // any PATCH/force-update on an existing ref (must stay empty)
+}
+
+/** Build a fresh admit-github state with the default branch pre-seeded with a HEAD sha so an
+ *  `epic/*` base can be created off it. */
+export function admitGithubState(
+  repo = "owner/repo",
+  defaultBranch = "main",
+): AdmitGithubState {
+  return {
+    repo,
+    defaultBranch,
+    branches: new Map([[defaultBranch, "0".repeat(40)]]),
+    creates: [],
+    resets: [],
+  };
+}
+
+function admitFetch(state: AdmitGithubState) {
+  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" } });
+
+    // GET /repos/{repo} → default branch (fetchDefaultBranch).
+    if (method === "GET" && path === `/repos/${state.repo}`) {
+      return Promise.resolve(json({ default_branch: state.defaultBranch }));
+    }
+    // GET /repos/{repo}/git/ref/heads/{branch} → head sha or 404 (branchHeadSha).
+    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(json({ ref: `refs/heads/${branch}`, object: { sha } }));
+    }
+    // POST /repos/{repo}/git/refs → create a ref (createBranchRef); 422 if it already exists.
+    if (method === "POST" && path === `/repos/${state.repo}/git/refs`) {
+      // biome-ignore lint/plugin: runtime contract boundary for parsed JSON
+      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.set(branch, sha);
+      return Promise.resolve(json({ ref }, 201));
+    }
+    // A ref force-update (reset) would be a PATCH; the idempotent head task must NEVER issue one.
+    if (method === "PATCH" && path.startsWith(`/repos/${state.repo}/git/refs/heads/`)) {
+      state.resets.push(decodeURIComponent(path.split("/git/refs/heads/")[1] ?? ""));
+      return Promise.resolve(json({ ok: true }));
+    }
+    // Any other endpoint is a best-effort read the sealed transport used to skip → 404 (null).
+    return Promise.resolve(new Response("Not Found", { status: 404 }));
+  };
+}
+
+/** Install the hermetic admit-github stub: pin the `token` transport with a dummy token and swap
+ *  `globalThis.fetch`. Returns a restore function that reverts env + fetch and clears the
+ *  default-branch cache so no state leaks between suites. */
+export function installAdmitGithub(state: AdmitGithubState): () => 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"] = "e2e-admit-token";
+  resetDefaultBranchCache();
+  globalThis.fetch = admitFetch(state) as typeof fetch;
+  return () => {
+    globalThis.fetch = prevFetch;
+    resetDefaultBranchCache();
+    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;
+  };
+}