@nanobpm/nano-workforce 0.56.0 → 0.58.0

package/app/github.ts

@@ -454,6 +454,12 @@ export async function fetchDefaultBranch(repo: string, token: string): Promise<s
   return name;
 }
 
+/** Test-only: drop the memoized default-branch entries so a suite can't leak a warmed cache
+ * (which ignores transport/token state on a hit) into a test that expects a cold lookup. */
+export function resetDefaultBranchCache(): void {
+  defaultBranchCache.clear();
+}
+
 /** Whether a branch has already *landed* — i.e. it is the head of a `MERGED` PR. Returns:
  *   • `landed`  — a merged PR exists from this branch → the branch is a dead-end target
  *   • `open`    — an open PR exists from it (still alive)
@@ -672,3 +678,129 @@ export async function enqueueViaComment(
   });
   return r.ok;
 }
+
+// ── Epic base-branch admission (ADR 0003, rule 2) ───────────────────────────
+// `ensureBaseBranch` is the create-if-missing primitive that guarantees an epic's integration
+// branch exists BEFORE any task fans out, with an `epic/*` guard so a typo can't silently spawn a
+// wrong-rooted branch. It is idempotent — an existing branch is a NO-OP (the ref is never reset,
+// which would nuke in-flight task PRs stacked on it) — so it is safe to call repeatedly: at
+// admission (fail fast), from the durable `ensure-base-branch` head task, and again on a re-plan.
+
+/** Thrown when a base branch that does NOT match the `epic/*` convention is missing. A
+ * non-`epic/*` base must already exist — a mistyped name is an operator error, not something to
+ * auto-create off the default branch (that would silently produce a wrong-rooted branch). */
+export class BaseBranchMustExistError extends Error {
+  readonly branch: string;
+  constructor(branch: string) {
+    super(
+      `base branch "${branch}" does not exist and is not an epic/* branch, so it will not be ` +
+        `auto-created — create it first, or use the epic/* convention for an auto-created ` +
+        `integration branch`,
+    );
+    this.name = "BaseBranchMustExistError";
+    this.branch = branch;
+  }
+}
+
+/** Whether `branch` matches the auto-creatable `epic/*` convention (migration 019). */
+function isEpicBranch(branch: string): boolean {
+  return branch.startsWith("epic/");
+}
+
+/** Resolve the head commit SHA of `branch` on `repo`, or `null` when the branch does not exist
+ * (a 404 from the git-ref endpoint). Throws only on a genuine transport failure. */
+async function branchHeadSha(repo: string, branch: string, token: string): Promise<string | null> {
+  const apiPath = `repos/${repo}/git/ref/heads/${branch}`;
+  if (await useGh()) {
+    try {
+      const out = await runGh(["api", apiPath]);
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      const j = JSON.parse(out) as { object?: { sha?: string } };
+      return j.object?.sha ?? null;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/\b404\b|not found|no such/i.test(msg)) return null;
+      throw err;
+    }
+  }
+  if (!token) throw new Error(`no GitHub transport available to read ${apiPath}`);
+  const r = await fetch(`https://api.github.com/${apiPath}`, {
+    headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+  });
+  if (r.status === 404) return null;
+  if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
+  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+  const j = (await r.json()) as { object?: { sha?: string } };
+  return j.object?.sha ?? null;
+}
+
+/** Create `refs/heads/<branch>` pointing at `sha`. Idempotent: a concurrent create / re-plan
+ * that already made the ref (GitHub `422 Reference already exists`) is treated as a no-op.
+ * Returns `true` when this call actually created the ref, `false` when it lost the race and the
+ * ref already existed (the 422 case) — so the caller can report an honest exists/created outcome. */
+async function createBranchRef(
+  repo: string,
+  branch: string,
+  sha: string,
+  token: string,
+): Promise<boolean> {
+  const ref = `refs/heads/${branch}`;
+  if (await useGh()) {
+    try {
+      await runGh(["api", `repos/${repo}/git/refs`, "-X", "POST", "-f", `ref=${ref}`, "-f", `sha=${sha}`]);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/\b422\b|already exists/i.test(msg)) return false; // idempotent — someone else created it
+      throw err;
+    }
+    return true;
+  }
+  if (!token) throw new Error(`no GitHub transport available to create ${ref}`);
+  const r = await fetch(`https://api.github.com/repos/${repo}/git/refs`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      accept: "application/vnd.github+json",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ ref, sha }),
+  });
+  if (r.ok) return true;
+  if (r.status === 422) return false; // reference already exists — idempotent
+  throw new Error(`github ${r.status} ${r.statusText}: ${(await r.text()).slice(0, 300)}`.trim());
+}
+
+/** The outcome of `ensureBaseBranch`: the branch was already present (`exists`, a no-op) or was
+ * just created off the default branch HEAD (`created`). */
+export type EnsureBaseBranchResult = "exists" | "created";
+
+/** Guarantee the epic base `branch` exists on `repo` (ADR 0003 rule 2), idempotently:
+ *   • already exists → `"exists"` — NO-OP; the ref is never moved/reset.
+ *   • missing and matches `epic/*` → create `refs/heads/<branch>` off the default branch HEAD,
+ *     return `"created"`.
+ *   • missing and not `epic/*` → throw `BaseBranchMustExistError` (a non-`epic/*` base must
+ *     pre-exist; a typo must fail fast, not silently spawn a wrong-rooted branch).
+ * Safe to call repeatedly (at admission AND as the durable head task, and on a re-plan). */
+export async function ensureBaseBranch(
+  repo: string,
+  branch: string,
+  token: string,
+): Promise<EnsureBaseBranchResult> {
+  const existing = await branchHeadSha(repo, branch, token);
+  if (existing !== null) return "exists"; // never reset an existing ref
+
+  if (!isEpicBranch(branch)) throw new BaseBranchMustExistError(branch);
+
+  const defaultBranch = await fetchDefaultBranch(repo, token);
+  if (!defaultBranch) {
+    throw new Error(`cannot resolve the default branch of ${repo} to create ${branch}`);
+  }
+  const defaultSha = await branchHeadSha(repo, defaultBranch, token);
+  if (!defaultSha) {
+    throw new Error(`cannot resolve HEAD of default branch ${defaultBranch} on ${repo} to create ${branch}`);
+  }
+  // A concurrent create / re-plan may have raced us to the ref (GitHub 422); in that case it
+  // already exists and we did not create it, so report "exists" rather than misleading "created".
+  const created = await createBranchRef(repo, branch, defaultSha, token);
+  return created ? "created" : "exists";
+}

package/app/mergeProtocol.test.ts

@@ -7,6 +7,7 @@
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import {
+  classifyMergeLanding,
   DEFAULT_MERGE_PROTOCOL,
   extractProtocolBlock,
   freshHeadRunAction,
@@ -195,3 +196,17 @@ test("headRunPresenceCount: token mode (totalChecks < 0) stays conservative (-1)
   assertEquals(headRunPresenceCount(NANO_REQ, { totalChecks: -1, presentCheckNames: [] }), -1);
   assertEquals(freshHeadRunAction(NANO_REQ, "waiting", -1, false), null);
 });
+
+// The land method is classified against the canonical escalation taxonomy: only a `ui` method is a
+// decision-required escalation (a human must click Merge); every machine-landable method is
+// transient (the merge stage lands it in-process).
+test("classifyMergeLanding: only `ui` is decision-required", () => {
+  const withMethod = (method: MergeProtocol["land"]["method"]): MergeProtocol => ({
+    ...DEFAULT_MERGE_PROTOCOL,
+    land: { method },
+  });
+  assertEquals(classifyMergeLanding(withMethod("ui")), "decision-required");
+  assertEquals(classifyMergeLanding(withMethod("gh-merge")), "transient");
+  assertEquals(classifyMergeLanding(withMethod("admin")), "transient");
+  assertEquals(classifyMergeLanding(withMethod("mergify-queue")), "transient");
+});

package/app/mergeProtocol.ts

@@ -14,6 +14,7 @@
 //   2. `.github/merge-protocol.json`.
 // A repo that publishes neither keeps today's behaviour (DEFAULT_MERGE_PROTOCOL).
 
+import { classifyEscalation, type EscalationDisposition } from "./escalationTaxonomy.ts";
 import { fetchRepoFile } from "./github.ts";
 
 /** How to give branch protection a fresh head `pull_request` run before landing. `none` = the
@@ -66,6 +67,15 @@ export const DEFAULT_MERGE_PROTOCOL: MergeProtocol = {
   requiredChecks: [],
 };
 
+/** Classify a repo's landing method against the canonical escalation taxonomy. A `ui` land
+ * method is a `decision-required` escalation (only a human can click Merge); every
+ * machine-landable method (gh-merge / admin / mergify-queue) is `transient` — the merge stage
+ * lands it in-process without paging a human. Delegates to {@link classifyEscalation} so the
+ * merge worker shares one source of truth with every other raise site. */
+export function classifyMergeLanding(protocol: MergeProtocol): EscalationDisposition {
+  return classifyEscalation({ kind: "merge-protocol", landMethod: protocol.land.method });
+}
+
 const FRESH_HEAD_RUNS: ReadonlySet<string> = new Set(["none", "ready", "reopen", "ready-or-reopen"]);
 const LAND_METHODS: ReadonlySet<string> = new Set(["gh-merge", "admin", "mergify-queue", "ui"]);
 

package/app/persist-escalation.test.ts

@@ -7,7 +7,7 @@
 // escalation. The agent-raised / max-rounds arms omit the flag (no prior round row) and must
 // still record the round.
 import { test } from "node:test";
-import { assert, assertEquals } from "#test-assert";
+import { assertEquals } from "#test-assert";
 import handler from "../workers/persist-escalation/worker.ts";
 
 function fakeApp() {
@@ -99,62 +99,60 @@ test("persist-escalation heals a missing pull_requests parent before recording",
 });
 
 
-test("a padded question is persisted trimmed (no whitespace drift)", async () => {
+test("a padded question is persisted trimmed and returned trimmed (no whitespace drift)", async () => {
   const { app, inserts, updates } = fakeApp();
   const job = { variables: { prKey: "o/r#1", round: 4, status: "needs_input", question: "  needs a decision  " } };
-  await handler(job as any, app as any);
+  const out = await handler(job as any, app as any);
   assertEquals((inserts.escalations[0] as any).question, "needs a decision", "escalation stores the trimmed question");
-  assertEquals((updates.pull_requests![0] as any).patch.open_escalation_question, "needs a decision", "denormalised question is trimmed too");
+  // The trimmed question is returned as a process variable so the downstream `wait-answer`
+  // userTask + `pr-escalation.form` can display it (there is no denormalised PR-row pointer).
+  assertEquals((out as any).question, "needs a decision", "the returned question is trimmed too");
+  const patch = (updates.pull_requests![0] as any).patch;
+  assertEquals(patch.open_escalation_question, undefined, "no denormalised question pointer is written");
+  assertEquals(patch.open_escalation_id, undefined, "no denormalised id pointer is written");
 });
 
-// Defence-in-depth for the persist-escalation worker: if the gateway ever DOES route a
-// blank-status / blank-question job here (an agent-raised `needs_input`/`blocked` with no
-// question, or the max-rounds / review-stalled arms), the worker must NOT throw — throwing
-// parked an un-remediable JobNoRetries incident (the empty "(no question provided)" escalations
-// on Magikcraft/nano-bpm #597/#599). It opens an *answerable* escalation with a fabricated,
-// concrete question and the agent's transcript attached, so a human can unblock the loop from
-// the UI.
+// REGRESSION (nano-workforce ADR 0002 §1 — retire the blank-question fabrication failure mode).
 //
-// NOTE: the `gw-status` gateway no longer routes an empty/unknown status here — that now
-// defaults to `f_addressed` and re-enters the review wait (see roundResultDefault.test.ts).
-// This fabrication path stays as a worker-level backstop for the explicit escalation arms.
-test("blank question fabricates an answerable escalation (no throw, no incident)", async () => {
+// A blank/absent question must be treated as a NON-escalation: no escalation row, no PR status
+// flip to `escalated`, no wait. The worker previously FABRICATED a concrete question from the
+// transcript and opened an answerable escalation — that is exactly the failure mode this slice
+// retires. This test reproduces that defect (it fails against the old fabricating worker, which
+// opened an escalation with `escalationId:42`) and pins the new non-escalation behaviour.
+//
+// The `gw-status` gateway is the primary guard (its `f_escalate` arm now requires a non-blank
+// question — see roundResultDefault.test.ts), so a blank-question round never reaches this worker
+// in practice; this asserts the worker's defence-in-depth via the canonical taxonomy.
+test("blank question is a non-escalation (no row fabricated, no status flip)", async () => {
   for (const question of [undefined, "", "   "]) {
     const { app, inserts, updates } = fakeApp();
     const job = {
       variables: {
         prKey: "o/r#1",
         round: 2,
+        status: "needs_input",
         ...(question === undefined ? {} : { question }),
         "io.nanobpm.agentResult": { output: "the agent's prose review, no result file" },
       },
     };
     const out = await handler(job as any, app as any);
-    assertEquals((out as any).escalationId, 42, "an escalation is opened, not refused");
-    assertEquals(inserts.escalations.length, 1, "escalation row written");
-    const esc = inserts.escalations[0] as any;
-    assert(esc.question.trim().length > 0, "fabricated question is concrete/non-blank");
-    assert(
-      esc.question.includes("machine-readable result"),
-      "no-result rounds explain the missing status",
-    );
-    assertEquals(esc.transcript, "the agent's prose review, no result file", "transcript attached");
-    // Default status for an unclassified escalation is a question needing input.
-    assertEquals(esc.kind, "question");
-    const pr = updates.pull_requests![0] as any;
-    assertEquals(pr.patch.open_escalation_question, esc.question, "denormalised question set");
+    assertEquals((out as any).escalated, false, "the job reports no escalation");
+    assertEquals((out as any).escalationId, null, "no escalation id is minted");
+    assertEquals(inserts.escalations.length, 0, "no escalation row is fabricated");
+    assertEquals(inserts.rounds.length, 0, "no round row is written for a non-escalation");
+    assertEquals(updates.pull_requests?.length ?? 0, 0, "the PR is never flipped to escalated");
   }
 });
 
-// When a non-empty-but-unclassified status arrives with no question, the fabricated question
-// names the status so the human sees what the agent reported.
-test("unclassified status without a question names the status in the fabricated question", async () => {
-  const { app, inserts } = fakeApp();
+// A non-human-blocking status (never routed here by `gw-status`, but defensively handled) is a
+// transient signal, not a decision-required escalation: it opens nothing.
+test("a non-decision status is a non-escalation even with no question", async () => {
+  const { app, inserts, updates } = fakeApp();
   const job = { variables: { prKey: "o/r#1", round: 3, status: "in_progress" } };
-  await handler(job as any, app as any);
-  const esc = inserts.escalations[0] as any;
-  assert(esc.question.includes("in_progress"), "fabricated question references the raw status");
-  assertEquals(esc.kind, "blocker", "a non needs_input status is a blocker escalation");
+  const out = await handler(job as any, app as any);
+  assertEquals((out as any).escalated, false);
+  assertEquals(inserts.escalations.length, 0, "no escalation is opened for a transient status");
+  assertEquals(updates.pull_requests?.length ?? 0, 0, "the PR is not flipped to escalated");
 });
 
 // When repo/prNumber process variables are absent the heal still runs by parsing the canonical