@nanobpm/nano-workforce 0.187.3 → 0.187.5

package/test/derivation-parity/README.md

@@ -72,7 +72,7 @@ sufficient_. Three golden features have no structured-builder derivation, each
 pinned by a diagnostic in `derivation-parity.test.ts`:
 
 1. **Task-level back-edge merge.** The loop head `review-round` is a
-   `serviceTask` that merges **three** back-edges directly (`in=3`). But `loop()`
+   `serviceTask` that merges **four** back-edges directly (`in=4`). But `loop()`
    always inserts an exclusive-gateway loop head that absorbs the back-edge, so
    the body task stays `in=1` — empirically demonstrated by the `loop() inserts a
    gateway head` test.
@@ -81,8 +81,8 @@ pinned by a diagnostic in `derivation-parity.test.ts`:
    complex boolean, one default). No `switch` (equalities + default) or `branch`
    (one condition + default) emits that.
 3. **Shared merge+split gateway.** `gw-escalated` is a single exclusive gateway
-   that is at once a **five-way merge and a two-way split**, reached by back-edges
-   from five distinct points.
+   that is at once a **six-way merge and a two-way split**, reached by back-edges
+   from six distinct points.
 
 The fix is an **arbitrary-graph / explicit-join (named-target)** builder upstream
 in `@nanobpm/workflow` — a **superset** of the class-1 gap.

package/test/derivation-parity/derivation-parity.test.ts

@@ -125,8 +125,14 @@ test("convergence-loop golden has arbitrary-graph features the structured builde
     const body = rest.slice(0, close);
     return (body.match(new RegExp(`<bpmn:${tag}\\b`, "g")) ?? []).length;
   };
-  // (a) the loop head is a serviceTask that MERGES three back-edges directly.
-  assertEquals(between("review-round", "serviceTask", "incoming"), 3, "review-round should merge 3 flows on the task itself");
+  // (a) the loop head is a serviceTask that MERGES four back-edges directly — after #786/#789 the
+  // round-entry head capture (`capture-head`) is the loop head sitting BEFORE `review-round`, so it
+  // is `capture-head` that absorbs the four back-edges (the review loop, the answer resume, the
+  // escalation re-enter, and the #786 husk auto-retry); `review-round` then takes its single
+  // `f_capture` in-edge. A serviceTask merging four back-edges directly is the arbitrary-graph shape
+  // the structured builder cannot emit — the feature this asserts, now on `capture-head`.
+  assertEquals(between("capture-head", "serviceTask", "incoming"), 4, "capture-head should merge 4 flows on the task itself");
+  assertEquals(between("review-round", "serviceTask", "incoming"), 1, "review-round now takes the single f_capture in-edge");
   // (b) a single exclusive gateway forks FOUR heterogeneous-condition out-edges.
   assertEquals(between("gw-status", "exclusiveGateway", "outgoing"), 4, "gw-status should be a 4-way exclusive gateway");
   // (c) a single exclusive gateway is at once a 6-way merge and a 2-way split.
@@ -138,7 +144,7 @@ test("convergence-loop golden has arbitrary-graph features the structured builde
 // (a): a `loop()` whose body starts with a task derives an exclusive-gateway
 // loop head that absorbs the back-edge (in>=2), leaving the task itself at
 // in=1. The golden instead merges its back-edges directly into `review-round`
-// (in=3) with no loop-head gateway — a shape the builder cannot express.
+// (in=4) with no loop-head gateway — a shape the builder cannot express.
 test("loop() inserts a gateway head, so back-edges cannot merge into a task", () => {
   const probe = defineFlow("loop-head-probe", (w) => {
     w.loop((b) => {

package/test/derivation-parity/flows.ts

@@ -24,12 +24,12 @@
 //         so it clears class (1) — but its topology is NOT expressible with the
 //         structured-only builder (`loop`/`switch`/`branch`), empirically proven
 //         (see `derivation-parity.test.ts`): its loop head `review-round` is a
-//         serviceTask that MERGES three back-edges directly (in=3), whereas
+//         serviceTask that MERGES four back-edges directly (in=4), whereas
 //         `loop()` always inserts an exclusive-gateway loop head (the task stays
 //         in=1); `gw-status` is a single exclusive gateway with FOUR
 //         heterogeneous-condition out-edges (two `=x = "v"`, one complex boolean,
 //         one default) which no `switch`/`branch` emits; and `gw-escalated` is a
-//         single gateway that is simultaneously a five-way merge and a two-way
+//         single gateway that is simultaneously a six-way merge and a two-way
 //         split. Single start/end is necessary but NOT sufficient. Needs an
 //         arbitrary-graph / explicit-join (named-target) builder — a SUPERSET of
 //         the class-(1) gap.
@@ -207,8 +207,8 @@ export const PORTS: readonly PortEntry[] = [
       "blocked (arbitrary control-flow graph): single top-level start/end, but " +
       "its topology is not expressible with the published @nanobpm/workflow's " +
       "structured-only builder (loop/switch/branch). Proven in the test suite: " +
-      "the loop head `review-round` is a serviceTask that merges 3 back-edges " +
-      "directly (in=3), but loop() always inserts an exclusive-gateway head " +
+      "the loop head `review-round` is a serviceTask that merges 4 back-edges " +
+      "directly (in=4), but loop() always inserts an exclusive-gateway head " +
       "(task stays in=1); `gw-status` is one gateway with 4 heterogeneous-" +
       "condition out-edges (no switch/branch emits that); `gw-escalated` is one " +
       "gateway that is at once a 6-way merge and a 2-way split. Awaits an " +

package/workers/capture-head/worker.test.ts

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { makeHandler } from "./worker.ts";
+
+const assertEquals = (a: unknown, b: unknown, m?: string) => assert.deepStrictEqual(a, b, m);
+
+// The worker reads only `job.variables`, so a bare stub job suffices.
+const job = (variables: Record<string, unknown>) => ({ variables }) as never;
+
+test("capture-head: reads the head via the carried repo/prNumber and publishes it as roundEntryHead", async () => {
+  let seen: [string, number] | null = null;
+  const handler = makeHandler({
+    readHead: async (repo, n) => {
+      seen = [repo, n];
+      return "sha-abc";
+    },
+  });
+  const out = await handler(job({ prKey: "o/r#1", repo: "o/r", prNumber: 1 }), {} as never);
+  assertEquals(out, { roundEntryHead: "sha-abc" });
+  assertEquals(seen, ["o/r", 1], "the carried repo/prNumber drive the head read");
+});
+
+test("capture-head: falls back to parsing the prKey when repo/prNumber are absent", async () => {
+  let seen: [string, number] | null = null;
+  const handler = makeHandler({
+    readHead: async (repo, n) => {
+      seen = [repo, n];
+      return "sha-def";
+    },
+  });
+  const out = await handler(job({ prKey: "owner/repo#42" }), {} as never);
+  assertEquals(out, { roundEntryHead: "sha-def" });
+  assertEquals(seen, ["owner/repo", 42], "repo/prNumber resolved from the canonical prKey");
+});
+
+test("capture-head: an unreadable head fails OPEN to the empty-string sentinel (never a fabricated baseline)", async () => {
+  // A transient GitHub hiccup must never publish a wrong baseline. The empty string is the "unknown"
+  // sentinel progress-check treats as no round-entry baseline (→ it falls back to last_round_head).
+  const handler = makeHandler({ readHead: async () => null });
+  const out = await handler(job({ prKey: "o/r#1", repo: "o/r", prNumber: 1 }), {} as never);
+  assertEquals(out, { roundEntryHead: "" });
+});
+
+test("capture-head: a THROWING head read is swallowed to the empty-string sentinel", async () => {
+  const handler = makeHandler({
+    readHead: async () => {
+      throw new Error("network down");
+    },
+  });
+  const out = await handler(job({ prKey: "o/r#1", repo: "o/r", prNumber: 1 }), {} as never);
+  assertEquals(out, { roundEntryHead: "" });
+});
+
+test("capture-head: an unresolvable target (unparseable prKey, no repo/prNumber) publishes the empty sentinel without calling the reader", async () => {
+  let called = false;
+  const handler = makeHandler({
+    readHead: async () => {
+      called = true;
+      return "sha-x";
+    },
+  });
+  const out = await handler(job({ prKey: "not-a-pr-key" }), {} as never);
+  assertEquals(out, { roundEntryHead: "" });
+  assertEquals(called, false, "no target ⇒ the head reader is never invoked");
+});
+
+test("capture-head: always publishes roundEntryHead so a husk retry / new round OVERWRITES a prior entry SHA", async () => {
+  // The field is returned on every invocation (string or ""), so a re-entry never carries a stale
+  // captured head forward — the value is re-derived from the live head each round entry.
+  const heads = ["sha-1", "sha-2"];
+  let i = 0;
+  const handler = makeHandler({ readHead: async () => heads[i++] ?? null });
+  const first = await handler(job({ prKey: "o/r#1", repo: "o/r", prNumber: 1 }), {} as never);
+  const second = await handler(job({ prKey: "o/r#1", repo: "o/r", prNumber: 1 }), {} as never);
+  assertEquals(first, { roundEntryHead: "sha-1" });
+  assertEquals(second, { roundEntryHead: "sha-2" }, "the re-entry overwrites with a freshly-read head");
+});

package/workers/capture-head/worker.ts

@@ -0,0 +1,64 @@
+// pr.capture-head — captures the PR's head SHA at the START of a convergence round, BEFORE the
+// `review-round` agent runs.
+//
+// Every entry into `review-round` (the first round from Start, a review-loop re-enter, a human-answer
+// resume, and a husk auto-retry) now routes through this step first. It reads the head as it stands
+// immediately before the agent acts and publishes it as the `roundEntryHead` process variable, which
+// `pr.progress-check` (workers/progress-check/worker.ts) then reads as the round's baseline.
+//
+// WHY this exists (issue #786 / Copilot #789 — closing both sides of the no-baseline husk problem):
+// progress-check classifies a no-advance `addressed` round by diffing the head against a baseline. It
+// previously used the PREVIOUS round's recorded head (`last_round_head`), which is null on the FIRST
+// addressed round (a fresh submission clears it), leaving two opposing failure modes:
+//   • fail-open on no baseline → a first-round HUSK is waved through as progress (bypasses gw-husk);
+//   • special-case husk on no baseline → a real commit an agent pushed just before dying non-terminal
+//     is mis-routed into gw-husk.
+// Capturing the entry head structurally eliminates the no-baseline case: a real push advances the head
+// WITHIN the round (→ progress, never a false husk), and a husk that pushed nothing leaves the head at
+// the captured entry (→ a genuine no-advance the agent-instance corroboration splits into husk vs.
+// no-advance). The special no-baseline branch is gone.
+//
+// `roundEntryHead` is an INSTANCE-SCOPED process variable, not a persisted column, so a straggler from
+// a superseded convergence instance can never contaminate a re-opened run's baseline. It is captured
+// fresh on every round entry (including husk retries), so it never carries a stale prior-round value.
+// The read fails OPEN to `null` (a transient GitHub hiccup must never fabricate a no-progress verdict);
+// progress-check then falls back to the persisted `last_round_head`.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { fetchBranchHead, fetchPrHead } from "../../app/github.ts";
+import { parsePr } from "../../app/service.ts";
+import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io.d.ts";
+import { type HeadReader, makeDefaultReadHead } from "../progress-check/worker.ts";
+
+// Input/output typed off the model data envelopes (`PrCaptureHeadIn` / `PrCaptureHeadOut` in
+// convergence-loop.bpmn), the single source of truth for this worker's wire contract (ADR 0040).
+type In = WorkerInputs["pr.capture-head"];
+type Out = WorkerOutputs["pr.capture-head"];
+
+const defaultReadHead: HeadReader = makeDefaultReadHead({ fetchPrHead, fetchBranchHead });
+
+/** Injectable head reader so unit tests never touch git/network; the default binds the same
+ * branch-ref-over-stale-`head.sha` reader progress-check uses (#786), keeping the entry-head and the
+ * exit-head reads byte-for-byte comparable. */
+export function makeHandler(deps: { readHead: HeadReader }): AppJobHandler<In, Out> {
+  return async (job) => {
+    const { prKey, repo, prNumber } = job.variables;
+    // Prefer the carried repo/prNumber; fall back to parsing the canonical `owner/repo#N` prKey so an
+    // older in-flight instance still resolves a target. If neither yields one, publish a null baseline
+    // — progress-check then falls back to `last_round_head` and, absent that, fails open.
+    const parsed = parsePr(prKey);
+    const ghRepo = repo ?? parsed?.repo;
+    const ghNumber = typeof prNumber === "number" ? prNumber : parsed?.number;
+    if (!ghRepo || typeof ghNumber !== "number") {
+      return { roundEntryHead: "" };
+    }
+    // ALWAYS publish the variable so a husk retry / new round OVERWRITES any prior round's captured
+    // head — it must never carry a stale entry SHA forward. An unreadable head yields the empty
+    // string (the "unknown" sentinel), which progress-check treats as no round-entry baseline and
+    // falls back to the persisted `last_round_head`; a non-empty string is the fresh entry baseline.
+    const roundEntryHead = (await deps.readHead(ghRepo, ghNumber).catch(() => null)) ?? "";
+    return { roundEntryHead };
+  };
+}
+
+const handler = makeHandler({ readHead: defaultReadHead });
+export default handler;

package/workers/persist-escalation/worker.ts

@@ -105,6 +105,10 @@ const handler: AppJobHandler<In> = async (job, app) => {
       worker,
       started_at: now,
       ended_at: now,
+      // Stamp the writing run's identity (issue #786) so the round-record row carries the same
+      // run-identity column pr.persist-round scopes its idempotent upsert by. A pr.persist-round
+      // resume for this same numeric round then reuses ONLY its own row, never this escalation row.
+      process_instance_key: job.processInstanceKey != null ? String(job.processInstanceKey) : null,
     });
   }
   const escalationId = await app.data.table("escalations", "id").insert({

package/workers/persist-round/worker.ts

@@ -1,6 +1,10 @@
 // pr.persist-round — records a completed round (an `addressed` round where the agent pushed
-// changes, or a `waiting` round where there was nothing to triage yet) and parks the PR in
-// `waiting_review` so the poller starts watching for / soliciting the next review.
+// changes, or a `waiting` round where there was nothing to triage yet) and advances the PR's
+// `current_round`. It does NOT park the PR in `waiting_review`: that transition is owned by the
+// downstream pr.progress-check step, the single writer of the post-round wait status. persist-round
+// runs BEFORE the husk decision, so parking here would momentarily expose a husk-retry round (which
+// re-enters review-round WITHOUT waiting for a review) to the poller's `waiting_review` scan and let
+// it solicit a spurious Copilot review before progress-check flips the row back (#786).
 //
 // Data access goes through the injected app datasource gateway (`app.data.table<T>`), the RAD
 // `Table<T>` surface — `rounds.insert(...)` / `pull_requests.update(...)`, not hand-written SQL.
@@ -107,20 +111,82 @@ const handler: AppJobHandler<In> = async (job, app) => {
     });
   }
 
-  await app.data.table("rounds", "id").insert({
-    pr_key: prKey,
-    round_no: round,
+  // Idempotent round record (issue #786): a husk auto-retry re-enters `review-round` WITHOUT
+  // advancing the round counter, so the SAME `(pr_key, round_no)` reaches this worker more than once.
+  // The `rounds` table has no UNIQUE(pr_key, round_no), so an unconditional insert would manufacture
+  // a DUPLICATE history row per retry — the durable round history is the SoT the cockpit and the
+  // no-progress guard read, so a duplicate row corrupts both. Upsert on `(pr_key, round_no)`:
+  // update the existing round-record row in place, else insert. Application-level (no
+  // migration/UNIQUE) so it heals installs that already carry pre-#786 duplicates rather than
+  // crashing on a new constraint.
+  //
+  // But the upsert MUST reuse only a row THIS run's `pr.persist-round` wrote — identity, not a
+  // status heuristic. Two ways a stale-but-status-eligible row can share `(pr_key, round_no)`:
+  //   • An escalation row: on a `needs_input`/`blocked` escalation, `pr.persist-escalation` inserts
+  //     a `rounds` row (status `needs_input`/`blocked`) for the SAME `(pr_key, round_no)`, and the
+  //     human-answered resume re-enters that numeric round → back here. Reusing it would overwrite
+  //     the escalation to `addressed`, ERASING the escalation attempt from the durable history.
+  //   • A prior RUN's row: `submitPr` re-opens a previously converged/abandoned/merged PR at
+  //     `current_round = 1` WITHOUT deleting `rounds` history, so a fresh convergence run (a NEW
+  //     process instance) at round 1 finds the prior run's `addressed`/`waiting`/`converged` round-1
+  //     row. Reusing it (its status is not a human-hold) would clobber another run's canonical
+  //     history — the resubmission drift the reviewer flagged.
+  // The idempotency target is precisely "the row a husk auto-retry of THIS process instance wrote",
+  // and a husk retry re-enters `review-round` in the SAME process instance while a resubmission is a
+  // NEW one. So scope reuse by the writing `process_instance_key` (persisted below) AND exclude
+  // human-hold rows: reuse a row only when it carries the current instance's key and a non-hold
+  // status; otherwise insert a fresh row so every prior run's history — and every escalation — is
+  // preserved. `job.processInstanceKey` is always present for an engine job; when it is absent (a
+  // testkit/synthetic job) we fall back to the status-only heuristic so idempotency still holds
+  // within that single run.
+  const roundsTbl = app.data.table<{
+    id: number;
+    pr_key: string;
+    round_no: number;
+    status: string;
+    summary?: string;
+    transcript: string | null;
+    worker?: string;
+    started_at: string;
+    ended_at: string;
+    process_instance_key?: string | null;
+  }>("rounds", "id");
+  const HUMAN_HOLD_STATUSES = new Set(["needs_input", "blocked"]);
+  const processInstanceKey = job.processInstanceKey != null ? String(job.processInstanceKey) : null;
+  const matching = await roundsTbl.find({ pr_key: prKey, round_no: round });
+  // Reuse only a round-record row written by THIS run (matching process instance, when known) and
+  // never an escalation (human-hold) row; of those, the newest (greatest id).
+  const reusable = matching
+    .filter((r) => !HUMAN_HOLD_STATUSES.has(r.status))
+    .filter((r) => processInstanceKey === null || r.process_instance_key === processInstanceKey)
+    .reduce<{ id: number } | null>((newest, r) => (newest && newest.id >= r.id ? newest : r), null);
+  const roundRow = {
     status,
     summary,
     transcript: transcriptOf(job.variables),
     worker: workerOf(job.variables),
-    started_at: now,
     ended_at: now,
-  });
+  };
+  if (reusable) {
+    await roundsTbl.update(reusable.id, roundRow);
+  } else {
+    await roundsTbl.insert({
+      pr_key: prKey,
+      round_no: round,
+      started_at: now,
+      process_instance_key: processInstanceKey,
+      ...roundRow,
+    });
+  }
+  // Advance the round pointer only; the PARK into `waiting_review` is owned by pr.progress-check,
+  // the single writer of the post-round wait status. persist-round must NOT park here — it runs
+  // BEFORE the husk decision, so writing `waiting_review` now would expose a husk-retry round (which
+  // re-enters review-round WITHOUT waiting for a review) to the poller's `waiting_review` scan for
+  // the window until progress-check resolves the outcome, letting the poller fire a spurious Copilot
+  // re-request (#786). Leaving the row on its running `converging` status until progress-check
+  // decides closes that window; only the genuine review-wait park sets `waiting_review`.
   await app.data.table("pull_requests", "pr_key").update(prKey, {
-    status: "waiting_review",
     current_round: round,
-    waiting_since: now,
     updated_at: now,
   });