@nanobpm/nano-workforce 0.56.0 → 0.58.0

package/resources/processes/spine-demo.bpmn

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:nano="https://nanobpm.io/schema/shapes/1.0" id="Definitions_nano_workforce_spine_demo" targetNamespace="http://nanobpm.io/nano-workforce">
+  <bpmn:process id="spine-demo" name="User-task Spine Demo" isExecutable="true">
+    <bpmn:startEvent id="start">
+      <bpmn:outgoing>flow-to-decide</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:userTask id="decide" name="Decide">
+      <bpmn:extensionElements>
+        <zeebe:formDefinition formId="spine-demo" />
+        <zeebe:userTask />
+      </bpmn:extensionElements>
+      <bpmn:incoming>flow-to-decide</bpmn:incoming>
+      <bpmn:outgoing>flow-to-gateway</bpmn:outgoing>
+    </bpmn:userTask>
+    <bpmn:exclusiveGateway id="gw-decision" name="decision?" default="flow-rejected">
+      <bpmn:incoming>flow-to-gateway</bpmn:incoming>
+      <bpmn:outgoing>flow-approved</bpmn:outgoing>
+      <bpmn:outgoing>flow-rejected</bpmn:outgoing>
+    </bpmn:exclusiveGateway>
+    <bpmn:endEvent id="end-approved">
+      <bpmn:incoming>flow-approved</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:endEvent id="end-rejected">
+      <bpmn:incoming>flow-rejected</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="flow-to-decide" sourceRef="start" targetRef="decide" />
+    <bpmn:sequenceFlow id="flow-to-gateway" sourceRef="decide" targetRef="gw-decision" />
+    <bpmn:sequenceFlow id="flow-approved" sourceRef="gw-decision" targetRef="end-approved">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=decision = "approve"</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="flow-rejected" sourceRef="gw-decision" targetRef="end-rejected" />
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_spine-demo">
+    <bpmndi:BPMNPlane id="BPMNPlane_spine-demo" bpmnElement="spine-demo">
+      <bpmndi:BPMNShape id="BPMNShape_start" bpmnElement="start">
+        <dc:Bounds x="80" y="102" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_decide" bpmnElement="decide">
+        <dc:Bounds x="216" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_gw-decision" bpmnElement="gw-decision" isMarkerVisible="true">
+        <dc:Bounds x="416" y="95" width="50" height="50" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="408" y="76" width="67" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_end-approved" bpmnElement="end-approved">
+        <dc:Bounds x="566" y="262" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_end-rejected" bpmnElement="end-rejected">
+        <dc:Bounds x="566" y="102" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="BPMNEdge_flow-to-decide" bpmnElement="flow-to-decide">
+        <di:waypoint x="116" y="120" />
+        <di:waypoint x="216" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_flow-to-gateway" bpmnElement="flow-to-gateway">
+        <di:waypoint x="316" y="120" />
+        <di:waypoint x="416" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_flow-rejected" bpmnElement="flow-rejected">
+        <di:waypoint x="466" y="120" />
+        <di:waypoint x="566" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_flow-approved" bpmnElement="flow-approved">
+        <di:waypoint x="441" y="145" />
+        <di:waypoint x="441" y="280" />
+        <di:waypoint x="566" y="280" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>

package/scripts/check-migrations.ts

@@ -0,0 +1,68 @@
+// check-migrations — merge-safety gate for the forward-only SQLite migrations under db/migrations/.
+//
+// Migrations are numbered by a leading 3-digit prefix and applied in prefix order (nano.app.json
+// data.sources.app.migrations). AGENTS.md tells every author to "number a new migration after the
+// current highest prefix" — but that number is computed independently in each worktree. When an
+// epic fans a fleet out across parallel branches, two siblings both take "the next" free prefix
+// and emit e.g. 023_agentic_presence.sql and 023_agentic_transcript.sql. Those filenames don't
+// textually conflict, so git merges both cleanly and the collision is SILENT: two migrations now
+// share an apply-order slot. This exact failure mode already scarred the repo (the historical
+// 004/005/006/007 duplicate pairs) and recurred on epic #142 despite the doc note added by the
+// #160 retro (PR #178) — so we escalate the lesson from a doc line to a mechanical gate.
+//
+// The rule: no two migration files may share a numeric prefix. The pre-existing historical
+// duplicates are forward-only and already applied, so they cannot be renamed — they are
+// grandfathered in GRANDFATHERED_DUPES. Any NEW duplicate prefix fails the build.
+import { readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MIGRATIONS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "db", "migrations");
+
+// Historical collisions that predate this gate. Forward-only + already applied ⇒ cannot be
+// renumbered. New duplicates are NOT allowed here — fix them before merge.
+const GRANDFATHERED_DUPES: ReadonlySet<string> = new Set(["004", "005", "006", "007"]);
+
+const PREFIX = /^(\d{3})_[^/]*\.sql$/;
+
+function main(): void {
+  const files = readdirSync(MIGRATIONS_DIR)
+    .filter((f) => f.endsWith(".sql"))
+    .sort();
+
+  const errors: string[] = [];
+  const byPrefix = new Map<string, string[]>();
+
+  for (const file of files) {
+    const m = PREFIX.exec(file);
+    if (!m) {
+      errors.push(
+        `  ${file}: does not match the required NNN_name.sql shape (3-digit prefix, underscore, name).`,
+      );
+      continue;
+    }
+    const prefix = m[1];
+    const group = byPrefix.get(prefix) ?? [];
+    group.push(file);
+    byPrefix.set(prefix, group);
+  }
+
+  for (const [prefix, group] of byPrefix) {
+    if (group.length > 1 && !GRANDFATHERED_DUPES.has(prefix)) {
+      errors.push(
+        `  prefix ${prefix} is used by ${group.length} files: ${group.join(", ")} — ` +
+          `two migrations cannot share an apply-order slot. Renumber the newer one to the next ` +
+          `free prefix (check origin/main, not your branch point).`,
+      );
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error(`check-migrations: db/migrations has colliding prefixes:\n${errors.join("\n")}`);
+    process.exit(1);
+  }
+
+  console.log(`check-migrations: OK (${files.length} migrations, no colliding prefixes).`);
+}
+
+main();

package/workers/answer-escalation/worker.ts

@@ -0,0 +1,78 @@
+// pr.answer-escalation — retires the review-loop escalation the operator just answered.
+//
+// The review-loop escalation is a native `wait-answer` userTask (backed by `pr-escalation.form`).
+// Completing that task resumes the token, but the engine folds the completed instance's variables
+// away — so without this step the durable `escalations` audit row raised by `pr.persist-escalation`
+// would stay `status="open"` forever, its `answer`/`answered_at` never recorded. That both loses the
+// Q&A audit trail and (because `activePrs` derives `openEscalation` from the open-row status — the
+// single source of truth, ADR "derivation over duplication") would keep surfacing a phantom open
+// escalation on `/status` after it was answered.
+//
+// This mirrors the merge-loop's message-catch answer path (`answerEscalation` in app/service.ts):
+// both answer the newest still-open `escalations` row, mark any duplicate open rows `stale` (a
+// retry of `pr.persist-escalation` can leave more than one open), AND move the `pull_requests` row
+// off `status="escalated"` back to `"converging"`, so an answered escalation is never left dangling
+// and `/status` never shows an escalated PR with a null question or a phantom open row. The token
+// resume itself is owned by the engine (userTask completion), so this worker only reconciles the
+// durable rows; it returns no variables, leaving the submitted `answer` untouched so it flows on to
+// the next review round.
+import type { AppJobHandler } from "@nanobpm/urban";
+
+interface Escalation extends Record<string, unknown> {
+  id: number;
+  pr_key: string;
+  status: string;
+  answer: string | null;
+  answered_at: string | null;
+}
+
+// The PR-row fields this worker reconciles when an escalation is answered. Only `status`/`updated_at`
+// are written (mirroring `answerEscalation`); the rest of the row is untouched.
+interface PullRequest extends Record<string, unknown> {
+  pr_key: string;
+  status: string;
+  updated_at: string;
+}
+
+interface In extends Record<string, unknown> {
+  prKey: string;
+  answer?: string;
+}
+
+// A string variable, or undefined when it is absent/blank. The form marks `answer` required, so a
+// blank here would be an out-of-band completion; record it as NULL rather than an empty string.
+function nonBlank(v: unknown): string | undefined {
+  return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
+}
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  const { prKey } = job.variables;
+  const answer = nonBlank(job.variables.answer);
+  const escs = app.data.table<Escalation>("escalations", "id");
+  // Retire EVERY still-open escalation for this PR. `pr.persist-escalation` always INSERTs a new
+  // open row, so a retry/duplicate activation can leave more than one open — answering only the
+  // newest would leave an older duplicate `open`, a phantom `activePrs` keeps deriving while the PR
+  // is still `escalated`. Answer the newest (it carries the operator's reply) and mark any remaining
+  // open rows `stale`, mirroring `answerEscalation` and `submitPr`'s resubmit cleanup.
+  const open = (await escs.find({ pr_key: prKey, status: "open" })).sort((a, b) => b.id - a.id);
+  if (open.length > 0) {
+    const ts = new Date().toISOString();
+    await escs.update(open[0].id, {
+      answer: answer ?? null,
+      status: "answered",
+      answered_at: ts,
+    });
+    for (const dup of open.slice(1)) {
+      await escs.update(dup.id, { status: "stale" });
+    }
+    // Mirror the merge loop's `answerEscalation`: move the PR off `status="escalated"` back to
+    // `"converging"` now that the question is answered. Without this the row stays `escalated` (with
+    // a now-null derived `openEscalation`) until the re-entered round's `persist-round` runs — a
+    // `/status` inconsistency and a divergence from the merge path both loops are meant to share.
+    const prs = app.data.table<PullRequest>("pull_requests", "pr_key");
+    await prs.update(prKey, { status: "converging", updated_at: ts });
+  }
+  return {};
+};
+
+export default handler;

package/workers/converge-feature/worker.ts

@@ -0,0 +1,51 @@
+// pr.converge-feature — hand a single-issue run's opened PR to the convergence loop (issue #172).
+//
+// Reached only via the `converge?` gateway's true branch (converge requested AND the agent opened a
+// keyed PR). Reuses `submitPr` — the SAME enrollment the epic waves and the standalone
+// `startConvergenceLoop` action use — so a feature run's PR gets identical review-round + merge
+// behaviour with no duplicated machinery. `autoMerge` maps to `submitPr`'s `convergeOnly`
+// (inverted): auto-merge → drive the merge-loop; otherwise stop at `converged`.
+//
+// The feature-run's OWN process ends here; the PR's live convergence/merge state lives on the
+// `pull_requests` row keyed by `pr_key`, which the feature page links to. We therefore leave the
+// `feature_runs` row in the terminal `converging` status (NOT an active status), so the
+// instanceTracking reconciler does not mark it `abandoned` when feature.bpmn completes.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { featureRuns } from "../../app/feature.ts";
+import { MAX_ROUNDS, parsePr, submitPr } from "../../app/service.ts";
+
+interface In extends Record<string, unknown> {
+  featureKey: string;
+  prKey?: unknown;
+  autoMerge?: unknown;
+}
+
+const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
+  const featureKey = job.variables.featureKey;
+  const prKey = typeof job.variables.prKey === "string" ? job.variables.prKey.trim() : "";
+  const autoMerge = job.variables.autoMerge === true;
+  const parsed = prKey ? parsePr(prKey) : null;
+  if (!parsed) {
+    // Should not happen — the gateway only routes here when record-feature emitted a parseable
+    // prKey — but never enroll a phantom PR. Leave the row `opened` and end.
+    app.log.warn("converge-feature: no parseable PR key, skipping hand-off", { featureKey, prKey });
+    await featureRuns(app.data).update(featureKey, { status: "opened", updated_at: new Date().toISOString() });
+    return {};
+  }
+  // `convergeOnly` is the inverse of auto-merge: converge-only stops at `converged`; auto-merge lets
+  // the merge-loop drive the merge. `submitPr` is idempotent on the PR key.
+  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, !autoMerge);
+  await featureRuns(app.data).update(featureKey, {
+    status: "converging",
+    pr_key: parsed.prKey,
+    updated_at: new Date().toISOString(),
+  });
+  app.log.info("converge-feature: enrolled PR into convergence loop", {
+    featureKey,
+    prKey: parsed.prKey,
+    convergeOnly: !autoMerge,
+  });
+  return {};
+};
+
+export default handler;

package/workers/ensure-base-branch/head-task.integration.test.ts

@@ -0,0 +1,126 @@
+// Integration coverage for the durable HEAD arm of ADR 0003 rule 2 — the `ensure-base-branch`
+// service task (taskType `pr.ensure-base-branch`). The unit tests in workers/ensure-base-branch/
+// worker.test.ts prove create/no-op in isolation; this file proves the END-TO-END belt-and-suspenders
+// property across a RE-PLAN: the head task CREATES a missing epic/* base off default HEAD on the first
+// pass, then NO-OPS on a second pass (idempotent — it neither errors nor resets the ref). Driven
+// through the real worker handler against a faked github transport — no network, deterministic.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { resetDefaultBranchCache } from "../../app/github.ts";
+import handler from "./worker.ts";
+
+interface GithubState {
+  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)
+}
+
+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));
+      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 } }));
+    }
+    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.set(branch, sha);
+      return Promise.resolve(json({ ref }, 201));
+    }
+    // A ref force-update (reset) would be a PATCH to .../git/refs/heads/<branch>. The idempotent head
+    // task must NEVER issue one; record it so the test can assert it stayed untouched.
+    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 }));
+    }
+    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;
+  }
+}
+
+const fakeApp = { log: { info() {}, warn() {}, error() {} } } as any;
+
+function runHead(state: GithubState, repo: string, baseBranch: string) {
+  return withGithub(state, () => handler({ variables: { repo, baseBranch } } as any, fakeApp)) as Promise<{
+    baseBranchResult: string;
+  }>;
+}
+
+test("head task: creates a missing epic/* base on first pass, then no-ops on re-plan (idempotent)", async () => {
+  const state: GithubState = {
+    repo: "owner/epic-repo",
+    defaultBranch: "main",
+    branches: new Map([["main", "mainhead"]]),
+    creates: [],
+    resets: [],
+  };
+
+  // First pass (fresh plan): the epic/* base is missing → created off default HEAD.
+  const first = await runHead(state, state.repo, "epic/gate");
+  assertEquals(first.baseBranchResult, "created");
+  assertEquals(state.creates, [{ ref: "refs/heads/epic/gate", sha: "mainhead" }]);
+  assertEquals(state.branches.get("epic/gate"), "mainhead");
+
+  // Second pass (re-plan / crash-recovery): the branch now exists → clean no-op. No further create,
+  // and — critically — no reset of the existing ref (a re-plan must not clobber landed work).
+  const second = await runHead(state, state.repo, "epic/gate");
+  assertEquals(second.baseBranchResult, "exists");
+  assertEquals(state.creates.length, 1); // still just the first create
+  assertEquals(state.resets, []); // never reset the ref
+  assertEquals(state.branches.get("epic/gate"), "mainhead"); // ref untouched
+});
+
+test("head task: a pre-existing base is a pure no-op (no create, no reset)", async () => {
+  const state: GithubState = {
+    repo: "owner/epic-repo2",
+    defaultBranch: "main",
+    branches: new Map([
+      ["main", "mainhead"],
+      ["epic/landed", "landedsha"],
+    ]),
+    creates: [],
+    resets: [],
+  };
+  const out = await runHead(state, state.repo, "epic/landed");
+  assertEquals(out.baseBranchResult, "exists");
+  assertEquals(state.creates, []);
+  assertEquals(state.resets, []);
+  assertEquals(state.branches.get("epic/landed"), "landedsha"); // untouched
+});

package/workers/ensure-base-branch/worker.test.ts

@@ -0,0 +1,104 @@
+// pr.ensure-base-branch worker — the durable, retriable head arm of ADR 0003 rule 2.
+//
+// It re-runs the idempotent `ensureBaseBranch` primitive on the durable path, so it must CREATE a
+// missing epic/* base off default HEAD and NO-OP when the branch already exists. Drive it through a
+// faked github transport (token mode + stubbed `globalThis.fetch`) so no network is touched.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import handler from "./worker.ts";
+
+interface FakeRepo {
+  repo: string;
+  defaultBranch: string;
+  branches: Map<string, string>; // branch name → head sha
+  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;
+    if (method === "GET" && path === `/repos/${state.repo}`) {
+      return Promise.resolve(jsonResponse({ 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));
+      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 } }));
+    }
+    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 prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "tok";
+  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;
+    if (prevTok === undefined) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = prevTok;
+  }
+}
+
+const fakeApp = { log: { info() {}, warn() {}, error() {} } } as any;
+
+async function run(state: FakeRepo, repo: string, baseBranch: string) {
+  return withGithub(state, () => handler({ variables: { repo, baseBranch } } as any, fakeApp)) as Promise<{
+    baseBranchResult: string;
+  }>;
+}
+
+test("ensure-base-branch worker: creates a missing epic/* base off default HEAD", async () => {
+  const state: FakeRepo = {
+    repo: "o/w-create",
+    defaultBranch: "main",
+    branches: new Map([["main", "defaulthead"]]),
+    creates: [],
+  };
+  const out = await run(state, state.repo, "epic/new");
+  assertEquals(out.baseBranchResult, "created");
+  assertEquals(state.creates, [{ ref: "refs/heads/epic/new", sha: "defaulthead" }]);
+});
+
+test("ensure-base-branch worker: no-ops when the branch already exists (idempotent re-plan)", async () => {
+  const state: FakeRepo = {
+    repo: "o/w-exists",
+    defaultBranch: "main",
+    branches: new Map([
+      ["main", "defaulthead"],
+      ["epic/already", "existingsha"],
+    ]),
+    creates: [],
+  };
+  const out = await run(state, state.repo, "epic/already");
+  assertEquals(out.baseBranchResult, "exists");
+  assertEquals(state.creates.length, 0);
+  // The existing ref must be left untouched.
+  assertEquals(state.branches.get("epic/already"), "existingsha");
+});

package/workers/ensure-base-branch/worker.ts

@@ -0,0 +1,31 @@
+// pr.ensure-base-branch — the durable, retriable head arm of ADR 0003 rule 2.
+//
+// `admitPlan` already ran `ensureBaseBranch` synchronously at admission (fail fast, so a missing
+// non-`epic/*` base is a clean edge 400 and a missing `epic/*` base is created before fan-out).
+// This head service task RE-RUNS the same idempotent primitive on the durable path — so a re-plan
+// or a crash between admission and fan-out still guarantees the base exists. Because
+// `ensureBaseBranch` never resets an existing ref, this is a clean no-op when the branch is already
+// there; a missing `epic/*` base is created off default HEAD, and a missing non-`epic/*` base
+// throws `BaseBranchMustExistError` (which fails the durable task rather than fanning out onto a
+// wrong-rooted branch).
+import type { AppJobHandler } from "@nanobpm/urban";
+import { type EnsureBaseBranchResult, ensureBaseBranch } from "../../app/github.ts";
+
+interface In extends Record<string, unknown> {
+  repo: string;
+  baseBranch: string;
+}
+interface Out extends Record<string, unknown> {
+  baseBranchResult: EnsureBaseBranchResult;
+}
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const repo = job.variables.repo;
+  const branch = job.variables.baseBranch;
+  const token = process.env.GITHUB_TOKEN ?? "";
+  const result = await ensureBaseBranch(repo, branch, token);
+  app.log.info("ensure-base-branch", { repo, branch, result });
+  return { baseBranchResult: result };
+};
+
+export default handler;

package/workers/finalize/worker.ts

@@ -101,8 +101,6 @@ const handler: AppJobHandler<In> = async (job, app) => {
     outcome: summary,
     converged_at: now,
     updated_at: now,
-    open_escalation_id: null,
-    open_escalation_question: null,
   });
 
   // Only the review-only terminal path ends the PR here as `converged` — in auto-merge mode the

package/workers/mark-merged/worker.ts

@@ -13,8 +13,6 @@ const handler: AppJobHandler<In> = async (job, app) => {
     status: "merged",
     merged_at: now,
     updated_at: now,
-    open_escalation_id: null,
-    open_escalation_question: null,
   });
 
   // If this PR was the last of its epic to land, kick off the retrospective. Best-effort: a

package/workers/merge/worker.ts

@@ -11,9 +11,9 @@
 import type { AppJobHandler } from "@nanobpm/urban";
 import { matchTags, tag } from "@nanobpm/urban/effect";
 import { abandonTokenFromUrl } from "../../app/abandon.ts";
-import { checkBaseTarget } from "../../app/baseGuard.ts";
+import { checkBaseTarget, classifyBaseGuard } from "../../app/baseGuard.ts";
 import { enqueueViaComment, fetchPrState, mergePr } from "../../app/github.ts";
-import { loadMergeProtocol } from "../../app/mergeProtocol.ts";
+import { classifyMergeLanding, DEFAULT_MERGE_PROTOCOL, loadMergeProtocol } from "../../app/mergeProtocol.ts";
 import { ensurePr, MERGE_ADMIN, MERGE_METHOD } from "../../app/service.ts";
 
 interface In extends Record<string, unknown> {
@@ -77,7 +77,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // base (typical in a stacked epic) stays the target and reads CLEAN, so nothing else catches it.
   // Best-effort: a transport hiccup leaves `deadEnd:false`, so this never blocks a valid merge.
   const guard = await checkBaseTarget(repo, prNumber, token).catch(() => null);
-  if (guard?.deadEnd) {
+  if (guard && classifyBaseGuard(guard) === "decision-required") {
     await app.data.table("merges", "id").insert({
       pr_key: prKey,
       outcome: "blocked",
@@ -112,8 +112,9 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     outcome = ok ? "queued" : "blocked";
     detail = ok ? `enqueued via "${comment}"` : `failed to post enqueue comment "${comment}"`;
     auditMethod = "queue-comment";
-  } else if (method === "ui") {
-    // The repo requires a human to click Merge; Merlin can't. Escalate rather than pretend.
+  } else if (classifyMergeLanding(protocol ?? DEFAULT_MERGE_PROTOCOL) === "decision-required") {
+    // The repo requires a human to click Merge (`land.method=ui`); Merlin can't. This is the
+    // only decision-required land method — escalate rather than pretend.
     outcome = "blocked";
     detail = "repo merge protocol requires a manual UI merge (land.method=ui)";
     auditMethod = "ui";