@nanobpm/nano-workforce 0.26.0

package/app/mergeProtocol.ts

@@ -0,0 +1,193 @@
+// Per-repo merge protocol (issue #43).
+//
+// Merlin's merge stage was repo-blind: it ran a plain `gh pr merge` and, on refusal, escalated to
+// a human. That breaks on any repo with a frugal-CI + on-demand-queue posture — e.g.
+// `Magikcraft/nano-bpm`, where auto-merge is OFF, CI runs only on `opened` (review-fix pushes do
+// NOT re-run it), and the documented way to land is: produce a fresh head run (`gh pr ready` /
+// close+reopen) → wait for it to go green → `@mergifyio queue`. See that repo's
+// `AGENTS.md → ## Merging PRs`.
+//
+// This module lets a target repo PUBLISH its landing protocol in a form Merlin can execute
+// deterministically. Discovery order (first hit wins):
+//   1. a fenced ```merge-protocol JSON block inside the repo's `AGENTS.md` (preferred — the human
+//      doc and the machine descriptor live together and can't drift), else
+//   2. `.github/merge-protocol.json`.
+// A repo that publishes neither keeps today's behaviour (DEFAULT_MERGE_PROTOCOL).
+
+import { fetchRepoFile } from "./github.ts";
+
+/** How to give branch protection a fresh head `pull_request` run before landing. `none` = the
+ * repo re-runs CI on every push, so no synthetic run is needed. `ready` = mark a draft ready
+ * (`gh pr ready`). `reopen` = close+reopen. `ready-or-reopen` = ready when the PR is a draft,
+ * otherwise reopen. */
+export type FreshHeadRun = "none" | "ready" | "reopen" | "ready-or-reopen";
+
+/** How to actually land the PR once its head checks are green. `gh-merge` = `gh pr merge`.
+ * `admin` = `gh pr merge --admin` (bypass required checks). `mergify-queue` = post the enqueue
+ * comment (`land.comment`, default `@mergifyio queue`) and wait for the queue to land it.
+ * `ui` = a human clicks Merge (Merlin can't do it → escalate). */
+export type LandMethod = "gh-merge" | "admin" | "mergify-queue" | "ui";
+
+export interface MergeProtocol {
+  /** Does the repo auto-merge a PR once its checks go green? (Informational; Merlin never relies
+   * on auto-merge — it lands deliberately.) */
+  autoMerge: boolean;
+  /** Whether/how to produce a fresh head CI run before landing. */
+  freshHeadRun: FreshHeadRun;
+  /** Wait for the head run to go green before landing (the poller does this anyway). */
+  waitForChecks: boolean;
+  /** How to land the PR. */
+  land: { method: LandMethod; comment?: string };
+  /** Names of the required checks (informational; the poller reads live state). */
+  requiredChecks: string[];
+  /** Pointer to the human doc, for escalation messages. */
+  doc?: string;
+}
+
+/** Absent-descriptor behaviour = exactly what Merlin did before #43: no synthetic head run, a
+ * direct `gh pr merge`. Opting in is purely additive. */
+export const DEFAULT_MERGE_PROTOCOL: MergeProtocol = {
+  autoMerge: true,
+  freshHeadRun: "none",
+  waitForChecks: false,
+  land: { method: "gh-merge" },
+  requiredChecks: [],
+};
+
+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"]);
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function str(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+function bool(v: unknown): boolean | undefined {
+  return typeof v === "boolean" ? v : undefined;
+}
+function strArray(v: unknown): string[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  return v.filter((x): x is string => typeof x === "string");
+}
+function oneOf<T extends string>(v: unknown, allowed: ReadonlySet<string>): T | undefined {
+  const s = str(v);
+  return s !== undefined && allowed.has(s) ? (s as T) : undefined;
+}
+
+/** Narrow arbitrary parsed JSON onto a MergeProtocol, defaulting every missing/invalid field.
+ * Never throws — an invalid descriptor degrades to the default rather than wedging the merge. */
+export function parseMergeProtocol(raw: unknown): MergeProtocol {
+  if (!isRecord(raw)) return { ...DEFAULT_MERGE_PROTOCOL };
+  const landRaw = isRecord(raw.land) ? raw.land : {};
+  const method = oneOf<LandMethod>(landRaw.method, LAND_METHODS) ?? DEFAULT_MERGE_PROTOCOL.land.method;
+  const comment = str(landRaw.comment);
+  return {
+    autoMerge: bool(raw.autoMerge) ?? DEFAULT_MERGE_PROTOCOL.autoMerge,
+    freshHeadRun: oneOf<FreshHeadRun>(raw.freshHeadRun, FRESH_HEAD_RUNS) ?? DEFAULT_MERGE_PROTOCOL.freshHeadRun,
+    waitForChecks: bool(raw.waitForChecks) ?? DEFAULT_MERGE_PROTOCOL.waitForChecks,
+    land: comment !== undefined ? { method, comment } : { method },
+    requiredChecks: strArray(raw.requiredChecks) ?? [],
+    doc: str(raw.doc),
+  };
+}
+
+/** Extract the JSON body of the first ```merge-protocol fenced block in a markdown document, or
+ * `null` if there is none. The info-string may carry a second word (```merge-protocol json). */
+export function extractProtocolBlock(markdown: string): string | null {
+  const m = markdown.match(/```merge-protocol(?:\s+\w+)?[ \t]*\r?\n([\s\S]*?)\r?\n```/);
+  return m ? m[1] : null;
+}
+
+/** Strip `//` line comments so a lightly-commented (JSONC-ish) descriptor still parses. Only
+ * whole-line comments are removed, to avoid mangling `//` inside a string value. */
+function stripLineComments(text: string): string {
+  return text
+    .split("\n")
+    .filter((l) => !/^\s*\/\//.test(l))
+    .join("\n");
+}
+
+function parseJsonLoose(text: string): unknown {
+  try {
+    return JSON.parse(stripLineComments(text));
+  } catch {
+    return undefined;
+  }
+}
+
+// The descriptor changes rarely; cache per repo so a busy merge poller doesn't re-fetch it every
+// pass. TTL keeps a mid-flight edit from being ignored for long.
+const CACHE_TTL_MS = 5 * 60_000;
+const cache = new Map<string, { at: number; protocol: MergeProtocol }>();
+
+/** Clear the in-memory descriptor cache (tests). */
+export function _clearMergeProtocolCache(): void {
+  cache.clear();
+}
+
+/** Load a repo's merge protocol (AGENTS.md block first, then `.github/merge-protocol.json`).
+ * Best-effort: any fetch/parse failure yields DEFAULT_MERGE_PROTOCOL, so a merge never wedges on
+ * a missing or malformed descriptor. Results are cached per repo for a few minutes. */
+export async function loadMergeProtocol(repo: string, token: string): Promise<MergeProtocol> {
+  const hit = cache.get(repo);
+  if (hit && Date.now() - hit.at < CACHE_TTL_MS) return hit.protocol;
+
+  let protocol = DEFAULT_MERGE_PROTOCOL;
+  try {
+    const agents = await fetchRepoFile(repo, "AGENTS.md", token).catch(() => null);
+    const block = agents ? extractProtocolBlock(agents) : null;
+    if (block !== null) {
+      protocol = parseMergeProtocol(parseJsonLoose(block));
+    } else {
+      const json = await fetchRepoFile(repo, ".github/merge-protocol.json", token).catch(() => null);
+      if (json !== null) protocol = parseMergeProtocol(parseJsonLoose(json));
+    }
+  } catch {
+    protocol = DEFAULT_MERGE_PROTOCOL;
+  }
+
+  cache.set(repo, { at: Date.now(), protocol });
+  return protocol;
+}
+
+export interface FreshHeadRunAttempt {
+  /** Current PR head commit. A rebase produces a new value, which starts a new landing attempt. */
+  headRefOid?: string | null;
+  /** Head commit for which this landing attempt already produced a synthetic run. */
+  lastActionHeadRefOid?: string | null;
+}
+
+/** Whether the merge poller should produce a synthetic fresh head run *now*, and how.
+ *
+ * Fires only when the protocol asks for a fresh run AND the PR currently has **no head check run
+ * at all** (`totalChecks === 0`) while GitHub still reports it un-landable-but-not-conflicting
+ * (`waiting`). That is exactly the frugal-CI stuck state: review converged, the last push produced
+ * no run, so branch protection's required checks read as *expected* forever. Once a run exists for
+ * the current head (`totalChecks > 0`, pending or done), or this same head already got its nudge,
+ * this returns `null`, so the poller never re-triggers inside one landing attempt. A rebase changes
+ * `headRefOid`, so the decision is re-derived and can fire again for the fresh post-rebase head.
+ * A genuinely-failing check (`blocked`) is left to the fix-ci arm, a conflict (`conflict`) to the
+ * rebase arm (#42). */
+export function freshHeadRunAction(
+  protocol: MergeProtocol,
+  verdict: "ready" | "waiting" | "conflict" | "blocked",
+  totalChecks: number,
+  isDraft: boolean,
+  attempt: FreshHeadRunAttempt = {},
+): "ready" | "reopen" | null {
+  if (protocol.freshHeadRun === "none") return null;
+  if (verdict !== "waiting") return null; // ready = go land; blocked/conflict = other arms
+  if (totalChecks !== 0) return null; // a run already exists (or unknown in token mode) → wait
+  if (attempt.headRefOid && attempt.headRefOid === attempt.lastActionHeadRefOid) return null;
+  switch (protocol.freshHeadRun) {
+    case "ready":
+      return isDraft ? "ready" : null;
+    case "reopen":
+      return "reopen";
+    case "ready-or-reopen":
+      return isDraft ? "ready" : "reopen";
+    default:
+      return null;
+  }
+}

package/app/mergeRebaseArm.test.ts

@@ -0,0 +1,72 @@
+// Structural regression guard for the merge-loop rebase remediation arm (issue #42).
+//
+// #42: the conflict arm routed a human's escalation answer straight back to `arm-merge`
+// (`f_m_answer → arm-merge`) with NO actor that rebases the branch, so a `CONFLICTING`
+// (moved-base) PR re-escalated forever — a human-in-the-loop livelock. The fix mirrors the
+// CI-fix arm: a `mergeState = "conflict"` verdict goes to a budgeted `senior:rebase` agent, and
+// escalates to a human only on the result gate.
+//
+// This test asserts the arm's topology on the committed model so it cannot regress silently the
+// way it originally shipped. It is a pure text assertion over the BPMN (no engine), matching the
+// repo's lightweight model-guard style.
+
+import { assert, assertStringIncludes } from "jsr:@std/assert@1";
+
+const bpmn = await Deno.readTextFile("resources/processes/merge-loop.bpmn");
+
+// Collapse whitespace so attribute-order / line-wrapping churn doesn't make the assertions brittle.
+const flat = bpmn.replace(/\s+/g, " ");
+
+// A `<sequenceFlow>` whose source/target match, regardless of attribute order or an inline
+// conditionExpression child. Returns true if such a flow is present.
+function hasFlow(source: string, target: string): boolean {
+  const re = new RegExp(
+    `<bpmn:sequenceFlow\\b[^>]*\\bsourceRef="${source}"[^>]*\\btargetRef="${target}"|` +
+      `<bpmn:sequenceFlow\\b[^>]*\\btargetRef="${target}"[^>]*\\bsourceRef="${source}"`,
+  );
+  return re.test(flat);
+}
+
+Deno.test("conflict routes to the rebase budget gate, not straight to a human", () => {
+  // The conflict verdict must reach the auto-rebase gate…
+  assert(hasFlow("gw-mergeable", "gw-rebase"), "gw-mergeable → gw-rebase (conflict) missing");
+  // …guarded by the exact conflict condition (DIRTY → mergeState = "conflict").
+  assertStringIncludes(flat, 'mergeState = "conflict"');
+});
+
+Deno.test("rebase arm mirrors the fix-ci arm: budget gate → agent → result gate", () => {
+  // Budget gate: within budget → the agent; exhausted → the (existing) conflict escalation.
+  assert(hasFlow("gw-rebase", "rebase"), "gw-rebase → rebase (within budget) missing");
+  assert(hasFlow("gw-rebase", "merge-esc-conflict"), "gw-rebase → merge-esc-conflict (budget exhausted) missing");
+  assertStringIncludes(flat, "rebaseRound &lt; rebaseMax");
+
+  // The agent is the senior:rebase fleet task, carrying its base prompt via the {{rebase}} header.
+  assertStringIncludes(flat, 'type="senior:rebase"');
+  assertStringIncludes(flat, 'value="{{rebase}}"');
+
+  // Agent → result gate; the round counter advances so the budget can actually be exhausted.
+  assert(hasFlow("rebase", "gw-rebase-result"), "rebase → gw-rebase-result missing");
+  assertStringIncludes(flat, "=rebaseRound + 1");
+});
+
+Deno.test("rebase result: success re-arms the poller; unresolved escalates to a human", () => {
+  // Success loops back to re-attempt the merge — forward progress, no human needed.
+  assert(hasFlow("gw-rebase-result", "arm-merge"), "gw-rebase-result → arm-merge (rebased) missing");
+  assertStringIncludes(flat, 'status = "rebased"');
+  // A genuine (semantic) conflict the agent can't resolve escalates to the human attempt path.
+  assert(
+    hasFlow("gw-rebase-result", "merge-esc-attempt"),
+    "gw-rebase-result → merge-esc-attempt (could not resolve) missing",
+  );
+});
+
+Deno.test("regression: the conflict verdict passes through the rebase actor, not straight to escalation", () => {
+  // The original #42 livelock had the conflict verdict escalate to a human with no remediation
+  // actor. The primary target of the conflict verdict must now be the rebase gate.
+  assert(
+    hasFlow("gw-mergeable", "gw-rebase"),
+    "conflict must reach the rebase gate (the #42 remediation actor)",
+  );
+  // Sanity: the untouched ready path still lands the merge directly.
+  assert(hasFlow("gw-mergeable", "attempt-merge"), "ready → attempt-merge path should still exist");
+});

package/app/mergeTrain.test.ts

@@ -0,0 +1,91 @@
+// Red/green regression for D6's pure merge-train lane planner.
+import { assertEquals } from "jsr:@std/assert@1";
+import { planLane, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
+
+const taskToPr = new Map([
+  ["gap-2", "o/r#2"],
+  ["gap-8", "o/r#8"],
+  ["gap-9", "o/r#9"],
+  ["gap-10", "o/r#10"],
+]);
+
+Deno.test("planLane: dependency depth then task id picks the single lane head", () => {
+  const depth = new Map([["gap-8", 2], ["gap-2", 0], ["gap-9", 0]]);
+  assertEquals(planLane(["gap-8", "gap-9", "gap-2"], taskToPr, new Set(), depth), {
+    headTaskId: "gap-2",
+    headPrKey: "o/r#2",
+    heldTaskIds: ["gap-9", "gap-8"],
+    heldPrKeys: ["o/r#9", "o/r#8"],
+  });
+});
+
+Deno.test("taskDependencyDepths: longest dependency path determines landing order depth", () => {
+  const depths = taskDependencyDepths([
+    { task_id: "b", depends_on_task_id: "a" },
+    { task_id: "c", depends_on_task_id: "b" },
+    { task_id: "d", depends_on_task_id: "a" },
+    { task_id: "e", depends_on_task_id: "c" },
+    { task_id: "e", depends_on_task_id: "d" },
+  ]);
+  assertEquals([depths.get("a"), depths.get("b"), depths.get("c"), depths.get("d"), depths.get("e")], [
+    0,
+    1,
+    2,
+    1,
+    3,
+  ]);
+});
+
+Deno.test("planLane: task id is the deterministic tiebreaker", () => {
+  assertEquals(planLane(["gap-9", "gap-2", "gap-8"], taskToPr, new Set()), {
+    headTaskId: "gap-2",
+    headPrKey: "o/r#2",
+    heldTaskIds: ["gap-8", "gap-9"],
+    heldPrKeys: ["o/r#8", "o/r#9"],
+  });
+});
+
+Deno.test("planLane: already-merged head advances to the next unmerged member", () => {
+  assertEquals(planLane(["gap-2", "gap-8", "gap-9"], taskToPr, new Set(["o/r#2"])), {
+    headTaskId: "gap-8",
+    headPrKey: "o/r#8",
+    heldTaskIds: ["gap-9"],
+    heldPrKeys: ["o/r#9"],
+  });
+});
+
+Deno.test("planLane: single-member lanes never hold their PR", () => {
+  assertEquals(planLane(["gap-10"], taskToPr, new Set()), {
+    headTaskId: null,
+    headPrKey: null,
+    heldTaskIds: [],
+    heldPrKeys: [],
+  });
+});
+
+Deno.test("planLane: tasks without PR keys do not block PR-backed members", () => {
+  assertEquals(planLane(["scaffold", "gap-2", "gap-8"], taskToPr, new Set()), {
+    headTaskId: "gap-2",
+    headPrKey: "o/r#2",
+    heldTaskIds: ["gap-8"],
+    heldPrKeys: ["o/r#8"],
+  });
+});
+
+Deno.test("planPrLane: held PRs point at the current lane head", () => {
+  assertEquals(
+    planPrLane([["gap-2", "gap-8"], ["gap-10"]], taskToPr, new Set(), "o/r#8"),
+    {
+      isHeld: true,
+      laneHeadOf: "o/r#2",
+      laneHeadTaskId: "gap-2",
+      laneTaskIds: ["gap-2", "gap-8"],
+    },
+  );
+});
+
+Deno.test("planPrLane: lane head and PRs outside exclusion lanes are not held", () => {
+  assertEquals(planPrLane([["gap-2", "gap-8"], ["gap-10"]], taskToPr, new Set(), "o/r#2").isHeld, false);
+  assertEquals(planPrLane([["gap-2", "gap-8"], ["gap-10"]], taskToPr, new Set(), "o/r#10").isHeld, false);
+  assertEquals(planPrLane([["gap-2", "gap-8"]], taskToPr, new Set(), "o/r#404").isHeld, false);
+});

package/app/mergeTrain.ts

@@ -0,0 +1,117 @@
+// nano-workforce — D6 merge-side lane serialization (issue #49).
+//
+// The D2 merge-exclusion graph groups tasks into landing lanes: tasks in the same lane can
+// implement concurrently but must merge serially. This pure planner chooses exactly one PR per
+// non-singleton lane to proceed now. Order is dependency depth first (a task that depends on another
+// lands later), then task id for stable tie-breaking; tasks with no PR key are ignored because there
+// is nothing to land.
+
+export interface LanePlan {
+  headTaskId: string | null;
+  headPrKey: string | null;
+  heldTaskIds: string[];
+  heldPrKeys: string[];
+}
+
+export interface PrLaneDecision {
+  isHeld: boolean;
+  laneHeadOf: string | null;
+  laneHeadTaskId: string | null;
+  laneTaskIds: string[];
+}
+
+export interface TaskDependencyEdge {
+  task_id: string;
+  depends_on_task_id: string;
+}
+
+/** Compute the same dependency depth used for lane order: roots at 0, dependants at
+ * `1 + max(dep depth)`. Cycles should already be rejected by plan review; if stale data contains
+ * one, break the recursive back-edge rather than wedging the poller. */
+export function taskDependencyDepths(edges: readonly TaskDependencyEdge[]): Map<string, number> {
+  const depsByTask = new Map<string, string[]>();
+  const ids = new Set<string>();
+  for (const e of edges) {
+    ids.add(e.task_id);
+    ids.add(e.depends_on_task_id);
+    const deps = depsByTask.get(e.task_id) ?? [];
+    deps.push(e.depends_on_task_id);
+    depsByTask.set(e.task_id, deps);
+  }
+  const depthOf = new Map<string, number>();
+  const visiting = new Set<string>();
+  const depth = (taskId: string): number => {
+    const cached = depthOf.get(taskId);
+    if (cached !== undefined) return cached;
+    if (visiting.has(taskId)) return 0;
+    visiting.add(taskId);
+    let d = 0;
+    for (const dep of depsByTask.get(taskId) ?? []) d = Math.max(d, depth(dep) + 1);
+    visiting.delete(taskId);
+    depthOf.set(taskId, d);
+    return d;
+  };
+  for (const id of ids) depth(id);
+  return depthOf;
+}
+
+const depthOf = (taskDepth: ReadonlyMap<string, number> | undefined, taskId: string) =>
+  taskDepth?.get(taskId) ?? 0;
+
+function compareTaskOrder(
+  a: string,
+  b: string,
+  taskDepth?: ReadonlyMap<string, number>,
+): number {
+  const da = depthOf(taskDepth, a);
+  const db = depthOf(taskDepth, b);
+  if (da !== db) return da - db;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Plan one serial landing lane. Singleton lanes never hold their sole PR; lanes with no unmerged
+ * PR-backed members have no head. */
+export function planLane(
+  laneTaskIds: readonly string[],
+  taskToPr: ReadonlyMap<string, string>,
+  mergedPrKeys: ReadonlySet<string>,
+  taskDepth?: ReadonlyMap<string, number>,
+): LanePlan {
+  if (laneTaskIds.length <= 1) {
+    return { headTaskId: null, headPrKey: null, heldTaskIds: [], heldPrKeys: [] };
+  }
+  const candidates = laneTaskIds
+    .filter((taskId) => {
+      const prKey = taskToPr.get(taskId);
+      return prKey && !mergedPrKeys.has(prKey);
+    })
+    .sort((a, b) => compareTaskOrder(a, b, taskDepth));
+  const headTaskId = candidates[0] ?? null;
+  const headPrKey = headTaskId ? taskToPr.get(headTaskId) ?? null : null;
+  const heldTaskIds = candidates.slice(1);
+  const heldPrKeys = heldTaskIds.map((taskId) => taskToPr.get(taskId)).filter((p): p is string => !!p);
+  return { headTaskId, headPrKey, heldTaskIds, heldPrKeys };
+}
+
+/** Decide whether a PR is currently held by its merge-exclusion lane. PRs outside a non-singleton
+ * exclusion lane are backward-compatible: they are never held. */
+export function planPrLane(
+  lanes: readonly (readonly string[])[],
+  taskToPr: ReadonlyMap<string, string>,
+  mergedPrKeys: ReadonlySet<string>,
+  prKey: string,
+  taskDepth?: ReadonlyMap<string, number>,
+): PrLaneDecision {
+  for (const lane of lanes) {
+    if (lane.length <= 1) continue;
+    if (!lane.some((taskId) => taskToPr.get(taskId) === prKey)) continue;
+    const plan = planLane(lane, taskToPr, mergedPrKeys, taskDepth);
+    return {
+      isHeld: plan.heldPrKeys.includes(prKey),
+      laneHeadOf: plan.headPrKey,
+      laneHeadTaskId: plan.headTaskId,
+      laneTaskIds: [...lane],
+    };
+  }
+  return { isHeld: false, laneHeadOf: null, laneHeadTaskId: null, laneTaskIds: [] };
+}

package/app/persist-escalation.test.ts

@@ -0,0 +1,119 @@
+// Red/green regression for pr.persist-escalation's round-recording (PR #32 review).
+//
+// The "review stalled" timer arm runs *after* `persist-round` has already inserted an
+// `addressed` row for this `round`. Re-inserting a `rounds` row there would record one round as
+// both `addressed` and `blocked`, making round history/UI ambiguous. The stalled arm therefore
+// passes `recordRound=false`, which must suppress the round insert while still opening the
+// escalation. The agent-raised / max-rounds arms omit the flag (no prior round row) and must
+// still record the round.
+import { assert, assertEquals } from "jsr:@std/assert@1";
+import handler from "../workers/persist-escalation/worker.ts";
+
+function fakeApp() {
+  const inserts: Record<string, unknown[]> = { rounds: [], escalations: [] };
+  const updates: Record<string, unknown[]> = { pull_requests: [] };
+  const app = {
+    data: {
+      table(name: string, _key: string) {
+        return {
+          // deno-lint-ignore require-await
+          async insert(row: unknown) {
+            (inserts[name] ??= []).push(row);
+            return name === "escalations" ? 42 : 1;
+          },
+          // deno-lint-ignore require-await
+          async update(key: string, patch: unknown) {
+            (updates[name] ??= []).push({ key, patch });
+          },
+        };
+      },
+    },
+  };
+  return { app, inserts, updates };
+}
+
+Deno.test("stalled arm (recordRound=false) does not insert a duplicate rounds row", async () => {
+  const { app, inserts } = fakeApp();
+  const job = {
+    variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "stalled", recordRound: false },
+  };
+  // deno-lint-ignore no-explicit-any
+  const out = await handler(job as any, app as any);
+  assertEquals(inserts.rounds.length, 0, "no round row when the round was already recorded");
+  assertEquals(inserts.escalations.length, 1, "escalation is still opened");
+  // deno-lint-ignore no-explicit-any
+  assertEquals((out as any).escalationId, 42);
+});
+
+Deno.test("escalation arm without the flag still records the round", async () => {
+  const { app, inserts } = fakeApp();
+  const job = { variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "max rounds" } };
+  // deno-lint-ignore no-explicit-any
+  await handler(job as any, app as any);
+  assertEquals(inserts.rounds.length, 1);
+  // deno-lint-ignore no-explicit-any
+  assertEquals((inserts.rounds[0] as any).round_no, 3);
+});
+
+// A blank question would have to be trimmed away, so a padded-but-non-blank question is stored
+// trimmed (matching the sibling `persist-task-escalation`) — no whitespace drift into the UI/DB.
+Deno.test("a padded question is persisted 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  " } };
+  // deno-lint-ignore no-explicit-any
+  await handler(job as any, app as any);
+  // deno-lint-ignore no-explicit-any
+  assertEquals((inserts.escalations[0] as any).question, "needs a decision", "escalation stores the trimmed question");
+  // deno-lint-ignore no-explicit-any
+  assertEquals((updates.pull_requests![0] as any).patch.open_escalation_question, "needs a decision", "denormalised question is trimmed too");
+});
+
+// A round that fell through the `gw-status` default (no `converged`/`addressed` status and no
+// question — the prompt-less-agent failure behind the empty "(no question provided)" escalations
+// on Magikcraft/nano-bpm #597/#599) must NOT throw (which parked an un-remediable JobNoRetries
+// incident). It now opens an *answerable* escalation with a fabricated, concrete question and the
+// agent's transcript attached, so a human can unblock the loop entirely from the UI.
+Deno.test("blank question fabricates an answerable escalation (no throw, no incident)", async () => {
+  for (const question of [undefined, "", "   "]) {
+    const { app, inserts, updates } = fakeApp();
+    const job = {
+      variables: {
+        prKey: "o/r#1",
+        round: 2,
+        ...(question === undefined ? {} : { question }),
+        "io.nanobpm.agentResult": { output: "the agent's prose review, no result file" },
+      },
+    };
+    // deno-lint-ignore no-explicit-any
+    const out = await handler(job as any, app as any);
+    // deno-lint-ignore no-explicit-any
+    assertEquals((out as any).escalationId, 42, "an escalation is opened, not refused");
+    assertEquals(inserts.escalations.length, 1, "escalation row written");
+    // deno-lint-ignore no-explicit-any
+    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");
+    // deno-lint-ignore no-explicit-any
+    const pr = updates.pull_requests![0] as any;
+    assertEquals(pr.patch.open_escalation_question, esc.question, "denormalised question set");
+  }
+});
+
+// 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.
+Deno.test("unclassified status without a question names the status in the fabricated question", async () => {
+  const { app, inserts } = fakeApp();
+  const job = { variables: { prKey: "o/r#1", round: 3, status: "in_progress" } };
+  // deno-lint-ignore no-explicit-any
+  await handler(job as any, app as any);
+  // deno-lint-ignore no-explicit-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");
+});

package/app/persist-round.test.ts

@@ -0,0 +1,65 @@
+// Red/green regression for pr.persist-round's round recording + parking behaviour.
+//
+// The convergence loop routes both `addressed` (the agent pushed changes) and the new `waiting`
+// (nothing to triage yet — round 1, awaiting the first review) statuses through gw-guard into
+// persist-round. Both must be recorded in `rounds` under their own status and both must park the
+// PR in `waiting_review` so the deterministic poller (app/service.ts) starts soliciting a review.
+// A `waiting` round is what replaced the old failure mode where an agent with nothing to do
+// re-requested the review destructively and escalated `blocked`.
+import { assertEquals } from "jsr:@std/assert@1";
+import handler from "../workers/persist-round/worker.ts";
+
+function fakeApp() {
+  const inserts: Record<string, unknown[]> = { rounds: [] };
+  const updates: Record<string, unknown[]> = { pull_requests: [] };
+  const app = {
+    data: {
+      table(name: string, _key: string) {
+        return {
+          // deno-lint-ignore require-await
+          async insert(row: unknown) {
+            (inserts[name] ??= []).push(row);
+            return 1;
+          },
+          // deno-lint-ignore require-await
+          async update(key: string, patch: unknown) {
+            (updates[name] ??= []).push({ key, patch });
+          },
+        };
+      },
+    },
+  };
+  return { app, inserts, updates };
+}
+
+for (const status of ["addressed", "waiting"]) {
+  Deno.test(`persist-round records a '${status}' round and parks the PR in waiting_review`, async () => {
+    const { app, inserts, updates } = fakeApp();
+    const job = { variables: { prKey: "o/r#1", round: 1, status, summary: `round was ${status}` } };
+    // deno-lint-ignore no-explicit-any
+    await handler(job as any, app as any);
+
+    assertEquals(inserts.rounds.length, 1, "the round is recorded");
+    // deno-lint-ignore no-explicit-any
+    const round = inserts.rounds[0] as any;
+    assertEquals(round.status, status, "the round carries the agent's status");
+    assertEquals(round.round_no, 1);
+
+    assertEquals(updates.pull_requests!.length, 1, "the PR is updated once");
+    // deno-lint-ignore no-explicit-any
+    const patch = (updates.pull_requests![0] as any).patch;
+    assertEquals(patch.status, "waiting_review", "the PR parks in waiting_review for the poller");
+    assertEquals(patch.current_round, 1);
+  });
+}
+
+// When the agent omits `status` (e.g. a fallback), persist-round defaults it to `addressed`
+// rather than writing a NULL status — the round history stays readable.
+Deno.test("persist-round defaults a missing status to 'addressed'", async () => {
+  const { app, inserts } = fakeApp();
+  const job = { variables: { prKey: "o/r#1", round: 2 } };
+  // deno-lint-ignore no-explicit-any
+  await handler(job as any, app as any);
+  // deno-lint-ignore no-explicit-any
+  assertEquals((inserts.rounds[0] as any).status, "addressed");
+});