@nanobpm/nano-workforce 0.187.3 → 0.187.5

package/app/roundProgress.test.ts

@@ -10,7 +10,7 @@
 import { readFileSync } from "node:fs";
 import { test } from "node:test";
 import { assert, assertEquals, assertStringIncludes } from "#test-assert";
-import { routeProgress } from "./roundProgress.ts";
+import { decideProgress, MAX_HUSK_RETRIES, noProgressQuestion, routeProgress } from "./roundProgress.ts";
 
 // ── The canonical router ────────────────────────────────────────────────────
 
@@ -68,13 +68,123 @@ test("routeProgress: fails OPEN when either head is unknown (no baseline / unrea
   }
 });
 
+// ── Husk classification & bounded self-heal (issue #786) ─────────────────────
+
+test("decideProgress: a progressing round continues and RESETS the husk counter", () => {
+  // head advanced -> progressed, huskRetries reset to 0 regardless of the carried count.
+  const d = decideProgress("addressed", "sha-1", "sha-2", 3, null, 2);
+  assertEquals(d.progressed, true);
+  assertEquals(d.huskRetries, 0);
+  assertEquals(d.huskRetry, undefined);
+  assertEquals(d.reason, undefined);
+});
+
+test("decideProgress: a husk (successful empty agent-work read) under the cap auto-retries the same round", () => {
+  // no head advance + a SUCCESSFUL empty agent-instance read (false) => husk. Under the cap it
+  // re-runs the same round on a healthy worker and bumps the counter.
+  const d = decideProgress("addressed", "sha-1", "sha-1", 5, false, 0);
+  assertEquals(d.progressed, false);
+  assertEquals(d.huskRetry, true, "a corroborated-empty husk must auto-retry");
+  assertEquals(d.huskRetries, 1, "the husk bumps the counter");
+  assertEquals(d.reason, "husk");
+  assertEquals(d.question, undefined, "an auto-retry opens no escalation question");
+});
+
+test("decideProgress: an UNKNOWN agent-work read (null/undefined) escalates as no-advance — never auto-retries", () => {
+  // An engine read that was unavailable/threw (null) — or was never attempted (undefined) — is NOT a
+  // corroborated husk. Auto-retrying it could duplicate agent work that actually ran, so it fails
+  // safe to an immediate no-advance escalation, exactly as the pre-#786 loop did.
+  for (const observed of [null, undefined] as const) {
+    const d = decideProgress("addressed", "sha-1", "sha-1", 5, observed, 0);
+    assertEquals(d.progressed, false, `observed=${observed}`);
+    assertEquals(d.huskRetry, false, `observed=${observed} must NOT auto-retry an unknown read`);
+    assertEquals(d.huskRetries, 0, `observed=${observed} does not bump the husk counter`);
+    assertEquals(d.reason, "no-advance");
+    assert(d.question, `observed=${observed} escalates with a question`);
+    assertStringIncludes(d.question ?? "", "PR head did not advance");
+  }
+});
+
+test("decideProgress: a husk at the retry cap escalates with a husk-specific question and resets", () => {
+  const d = decideProgress("addressed", "sha-1", "sha-1", 5, false, MAX_HUSK_RETRIES);
+  assertEquals(d.progressed, false);
+  assertEquals(d.huskRetry, false, "the cap is reached — no more auto-retries");
+  assertEquals(d.huskRetries, 0, "the counter resets so a human-answered resume gets fresh retries");
+  assertEquals(d.reason, "husk");
+  assert(d.question, "an escalating husk carries a question");
+  assertStringIncludes(d.question ?? "", "no durable work");
+  assertStringIncludes(d.question ?? "", "did not help");
+});
+
+test("decideProgress: a no-advance round (agent DID run) escalates immediately — never auto-retries", () => {
+  // A terminal agent-instance exists (agentWorkObserved=true): the agent ran but pushed nothing.
+  // Re-running would loop on identical reasoning, so escalate straight away even with 0 retries used.
+  const d = decideProgress("addressed", "sha-1", "sha-1", 4, true, 0);
+  assertEquals(d.progressed, false);
+  assertEquals(d.huskRetry, false, "a no-advance round is never auto-retried");
+  assertEquals(d.reason, "no-advance");
+  assert(d.question, "a no-advance round carries a question");
+  assertStringIncludes(d.question ?? "", "PR head did not advance");
+});
+
+test("decideProgress: a legitimately non-addressed / unreadable-head round continues without a husk verdict", () => {
+  for (const args of [
+    ["waiting", "sha-1", "sha-1", 1, null, 0],
+    ["addressed", null, "sha-1", 1, null, 0],
+    ["addressed", "sha-1", null, 1, null, 0],
+  ] as const) {
+    const d = decideProgress(...args);
+    assertEquals(d.progressed, true, `${JSON.stringify(args)} must continue`);
+    assertEquals(d.reason, undefined);
+    assertEquals(d.huskRetries, 0);
+  }
+});
+
+test("decideProgress: a NO-BASELINE addressed round ALWAYS fails open — the no-baseline husk special-case is gone (closed structurally by pr.capture-head)", () => {
+  // The no-baseline case is now handled UPSTREAM: `pr.capture-head` records the round's entry head
+  // into `roundEntryHead` before `review-round` runs, so within a round there is always a baseline
+  // and a first-addressed-round husk leaves `currentHead === roundEntryHead` (→ the escalate/husk
+  // split). Consequently `decideProgress` itself no longer special-cases a null baseline: with no
+  // baseline the head-diff cannot see a no-advance, so it fails OPEN for EVERY agent-work verdict —
+  // including a corroborated non-terminal read that the old code retried. This removes the opposing
+  // risk of mis-escalating a straggler push the old special-case carried.
+  for (const agentWork of [true, false, null, undefined] as const) {
+    const d = decideProgress("addressed", null, "sha-1", 1, agentWork, 0);
+    assertEquals(d.progressed, true, `no baseline + agentWork=${String(agentWork)} fails open`);
+    assertEquals(d.huskRetry, undefined, "no baseline never auto-retries");
+    assertEquals(d.reason, undefined, "a no-baseline round carries no husk verdict");
+    assertEquals(d.huskRetries, 0, "the husk counter resets on a fail-open round");
+  }
+});
+
+test("decideProgress: a garbage carried husk-retry counter is coerced to 0", () => {
+  for (const bad of [Number.NaN, -3, undefined, null] as const) {
+    const d = decideProgress("addressed", "sha-1", "sha-1", 5, false, bad);
+    assertEquals(d.huskRetry, true, `counter ${String(bad)} coerces to 0 -> under the cap`);
+    assertEquals(d.huskRetries, 1);
+  }
+});
+
+test("noProgressQuestion: husk vs no-advance render distinct, human-actionable reasons", () => {
+  assertStringIncludes(noProgressQuestion(5, "husk", false), "no durable work");
+  assertStringIncludes(noProgressQuestion(5, "no-advance", false), "PR head did not advance");
+});
+
 // ── The worker (with an injected head reader — never touches git/network) ────
 
-function fakeApp(row?: { last_round_head: string | null }) {
+function fakeApp(
+  row?: ({ last_round_head: string | null } & Record<string, unknown>) | undefined,
+  searchAgentInstances: (arg: unknown) => Promise<unknown[]> = async () => [],
+) {
   const updates: { key: string; patch: Record<string, unknown> }[] = [];
-  const store = new Map<string, unknown>();
+  const store = new Map<string, Record<string, unknown>>();
   if (row) store.set("o/r#1", { pr_key: "o/r#1", ...row });
   const app = {
+    // The default agent-work reader consults app.engine.searchAgentInstances; the fake returns an
+    // empty list (read-as-absence → availability probe → null → no-advance) by default so a test
+    // exercises the AVAILABILITY-AWARE default reader unless it injects its own readAgentWork or a
+    // non-empty instance list.
+    engine: { searchAgentInstances },
     data: {
       table(_name: string, _key: string) {
         return {
@@ -83,6 +193,9 @@ function fakeApp(row?: { last_round_head: string | null }) {
           },
           async update(key: string, patch: Record<string, unknown>) {
             updates.push({ key, patch });
+            // Apply the patch so a redelivery in the SAME test observes the committed baseline +
+            // idempotency stamp — the faithful double for the at-least-once replay guard (#789).
+            store.set(key, { ...(store.get(key) ?? { pr_key: key }), ...patch });
           },
         };
       },
@@ -91,22 +204,57 @@ function fakeApp(row?: { last_round_head: string | null }) {
   return { app, updates };
 }
 
-async function makeUnderTest(readHead: (repo: string, n: number) => Promise<string | null>) {
+async function makeUnderTest(
+  readHead: (repo: string, n: number) => Promise<string | null>,
+  readAgentWork?: (
+    pik: string | null | undefined,
+    round: number,
+    priorWatermark?: string | null,
+  ) => Promise<boolean | null | { work: boolean | null; consumedKey?: string | null }>,
+) {
   const { makeHandler } = await import("../workers/progress-check/worker.ts");
-  return makeHandler({ readHead });
+  return makeHandler(readAgentWork ? { readHead, readAgentWork } : { readHead });
 }
 
-test("progress-check: skips the head read entirely for a non-addressed round", async () => {
+test("progress-check: a non-addressed round records the baseline and consumes the attempt watermark but never escalates", async () => {
+  // Post-#786 the head read + baseline write happen for EVERY round (so the first `addressed` round
+  // has a baseline to compare against). Post-#789 (worker.ts:329) a non-addressed `waiting` round
+  // ALSO consults the agent-work channel — its own review runs BEFORE this progress-check, so it must
+  // CONSUME that review-round instance into the attempt watermark, else a following addressed
+  // pre-registration husk would see the stale terminal instance as "newer than the watermark" and
+  // bypass the bounded husk retry. It still short-circuits to progressed:true and never escalates.
   let called = false;
-  const handler = await makeUnderTest(async () => {
-    called = true;
-    return "sha-2";
-  });
+  let agentReads = 0;
+  const handler = await makeUnderTest(
+    async () => {
+      called = true;
+      return "sha-2";
+    },
+    async () => {
+      agentReads++;
+      // The waiting round's own review-round left a terminal instance keyed "9"; the reader reports
+      // it consumed (its verdict is irrelevant on the non-addressed path).
+      return { work: true, consumedKey: "9" };
+    },
+  );
   const { app, updates } = fakeApp({ last_round_head: "sha-1" });
-  const out = await handler({ variables: { prKey: "o/r#1", status: "waiting", repo: "o/r", prNumber: 1 } } as any, app as any);
-  assertEquals(out, { progressed: true });
-  assertEquals(called, false, "a waiting round never reads the head");
-  assertEquals(updates.length, 0, "and never rewrites the baseline");
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "waiting", repo: "o/r", prNumber: 1 } } as any, app as any);
+  assertEquals(out, { progressed: true, huskRetries: 0 });
+  assertEquals(called, true, "a waiting round reads the head to seed the baseline");
+  assertEquals(agentReads, 1, "and consults the agent-work channel to consume its own review instance");
+  // ONE atomic write now (Copilot #789): the baseline head advance, the review-wait PARK, and the
+  // attempt-watermark advance are folded into a single row update so a redelivery can't observe a
+  // half-state. persist-round no longer parks — pr.progress-check is the single writer of
+  // `waiting_review` (#786).
+  assertEquals(updates.length, 1, "records the baseline and parks for review in one atomic write");
+  assertEquals(updates[0]!.patch.last_round_head, "sha-2", "the observed head is the new baseline");
+  assertEquals(updates[0]!.patch.status, "waiting_review", "the round parks for review");
+  assertEquals(typeof updates[0]!.patch.waiting_since, "string", "and stamps the review-wait start");
+  assertEquals(
+    updates[0]!.patch.last_progress_agent_watermark,
+    "9",
+    "the waiting round consumes its own review instance into the watermark (Copilot #789 worker.ts:329)",
+  );
 });
 
 test("progress-check: a blank/unknown status is treated as addressed — reads the head and can report no progress", async () => {
@@ -116,41 +264,180 @@ test("progress-check: a blank/unknown status is treated as addressed — reads t
     return "sha-1";
   });
   const { app } = fakeApp({ last_round_head: "sha-1" });
-  const out = await handler({ variables: { prKey: "o/r#1", status: "", repo: "o/r", prNumber: 1 } } as any, app as any);
-  assertEquals(out, { progressed: false }, "a blank-status no-progress round is caught, not waved through");
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "", repo: "o/r", prNumber: 1, round: 5, huskRetries: MAX_HUSK_RETRIES } } as any, app as any);
+  assertEquals(out.progressed, false, "a blank-status no-progress round is caught, not waved through");
   assertEquals(called, true, "a blank status (the safe-default addressed trap) still reads the head");
 });
 
-test("progress-check: an addressed round whose head is unchanged reports progressed:false", async () => {
-  const handler = await makeUnderTest(async () => "sha-1");
+test("progress-check: an addressed round whose head is unchanged with no agent work AUTO-RETRIES (husk) under the cap", async () => {
+  // No terminal review-round agent-instance (injected false) => husk. Under the cap the worker
+  // re-runs the same round instead of parking a human.
+  const handler = await makeUnderTest(async () => "sha-1", async () => false);
+  const { app, updates } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 5, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, true, "the husk is auto-retried");
+  assertEquals(out.huskRetries, 1);
+  assertEquals(out.noProgressReason, "husk");
+  // Poller non-interference (#786): the retry keeps the PR on a running `converging` status (never a
+  // transient `waiting_review`) so pollReviews can't solicit a spurious review while the retried
+  // round re-enters review-round. persist-round no longer parks, so this is the ONLY status write.
+  const parked = updates.find((u) => u.patch.status === "waiting_review");
+  assertEquals(parked, undefined, "a husk-retry round NEVER transits waiting_review");
+  const statusUpdate = updates.find((u) => u.patch.status !== undefined);
+  assert(statusUpdate, "a husk retry must update the PR status");
+  assertEquals(statusUpdate!.patch.status, "converging", "the retry flips the PR to a running status");
+});
+
+test("progress-check: an unchanged head with an UNKNOWN agent-work read (null) escalates as no-advance, never auto-retries", async () => {
+  // A transient/unavailable AgentInstance read (injected null) must not be treated as a husk — it
+  // fails safe to an immediate no-advance escalation so a read outage can never auto-retry (and
+  // possibly duplicate) genuinely-completed agent work.
+  const handler = await makeUnderTest(async () => "sha-1", async () => null);
   const { app } = fakeApp({ last_round_head: "sha-1" });
-  const out = await handler({ variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1 } } as any, app as any);
-  assertEquals(out, { progressed: false });
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 5, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, false, "an unknown read is never auto-retried");
+  assertEquals(out.noProgressReason, "no-advance");
+  assertStringIncludes(String(out.noProgressQuestion), "PR head did not advance");
+});
+
+test("progress-check: an unchanged head with a terminal agent-instance escalates as no-advance (never auto-retry)", async () => {
+  const handler = await makeUnderTest(async () => "sha-1", async () => true);
+  const { app } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 3, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, false, "a corroborated no-advance round is never auto-retried");
+  assertEquals(out.noProgressReason, "no-advance");
+  assertStringIncludes(String(out.noProgressQuestion), "PR head did not advance");
 });
 
 test("progress-check: an addressed round whose head advanced reports progressed:true and rebaselines", async () => {
   const handler = await makeUnderTest(async () => "sha-2");
   const { app, updates } = fakeApp({ last_round_head: "sha-1" });
-  const out = await handler({ variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1 } } as any, app as any);
-  assertEquals(out, { progressed: true });
-  assertEquals(updates.length, 1, "the observed head is recorded as the new baseline");
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 2 } } as any, app as any);
+  assertEquals(out.progressed, true);
+  assertEquals(out.huskRetries, 0, "a progressing round resets the husk counter");
+  // ONE atomic write (Copilot #789): the rebaseline and the review-wait PARK are a single row
+  // update so a redelivery can't see the advanced baseline without the park. progress-check owns
+  // `waiting_review` now (#786).
+  assertEquals(updates.length, 1, "the observed head is rebaselined and parked in one atomic write");
   assertEquals(updates[0]!.patch.last_round_head, "sha-2");
+  assertEquals(updates[0]!.patch.status, "waiting_review", "a progressed round parks for review");
+  assertEquals(typeof updates[0]!.patch.waiting_since, "string", "and stamps the review-wait start");
+});
+
+test("progress-check: a lost completion-ack REDELIVERS the same job — the recorded outcome is replayed, not recomputed against the advanced baseline (idempotent)", async () => {
+  // Copilot #789 (engine at-least-once delivery): a progressed round advances `last_round_head` to
+  // the new head. If its completion-ack is LOST the engine redelivers the SAME job key. Without the
+  // idempotency guard the redelivery reads the just-advanced baseline as `previousHead`, sees the
+  // (still-unchanged) head as "no advance", and mis-ESCALATES an already-progressed round. The guard
+  // must recognize its own job key and REPLAY the recorded progressed outcome, making no new write
+  // and never consulting the agent-work channel.
+  let agentReads = 0;
+  const readAgentWork = async () => {
+    agentReads++;
+    return null; // would drive a no-advance ESCALATION if the guard let it recompute
+  };
+  // Head reader returns the SAME advanced head on both deliveries (no new push between them).
+  const handler = await makeUnderTest(async () => "sha-2", readAgentWork);
+  const { app, updates } = fakeApp({ last_round_head: "sha-1" });
+
+  // First delivery: an addressed round whose head advanced → progressed:true, stamps the baseline +
+  // idempotency record atomically.
+  const first = await handler(
+    { jobKey: "job-1", processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 2, huskRetries: 0 } } as any,
+    app as any,
+  );
+  assertEquals(first.progressed, true, "the first delivery sees the advance and progresses");
+  const writesAfterFirst = updates.length;
+  assertEquals(agentReads, 1, "a progressing round reads agent-work once to maintain the attempt watermark (#789)");
+
+  // Second delivery: the SAME job key redelivered after a lost ack. The baseline is now "sha-2" and
+  // the head is unchanged, so a RECOMPUTE would read "no advance" and escalate. The guard must
+  // replay the recorded progressed outcome instead.
+  const replay = await handler(
+    { jobKey: "job-1", processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 2, huskRetries: 0 } } as any,
+    app as any,
+  );
+  assertEquals(replay.progressed, true, "the redelivery REPLAYS progressed:true, never mis-escalates");
+  assertEquals(replay.huskRetry, undefined, "the replay is not a no-advance/husk escalation");
+  assertEquals(agentReads, 1, "the replay short-circuits before recomputing, so it adds no further read");
+  assertEquals(updates.length, writesAfterFirst, "the replay makes no new write (pure replay)");
 });
 
 test("progress-check: the first observed round (no baseline) continues and records the baseline", async () => {
   const handler = await makeUnderTest(async () => "sha-1");
   const { app, updates } = fakeApp(); // no row yet -> previousHead null
-  const out = await handler({ variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1 } } as any, app as any);
-  assertEquals(out, { progressed: true }, "no baseline yet fails open");
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 1 } } as any, app as any);
+  assertEquals(out.progressed, true, "no baseline yet fails open");
   assertEquals(updates[0]!.patch.last_round_head, "sha-1");
 });
 
+test("progress-check: capture-head's roundEntryHead is the within-round baseline — a first-round husk that pushed nothing (head == roundEntryHead, non-terminal instance) is now CAUGHT and retried (#786/#789 categorical fix)", async () => {
+  // Copilot #789 "close both sides": `pr.capture-head` records the round-entry head into
+  // `roundEntryHead` BEFORE `review-round` runs, so even the FIRST addressed round has a baseline. A
+  // husk that pushed nothing leaves `currentHead === roundEntryHead`, so the head-diff now sees a
+  // no-advance, and the non-terminal completing instance (agentWork=false) splits it into a husk that
+  // auto-retries — no longer waved through as progress for want of a baseline.
+  const handler = await makeUnderTest(async () => "sha-1", async () => false);
+  const { app } = fakeApp(); // no persisted last_round_head — the baseline comes from roundEntryHead
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 1, huskRetries: 0, roundEntryHead: "sha-1" } } as any, app as any);
+  assertEquals(out.progressed, false, "a first-round husk is NOT waved through as progress");
+  assertEquals(out.huskRetry, true, "the first-round husk auto-retries the same round");
+  assertEquals(out.noProgressReason, "husk");
+});
+
+test("progress-check: with a roundEntryHead baseline, a first-round terminal no-advance (head == roundEntryHead, terminal instance) now escalates as no-advance — the other side closed", async () => {
+  // The mirror of the categorical fix: a real terminal attempt that pushed nothing on the FIRST round
+  // is a genuine no-advance and now escalates immediately — previously it failed open for want of a
+  // baseline. The within-round baseline makes both husk and no-advance classifiable from round one.
+  const handler = await makeUnderTest(async () => "sha-1", async () => true);
+  const { app } = fakeApp();
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 1, huskRetries: 0, roundEntryHead: "sha-1" } } as any, app as any);
+  assertEquals(out.progressed, false, "a first-round terminal no-advance escalates");
+  assertEquals(out.huskRetry, false, "a no-advance never auto-retries");
+  assertEquals(out.noProgressReason, "no-advance");
+});
+
+test("progress-check: a real push within the round (currentHead != roundEntryHead) is progress, never a false husk", async () => {
+  // The complement: capture-head recorded the entry head, the agent pushed a commit, so currentHead
+  // advances past roundEntryHead → progress, regardless of the (non-terminal) instance state. This is
+  // the false-husk direction the within-round baseline closes.
+  const handler = await makeUnderTest(async () => "sha-2", async () => false);
+  const { app } = fakeApp();
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 1, huskRetries: 0, roundEntryHead: "sha-1" } } as any, app as any);
+  assertEquals(out.progressed, true, "a head advance within the round is progress");
+  assertEquals(out.huskRetry, undefined);
+});
+
+test("progress-check: roundEntryHead takes PRECEDENCE over the persisted last_round_head; an empty-string roundEntryHead (capture read failed) falls back to last_round_head", async () => {
+  // Precedence: capture-head's within-round entry head is the primary baseline.
+  const h1 = await makeUnderTest(async () => "sha-9", async () => false);
+  const a1 = fakeApp({ last_round_head: "stale-old" });
+  const o1 = await h1({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 3, huskRetries: 0, roundEntryHead: "sha-9" } } as any, a1.app as any);
+  assertEquals(o1.progressed, false, "head==roundEntryHead is a no-advance even though it != last_round_head");
+  assertEquals(o1.noProgressReason, "husk");
+  // Fallback: an empty-string roundEntryHead (capture-head could not read the entry head) is treated
+  // as no round-entry baseline, so the persisted last_round_head is used instead.
+  const h2 = await makeUnderTest(async () => "sha-1", async () => false);
+  const a2 = fakeApp({ last_round_head: "sha-1" });
+  const o2 = await h2({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 3, huskRetries: 0, roundEntryHead: "" } } as any, a2.app as any);
+  assertEquals(o2.progressed, false, "empty roundEntryHead falls back to last_round_head baseline");
+  assertEquals(o2.noProgressReason, "husk");
+});
+
 test("progress-check: an unreadable head fails open and does not clobber the baseline", async () => {
   const handler = await makeUnderTest(async () => null);
   const { app, updates } = fakeApp({ last_round_head: "sha-1" });
-  const out = await handler({ variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1 } } as any, app as any);
-  assertEquals(out, { progressed: true }, "a null head fails open");
-  assertEquals(updates.length, 0, "a null head never overwrites the good baseline");
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 2 } } as any, app as any);
+  assertEquals(out.progressed, true, "a null head fails open");
+  // A null head is never written as a baseline (it must not clobber the good `last_round_head`), but
+  // the round still fails OPEN to the review wait, so progress-check parks it (persist-round no
+  // longer does). The single write is therefore the PARK, carrying no `last_round_head`.
+  assertEquals(updates.length, 1, "only the review-wait park is written");
+  assertEquals(updates[0]!.patch.last_round_head, undefined, "a null head never overwrites the baseline");
+  assertEquals(updates[0]!.patch.status, "waiting_review", "a fail-open round still parks for review");
 });
 
 test("progress-check: resolves repo/prNumber from the prKey when the vars are absent", async () => {
@@ -160,10 +447,234 @@ test("progress-check: resolves repo/prNumber from the prKey when the vars are ab
     return "sha-2";
   });
   const { app } = fakeApp({ last_round_head: "sha-1" });
-  await handler({ variables: { prKey: "o/r#1", status: "addressed" } } as any, app as any);
+  await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", round: 2 } } as any, app as any);
   assertEquals(seen, ["o/r", 1], "falls back to parsing owner/repo#N from the prKey");
 });
 
+test("progress-check: reads agent-instances on EVERY addressed round (incl. a progressing one) to maintain the attempt watermark (#789)", async () => {
+  // Copilot #789: the husk verdict is only consulted on the no-advance path, but the read must ALSO
+  // run on a progressing round so its fresh `review-round` instance is CONSUMED into the watermark —
+  // otherwise the next round's pre-registration husk would see that stale terminal instance as
+  // "newer than the watermark" and mis-escalate. The advancing head still fails open to progress.
+  let agentReads = 0;
+  const handler = await makeUnderTest(async () => "sha-2", async () => {
+    agentReads++;
+    return true;
+  });
+  const { app } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 2 } } as any, app as any);
+  assertEquals(agentReads, 1, "a progressing round still reads once to advance the attempt watermark");
+  assertEquals(out.progressed, true, "an advancing head is still progress regardless of the read");
+});
+
+test("progress-check: an unreadable head STILL reads the agent channel to advance the watermark (Copilot #789 worker.ts:372)", async () => {
+  // A GitHub outage that blanks the current head must not also skip consuming this round's own
+  // `review-round` instance into the attempt watermark: if it did, a later pre-registration husk
+  // would see that unconsumed terminal instance as newer than the stale watermark and mis-classify
+  // itself as no-advance. So the agent read runs even with a null head; the head-diff still fails
+  // open to progress, but the watermark advances.
+  let agentReads = 0;
+  const handler = await makeUnderTest(async () => null, async () => {
+    agentReads++;
+    return { work: true, consumedKey: "77" };
+  });
+  const { app, updates } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 2 } } as any, app as any);
+  assertEquals(agentReads, 1, "an unreadable head still reads the channel to advance the watermark");
+  assertEquals(out.progressed, true, "an unreadable head fails open to progress");
+  assertEquals(
+    updates[0]!.patch.last_progress_agent_watermark,
+    "77",
+    "the round consumes its review instance into the watermark despite the head-read outage",
+  );
+});
+
+// ── The DEFAULT (availability-aware) agent-work reader over app.engine.searchAgentInstances ──────
+// These exercise agentWorkFromEngine directly (no injected readAgentWork), via fakeApp's injectable
+// engine, to lock the Option 1 (#786) semantics: BOTH-empty→unknown→no-advance; scoped-empty-but-
+// channel-present→husk; non-terminal→husk; all-terminal→no-advance; correlation is by the COMPLETING
+// element-instance, not a round count.
+
+test("progress-check default reader: a WHOLLY-empty process instance (absent channel) fails safe to no-advance, never a husk", async () => {
+  // Two-tier availability probe: on a channel-absent engine (the testkit double returns [] for EVERY
+  // search — both the scoped review-round query AND the process-wide probe) the channel is UNKNOWN,
+  // so empty ⇒ no-advance — NOT a husk auto-retry that could loop forever on a non-agentic engine.
+  const handler = await makeUnderTest(async () => "sha-1"); // no injected readAgentWork -> default
+  const { app } = fakeApp({ last_round_head: "sha-1" }, async () => []);
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 5, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, false, "an absent channel must never auto-retry");
+  assertEquals(out.noProgressReason, "no-advance");
+});
+
+test("progress-check default reader: an empty review-round search but a CHANNEL-PRESENT process (another agent instance exists) ⇒ husk — the round husked before registering (#789)", async () => {
+  // Copilot #789: review-round is an external-agent serviceTask, so a job that husks BEFORE the
+  // worker registers its AgentInstance mints NOTHING — the scoped search is empty even on a
+  // channel-present engine. The process-wide probe disambiguates: another agent instance (e.g.
+  // classify-scope, or an earlier round) proves the channel is PRESENT, so the empty review-round is
+  // a genuine husk (auto-retry), not an absent channel.
+  const handler = await makeUnderTest(async () => "sha-1");
+  const { app } = fakeApp({ last_round_head: "sha-1" }, async (arg) => {
+    // Filter-aware double: the scoped review-round query is EMPTY (the round husked pre-registration),
+    // but the process-wide probe returns a classify-scope instance (channel present).
+    const f = (arg ?? {}) as { elementId?: string };
+    if (f.elementId === "review-round") return [];
+    return [{ status: "completed", completionDate: "2024-01-01T00:00:00Z", elementInstanceKeys: ["50"] }];
+  });
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 5, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, true, "a channel-present empty review-round is a husk, so it auto-retries");
+  assertEquals(out.noProgressReason, "husk");
+});
+
+test("progress-check default reader: a non-terminal review-round instance ⇒ husk (auto-retry under cap)", async () => {
+  // Channel present, the completing attempt (newest element-instance) is stuck non-terminal
+  // (husked) => false => husk. The stale terminal instance is an EARLIER attempt (lower key).
+  const handler = await makeUnderTest(async () => "sha-1");
+  const { app } = fakeApp({ last_round_head: "sha-1" }, async () => [
+    { status: "completed", completionDate: "2024-01-01T00:00:00Z", elementInstanceKeys: ["100"] },
+    { status: "THINKING", completionDate: null, elementInstanceKeys: ["200"] },
+  ]);
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 5, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, true, "a non-terminal completing attempt is a husk");
+  assertEquals(out.noProgressReason, "husk");
+});
+
+test("progress-check default reader: ALL-terminal review-round instances ⇒ no-advance (never auto-retry)", async () => {
+  // Channel present, every instance (including the completing attempt) is terminal => true =>
+  // genuine no-advance — the agent ran to completion but produced no head change, a human question.
+  const handler = await makeUnderTest(async () => "sha-1");
+  const { app } = fakeApp({ last_round_head: "sha-1" }, async () => [
+    { status: "completed", completionDate: "2024-01-01T00:00:00Z", elementInstanceKeys: ["100"] },
+    { status: "failed", completionDate: "2024-01-02T00:00:00Z", elementInstanceKeys: ["200"] },
+  ]);
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 5, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, false, "an all-terminal round is a genuine no-advance, not a husk");
+  assertEquals(out.noProgressReason, "no-advance");
+});
+
+test("progress-check default reader: a STALE non-terminal prior attempt does NOT mask a terminal completing attempt (no false husk)", async () => {
+  // #786 correlation defect: `.every(isTerminalInstance)` over ALL historical instances mis-flags a
+  // genuine no-advance as a husk whenever an EARLIER attempt is still stuck non-terminal. The newest
+  // element-instance (greatest engine key) is the COMPLETING attempt and it is terminal => no-advance,
+  // regardless of the stale husked prior instance.
+  const handler = await makeUnderTest(async () => "sha-1");
+  const { app } = fakeApp({ last_round_head: "sha-1" }, async () => [
+    { status: "THINKING", completionDate: null, elementInstanceKeys: ["100"] }, // stale prior husk
+    { status: "completed", completionDate: "2024-01-02T00:00:00Z", elementInstanceKeys: ["200"] }, // newest, terminal
+  ]);
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 5, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, false, "a stale non-terminal prior attempt must not fabricate a husk");
+  assertEquals(out.noProgressReason, "no-advance");
+});
+
+test("progress-check default reader: a same-round husk AFTER an earlier terminal attempt is a husk (newest instance wins)", async () => {
+  // The mirror case: an earlier attempt in this round ran to a terminal instance, then a resume
+  // husked. The newest element-instance (greatest engine key) is the non-terminal resume => husk,
+  // not masked by the earlier terminal instance.
+  const handler = await makeUnderTest(async () => "sha-1");
+  const { app } = fakeApp({ last_round_head: "sha-1" }, async () => [
+    { status: "completed", completionDate: "2024-01-01T00:00:00Z", elementInstanceKeys: ["300"] }, // earlier terminal
+    { status: "THINKING", completionDate: null, elementInstanceKeys: ["400"] }, // newest, husked
+  ]);
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 5, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, true, "the newest attempt husked, so the round is a husk");
+  assertEquals(out.noProgressReason, "husk");
+});
+
+test("progress-check default reader: an engine read that THROWS degrades to no-advance (unknown), never a husk", async () => {
+  const handler = await makeUnderTest(async () => "sha-1");
+  const { app } = fakeApp({ last_round_head: "sha-1" }, async () => {
+    throw new Error("engine unreachable");
+  });
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 5, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, false, "a read outage must never auto-retry");
+  assertEquals(out.noProgressReason, "no-advance");
+});
+
+test("progress-check default reader: a prior round's TERMINAL instance does NOT mask a current pre-registration husk (#789)", async () => {
+  // Copilot #789 suppressed comment (worker.ts:184): if an earlier round's `review-round` instance
+  // is terminal and the CURRENT attempt husks BEFORE registering any AgentInstance, the scoped
+  // search still returns that earlier terminal row as `newest` — which, read naively, returns `true`
+  // and routes to a no-advance escalation, BYPASSING the bounded husk retry. The attempt watermark
+  // fixes it: the persisted watermark (100) already ACCOUNTED FOR that terminal instance, so a scoped
+  // search whose greatest key is still 100 (no NEWER instance) means the current attempt registered
+  // nothing new — a genuine husk (auto-retry), not a no-advance.
+  const handler = await makeUnderTest(async () => "sha-1");
+  const { app, updates } = fakeApp(
+    { last_round_head: "sha-1", last_progress_agent_watermark: "100" },
+    async () => [
+      { status: "completed", completionDate: "2024-01-01T00:00:00Z", elementInstanceKeys: ["100"] }, // prior terminal, already consumed
+    ],
+  );
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 6, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, true, "no instance newer than the watermark ⇒ the current attempt husked pre-registration");
+  assertEquals(out.noProgressReason, "husk");
+  // The watermark stays where it was — nothing new was consumed.
+  const wm = updates.at(-1)?.patch.last_progress_agent_watermark;
+  assertEquals(wm, "100", "a pre-registration husk leaves the watermark unchanged");
+});
+
+test("progress-check default reader: a NEW terminal attempt past the watermark ⇒ no-advance and ADVANCES the watermark (#789)", async () => {
+  // The complement: the current attempt DID register (a `review-round` instance keyed 200, newer than
+  // the watermark 100), and it is terminal — a genuine no-advance. The watermark advances to 200 so
+  // the NEXT round can tell the attempt after it from this one.
+  const handler = await makeUnderTest(async () => "sha-1");
+  const { app, updates } = fakeApp(
+    { last_round_head: "sha-1", last_progress_agent_watermark: "100" },
+    async () => [
+      { status: "completed", completionDate: "2024-01-01T00:00:00Z", elementInstanceKeys: ["100"] }, // prior, consumed
+      { status: "completed", completionDate: "2024-01-02T00:00:00Z", elementInstanceKeys: ["200"] }, // fresh terminal attempt
+    ],
+  );
+  const out = await handler({ processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 6, huskRetries: 0 } } as any, app as any);
+  assertEquals(out.progressed, false);
+  assertEquals(out.huskRetry, false, "a fresh terminal attempt is a genuine no-advance");
+  assertEquals(out.noProgressReason, "no-advance");
+  const wm = updates.at(-1)?.patch.last_progress_agent_watermark;
+  assertEquals(wm, "200", "consuming a fresh attempt advances the watermark");
+});
+
+test("progress-check: a straggler from a SUPERSEDED process instance does NOT write into the re-opened row (process-instance fence #789)", async () => {
+  // Copilot #789 (worker.ts:290): after `submitPr` re-opens a PR it clears the per-run fields
+  // (including the idempotency stamp) and starts a NEW convergence instance, setting the row's
+  // `process_key` to that new instance. An OLD progress-check job from the SUPERSEDED instance can
+  // slip past the (now-cleared) replay guard and reach `commit`; writing its stale baseline / status
+  // / watermark would clobber the fresh run. The commit re-reads the row's current `process_key` and
+  // drops the write when the job's own `processInstanceKey` no longer owns the row.
+  const handler = await makeUnderTest(async () => "sha-stale", async () => true);
+  const { app, updates } = fakeApp({ last_round_head: "sha-new", process_key: "PI-NEW" });
+  const out = await handler(
+    // The straggler job belongs to the OLD instance PI-OLD, but the row is now owned by PI-NEW.
+    { jobKey: "job-old", processInstanceKey: "PI-OLD", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 3, huskRetries: 0 } } as any,
+    app as any,
+  );
+  // The job still ACKs with a computed outcome (its token lives in a terminated instance), but it
+  // must persist NOTHING — the fresh run's row is untouched.
+  assertEquals(updates.length, 0, "the superseded straggler writes nothing into the re-opened row");
+  assertEquals(typeof out.progressed, "boolean", "the straggler still returns an outcome to ACK");
+});
+
+test("progress-check: a job whose processInstanceKey OWNS the row still writes normally (fence fails open on match)", async () => {
+  // The complement of the fence: when the job's `processInstanceKey` matches the row's current
+  // `process_key`, the write proceeds exactly as before — the fence only drops a SUPERSEDED straggler.
+  const handler = await makeUnderTest(async () => "sha-2");
+  const { app, updates } = fakeApp({ last_round_head: "sha-1", process_key: "PI-CURRENT" });
+  const out = await handler(
+    { processInstanceKey: "PI-CURRENT", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 2 } } as any,
+    app as any,
+  );
+  assertEquals(out.progressed, true, "the owning job progresses");
+  assertEquals(updates.length, 1, "the owning job writes its baseline/park normally");
+  assertEquals(updates[0]!.patch.last_round_head, "sha-2");
+});
+
 // ── Structural guard over the committed BPMN (no engine) ─────────────────────
 
 const bpmn = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
@@ -193,21 +704,146 @@ test("check-progress feeds the gw-progress gateway", () => {
   assertStringIncludes(flat, 'type="pr.progress-check"');
 });
 
-test("gw-progress escalates a no-progress round on an explicit progressed = false condition", () => {
+test("gw-progress routes a no-progress round into the husk gate on an explicit progressed = false condition", () => {
   const f = flowElement("f_noProgress");
   assert(f, "f_noProgress flow missing");
-  assertStringIncludes(f, 'targetRef="persist-escalation-noprogress"');
+  assertStringIncludes(f, 'targetRef="gw-husk"');
   assertStringIncludes(f, "progressed = false");
 });
 
-test("gw-progress default arm re-enters the review wait with no condition", () => {
+test("gw-husk auto-retries a husk back into review-round, and defaults to the human escalation", () => {
+  // #786: a husked round (no commit AND no terminal review-round agent-instance) is re-run onto a
+  // healthy worker — bounded by the worker's huskRetries cap — before parking a human. The bound
+  // lives in the pr.progress-check worker (app/roundProgress.ts decideProgress), so the gateway only
+  // routes on the worker's `huskRetry` output.
+  const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-husk"[^>]*>/);
+  assert(gw, "gw-husk gateway missing");
+  assertStringIncludes(gw[0], 'default="f_huskEscalate"');
+  const retry = flowElement("f_huskRetry");
+  assert(retry, "f_huskRetry flow missing");
+  assertStringIncludes(retry, 'sourceRef="gw-husk"');
+  assertStringIncludes(retry, 'targetRef="capture-head"');
+  assertStringIncludes(retry, "huskRetry = true");
+  const esc = flowElement("f_huskEscalate");
+  assert(esc, "f_huskEscalate flow missing");
+  assertStringIncludes(esc, 'sourceRef="gw-husk"');
+  assertStringIncludes(esc, 'targetRef="persist-escalation-noprogress"');
+  assert(!/conditionExpression/.test(esc), "the escalate arm is the unconditioned default");
+  // The husk-retry re-enters review-round (via capture-head, which re-captures the round-entry head)
+  // WITHOUT going through the round-incrementing review wait, so it re-runs the SAME round rather than
+  // advancing the counter. capture-head owns f_huskRetry; review-round is entered from f_capture.
+  const captureHead = flat.match(/<bpmn:serviceTask\b[^>]*\bid="capture-head"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(captureHead, "capture-head task missing");
+  assertStringIncludes(captureHead[0], "<bpmn:incoming>f_huskRetry</bpmn:incoming>");
+  const reviewRound = flat.match(/<bpmn:serviceTask\b[^>]*\bid="review-round"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(reviewRound, "review-round task missing");
+  assertStringIncludes(reviewRound[0], "<bpmn:incoming>f_capture</bpmn:incoming>");
+});
+
+test("capture-head runs BEFORE review-round on EVERY round entry (round-entry head baseline, #786/#789)", () => {
+  // The categorical fix for the no-baseline husk: `pr.capture-head` records the head into
+  // `roundEntryHead` immediately before `review-round` on ALL four entry paths (Start, review-loop
+  // re-enter, human-answer resume, husk auto-retry), so progress-check always has a within-round
+  // baseline. This guards the structural invariant that no path reaches review-round without first
+  // passing through capture-head.
+  const capture = flat.match(/<bpmn:serviceTask\b[^>]*\bid="capture-head"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(capture, "capture-head task missing");
+  assertStringIncludes(capture[0], 'type="pr.capture-head"');
+  // All four round-entry flows target capture-head, not review-round.
+  for (const [id, src] of [
+    ["f_start", "Start"],
+    ["f_reviewLoop", "wait-review"],
+    ["f_answerLoop", "record-answer"],
+    ["f_huskRetry", "gw-husk"],
+  ] as const) {
+    const f = flowElement(id);
+    assert(f, `${id} flow missing`);
+    assertStringIncludes(f, `sourceRef="${src}"`);
+    assertStringIncludes(f, 'targetRef="capture-head"');
+    assertStringIncludes(capture[0], `<bpmn:incoming>${id}</bpmn:incoming>`);
+  }
+  // capture-head's single outgoing is the ONLY way into review-round.
+  const cap = flowElement("f_capture");
+  assert(cap, "f_capture flow missing");
+  assertStringIncludes(cap, 'sourceRef="capture-head"');
+  assertStringIncludes(cap, 'targetRef="review-round"');
+  assertStringIncludes(capture[0], "<bpmn:outgoing>f_capture</bpmn:outgoing>");
+  const reviewRound = flat.match(/<bpmn:serviceTask\b[^>]*\bid="review-round"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(reviewRound, "review-round task missing");
+  assertStringIncludes(reviewRound[0], "<bpmn:incoming>f_capture</bpmn:incoming>");
+  // review-round is entered ONLY via f_capture — no direct round-entry flow survives.
+  for (const id of ["f_start", "f_reviewLoop", "f_answerLoop", "f_huskRetry"]) {
+    assert(!reviewRound[0].includes(`<bpmn:incoming>${id}</bpmn:incoming>`), `review-round must not still take ${id} directly`);
+  }
+});
+
+test("record-answer resets huskRetries on every human resume (Copilot #789)", () => {
+  // #789 worker.ts:172: `huskRetries` is a process variable bounding the husk auto-retry chain. Every
+  // escalation resume funnels through the SINGLE chokepoint gw-escalated → wait-answer → record-answer
+  // → review-round, so record-answer must reset the counter to 0 — otherwise a fresh review attempt
+  // after a human intervention inherits a `huskRetries` a prior escalation left at MAX and the next
+  // husk escalates immediately with no self-heal. Scoping the reset here bounds the counter to one
+  // uninterrupted husk-retry chain.
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="record-answer"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "record-answer task missing");
+  assertStringIncludes(task[0], 'source="=0"');
+  assertStringIncludes(task[0], 'target="huskRetries"');
+  // record-answer is the loop-back into review-round via capture-head (the human-resume chokepoint
+  // the reset guards); capture-head re-captures the round-entry head before the re-run.
+  assertStringIncludes(task[0], "<bpmn:outgoing>f_answerLoop</bpmn:outgoing>");
+  const loop = flowElement("f_answerLoop");
+  assert(loop, "f_answerLoop flow missing");
+  assertStringIncludes(loop, 'sourceRef="record-answer"');
+  assertStringIncludes(loop, 'targetRef="capture-head"');
+});
+
+test("gw-progress default (progress) arm routes to the round-cap guard, then the review wait", () => {
+  // After #786/#789 the round-cap guard (gw-guard) moved DOWNSTREAM of progress classification: a
+  // progressing round routes gw-progress → gw-guard → (round<max) gw-review-wait, so the round cap
+  // gates the NEXT review round only. A husk auto-retry (gw-husk → capture-head) therefore bypasses
+  // the cap entirely — a dead-worker husk is re-tried onto a healthy worker even on the final round.
   const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-progress"[^>]*>/);
   assert(gw, "gw-progress gateway missing");
   assertStringIncludes(gw[0], 'default="f_progressOk"');
   const ok = flowElement("f_progressOk");
   assert(ok, "f_progressOk flow missing");
-  assertStringIncludes(ok, 'targetRef="gw-review-wait"');
+  assertStringIncludes(ok, 'targetRef="gw-guard"');
   assert(!/conditionExpression/.test(ok), "the default arm must carry no conditionExpression");
+  // The guard's continue arm (not the max-rounds arm) is what re-enters the review wait.
+  const guardOk = flowElement("f_guardOk");
+  assert(guardOk, "f_guardOk flow missing");
+  assertStringIncludes(guardOk, 'sourceRef="gw-guard"');
+  assertStringIncludes(guardOk, 'targetRef="gw-review-wait"');
+  assert(!/conditionExpression/.test(guardOk), "the guard continue arm is the default (no condition)");
+});
+
+test("the round-cap guard is downstream of progress classification, so a husk auto-retry bypasses it (#786/#789)", () => {
+  // gw-guard is fed ONLY by the progress arm (f_progressOk), NOT by the addressed/waiting status
+  // arms — those now go straight to persist-round. This is the structural guarantee that a husk on
+  // the final configured round still reaches gw-husk and gets its bounded retries, instead of being
+  // escalated as "max rounds" before it is ever classified.
+  const guard = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-guard"[^>]*>[\s\S]*?<\/bpmn:exclusiveGateway>/);
+  assert(guard, "gw-guard gateway missing");
+  assertStringIncludes(guard[0], "<bpmn:incoming>f_progressOk</bpmn:incoming>");
+  for (const id of ["f_addressed", "f_waiting", "f_escReenter"]) {
+    assert(!guard[0].includes(`<bpmn:incoming>${id}</bpmn:incoming>`), `gw-guard must not sit before progress classification (still takes ${id})`);
+  }
+  // The max-rounds arm still fires on the round cap, but only AFTER a progressing round.
+  const max = flowElement("f_guardMax");
+  assert(max, "f_guardMax flow missing");
+  assertStringIncludes(max, 'sourceRef="gw-guard"');
+  assertStringIncludes(max, 'targetRef="persist-escalation-maxrounds"');
+  assertStringIncludes(max, "round &gt;= maxRounds");
+  // The husk retry re-enters via capture-head, never touching gw-guard.
+  const retry = flowElement("f_huskRetry");
+  assert(retry, "f_huskRetry flow missing");
+  assertStringIncludes(retry, 'targetRef="capture-head"');
+  // The addressed/waiting status arms feed persist-round directly (not the guard).
+  for (const id of ["f_addressed", "f_waiting"]) {
+    const f = flowElement(id);
+    assert(f, `${id} flow missing`);
+    assertStringIncludes(f, 'targetRef="persist-round"');
+  }
 });
 
 test("the no-progress escalation routes through gw-escalated toward the human wait-answer task", () => {
@@ -230,3 +866,89 @@ test("the no-progress escalation routes through gw-escalated toward the human wa
   // It must NOT double-record the round persist-round already recorded.
   assertStringIncludes(task[0], 'target="recordRound"');
 });
+
+// ── makeDefaultReadHead: the real head reader's branch-ref-over-stale-head.sha preference ─────────
+// #786 regression guard: the handler tests inject `readHead`, and app/github.test.ts exercises
+// fetchBranchHead in isolation, so nothing pinned the DEFAULT reader's wiring — a change that stopped
+// reading the branch ref, or fell back to the PR object's denormalized head.sha, would leave the
+// suite green. These drive makeDefaultReadHead with injected fetchers to lock that contract.
+async function makeReader(deps: {
+  fetchPrHead: (repo: string, n: number | string, token: string) => Promise<{ headRef: string | null; headSha: string | null; baseRef: string | null; headRepo: string | null } | null>;
+  fetchBranchHead: (repo: string, branch: string, token: string) => Promise<string | null>;
+}) {
+  const { makeDefaultReadHead } = await import("../workers/progress-check/worker.ts");
+  return makeDefaultReadHead(deps as any);
+}
+
+test("makeDefaultReadHead: prefers the atomic branch ref over a stale PR head.sha", async () => {
+  let branchReads = 0;
+  const read = await makeReader({
+    fetchPrHead: async () => ({ headRef: "feat/x", headSha: "stale-denormalized-sha", baseRef: "main", headRepo: "o/r" }),
+    fetchBranchHead: async (_r, branch) => {
+      branchReads++;
+      assertEquals(branch, "feat/x", "the branch ref read targets the PR's head ref");
+      return "fresh-atomic-sha";
+    },
+  });
+  assertEquals(await read("o/r", 1), "fresh-atomic-sha", "the branch ref SHA wins over the stale head.sha");
+  assertEquals(branchReads, 1, "the branch ref was actually consulted");
+});
+
+test("makeDefaultReadHead: a failed branch-ref read fails OPEN to null, never falling back to head.sha", async () => {
+  const read = await makeReader({
+    fetchPrHead: async () => ({ headRef: "feat/x", headSha: "stale-sha", baseRef: "main", headRepo: "o/r" }),
+    fetchBranchHead: async () => {
+      throw new Error("ref 404 / transport hiccup");
+    },
+  });
+  assertEquals(await read("o/r", 1), null, "a ref-read failure must not fall back to the denormalized head.sha");
+});
+
+test("makeDefaultReadHead: with NO head ref (e.g. detached) falls back to the PR head.sha", async () => {
+  let branchReads = 0;
+  const read = await makeReader({
+    fetchPrHead: async () => ({ headRef: null, headSha: "only-head-sha", baseRef: "main", headRepo: "o/r" }),
+    fetchBranchHead: async () => {
+      branchReads++;
+      return "unused";
+    },
+  });
+  assertEquals(await read("o/r", 1), "only-head-sha", "with no head ref the PR head.sha is the only signal");
+  assertEquals(branchReads, 0, "the branch ref is not read when there is no head ref");
+});
+
+test("makeDefaultReadHead: an unreadable PR (null) fails OPEN to null", async () => {
+  const read = await makeReader({
+    fetchPrHead: async () => null,
+    fetchBranchHead: async () => "never",
+  });
+  assertEquals(await read("o/r", 1), null, "a null PR read fails open (the guard treats null as continue)");
+});
+
+test("makeDefaultReadHead: a fork PR reads the FORK repo's ref, not the (colliding) base-repo ref (#786)", async () => {
+  // A cross-repo PR whose head branch shares a name with a base-repo branch: querying the base repo
+  // would read the unrelated base-branch SHA. The reader must target the head branch's OWNING repo.
+  const queried: Array<{ repo: string; branch: string }> = [];
+  const read = await makeReader({
+    fetchPrHead: async () => ({ headRef: "feat/x", headSha: "sha", baseRef: "main", headRepo: "fork-owner/r" }),
+    fetchBranchHead: async (repo, branch) => {
+      queried.push({ repo, branch });
+      return repo === "fork-owner/r" ? "fork-head-sha" : "unrelated-base-sha";
+    },
+  });
+  assertEquals(await read("base-owner/r", 1), "fork-head-sha", "the head ref is resolved in the fork, not the base repo");
+  assertEquals(queried, [{ repo: "fork-owner/r", branch: "feat/x" }], "the branch ref read targets the fork repository");
+});
+
+test("makeDefaultReadHead: an unresolvable head repository (deleted fork) fails OPEN to null (#786)", async () => {
+  let branchReads = 0;
+  const read = await makeReader({
+    fetchPrHead: async () => ({ headRef: "feat/x", headSha: "sha", baseRef: "main", headRepo: null }),
+    fetchBranchHead: async () => {
+      branchReads++;
+      return "never";
+    },
+  });
+  assertEquals(await read("o/r", 1), null, "a null head repo fails open rather than falling back to the base repo");
+  assertEquals(branchReads, 0, "no base-repo branch read is attempted when the head repo is unresolvable");
+});