@nanobpm/nano-workforce 0.187.3 → 0.187.5

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.187.5](https://github.com/nanobpm/nano-workforce/compare/v0.187.4...v0.187.5) (2026-09-15)
+
+### Bug Fixes
+
+* **convergence:** classify husked review rounds and bound-retry the no-progress loop ([#789](https://github.com/nanobpm/nano-workforce/issues/789)) ([faebcdc](https://github.com/nanobpm/nano-workforce/commit/faebcdcaca017fab8d7436a50e3dc09354dc3022)), closes [jwulf/c8ctl-plugin-nano#230](https://github.com/jwulf/c8ctl-plugin-nano/issues/230) [#786](https://github.com/nanobpm/nano-workforce/issues/786) [#786](https://github.com/nanobpm/nano-workforce/issues/786)
+
+## [0.187.4](https://github.com/nanobpm/nano-workforce/compare/v0.187.3...v0.187.4) (2026-09-14)
+
+### Bug Fixes
+
+* raise default review-wait timeout to PT30M ([#792](https://github.com/nanobpm/nano-workforce/issues/792)) ([042573d](https://github.com/nanobpm/nano-workforce/commit/042573dc5e691dc97efebc12da6a63f2cf398c2a)), closes [#783](https://github.com/nanobpm/nano-workforce/issues/783) [#791](https://github.com/nanobpm/nano-workforce/issues/791)
+
 ## [0.187.3](https://github.com/nanobpm/nano-workforce/compare/v0.187.2...v0.187.3) (2026-09-14)
 
 ### Bug Fixes

package/README.md

@@ -360,7 +360,7 @@ agent at that URL to author, compile, and submit a graph unaided. See
 | `NANO_PR_MERGE_METHOD` | `squash` | merge method: `squash`, `merge`, or `rebase` |
 | `NANO_PR_MERGE_ADMIN` | `0` | pass `--admin` to override failing non-required checks (use with care) |
 | `NANO_PR_MAX_CI_FIX_ROUNDS` | `3` | max `senior:fix-ci` attempts to green a `blocked` PR before escalating; `0` disables (escalate immediately), clamped 0–20 |
-| `NANO_PR_REVIEW_WAIT_TIMEOUT` | `PT20M` | ISO-8601 duration the loop waits for a fresh review before escalating a stalled review (timer arm of the `wait-review` gateway) |
+| `NANO_PR_REVIEW_WAIT_TIMEOUT` | `PT30M` | ISO-8601 duration the loop waits for a fresh review before escalating a stalled review (timer arm of the `wait-review` gateway) |
 | `NANO_PR_REVIEW_NUDGE_MINUTES` | `5` | cooldown between the poller's automatic reviewer re-request nudges for one waiting PR (clamped 1–1440) |
 | `NANO_WORKFORCE_BASE_URL` | `http://localhost:3000` | externally-reachable base URL for the capability hooks (`/app/api/hooks/*`). Must resolve from **wherever the agent runs** — set it to the app's LAN address (or console-proxy URL) for a remote fleet. See [Fleet networking](#fleet-networking-remote-workers) |
 | `NANO_AGENTIC_SECRET` | — | enables **secure mode** for the agentic visibility channel (`/agentic`): every peer must present the **same** `NANO_AGENTIC_SECRET` value (set the identical env var on the server and every worker box — Tab A → Slot A). Unset = on-by-default **LOCAL mode** — the well-known token is honoured from **any origin** (open on the trusted LAN, matching the engine's posture); exposure is governed by the server bind address, not a shared secret. Also accepts `NANO_PR_WEBHOOK_SECRET` |

package/SPEC.md

@@ -101,11 +101,17 @@ known at submit time, carried as a process variable and stored on the DB row.
 │    <gateway: status>
 │      ├── converged  → [Mark converged] → (end: converged)
 │      │
-│      ├── addressed  → [Record round] → <event-based gateway: review ready or timeout?>
-│      │                     ├── readiness-ready (msg catch, key = prKey) → round++ ─┐
-│      │                     └── =reviewWaitTimeout (timer catch)                     │
-│      │                          → [Escalate: review stalled] (blocked)              │
-│      │                          → [Wait: wait-answer userTask] ─────────────────────┤
+│      ├── addressed  → [Record round] → [Check progress] (did the PR head advance?)
+│      │                   ├── progressed → <guard: round ≥ maxRounds → escalate "not converged"> │
+│      │                   │                   → <event-based gateway: review ready or timeout?>   │
+│      │                   │      ├── readiness-ready (msg catch, key = prKey) → round++ ─┐
+│      │                   │      └── =reviewWaitTimeout (timer catch)                    │
+│      │                   │           → [Escalate: review stalled] (blocked)             │
+│      │                   │           → [Wait: wait-answer userTask] ────────────────────┤
+│      │                   └── no progress → <husk? no commit AND no terminal instance>   │
+│      │                          ├── husk & retries < MAX → re-enter [Review round] (bypasses the round-cap guard) │
+│      │                          └── no-advance / husk cap → [Escalate: no progress]      │
+│      │                                     → [Wait: wait-answer userTask] ───────────────────┤
 │      │                                                                             │
 │      └── needs_input     [Record escalation]                       │               │
 │          or blocked  →   (kind = question | blocker)               │               │
@@ -124,8 +130,11 @@ step, then retry the same round with the human's `answer`. They differ only by e
 which the UI uses to label the card. Neither ends the run — a human always gets
 a chance to unblock and resume.
 
-Guard: before each Review round, if round > MAX_ROUNDS → force an escalation
-("not converged after N rounds") so a human decides, rather than looping forever.
+Guard: after progress classification, a **progressing** round with round ≥
+MAX_ROUNDS forces an escalation ("not converged after N rounds") so a human
+decides rather than looping forever. The guard sits *after* `check-progress`
+(not before), so a husk auto-retry — which does not consume a round — bypasses
+the cap and is re-tried onto a healthy worker even on the final configured round.
 ```
 
 Notes:
@@ -133,7 +142,7 @@ Notes:
   canonical `readiness-ready` wait-gate message (ADR 0001 §2; correlated by the
   poller when a fresh review lands)
   against a `=reviewWaitTimeout` timer (seeded at submit from
-  `NANO_PR_REVIEW_WAIT_TIMEOUT`, default `PT20M`). Whichever fires first
+  `NANO_PR_REVIEW_WAIT_TIMEOUT`, default `PT30M`). Whichever fires first
   withdraws the other — the message arm advances `round`, the timer arm escalates
   a **stalled review** (`blocked`) so a human decides rather than the instance
   hanging forever. Because `persist-round` already recorded this `round` as
@@ -149,6 +158,59 @@ Notes:
   backstop when even repeated nudges fail.
 - On `needs_input`, the same `round` is retried after the answer (the answer is
   added to the agent's context; the round number does not advance).
+- **No-progress guard + husk classification (issue #786).** Before the review
+  wait, an `addressed` round passes through `pr.progress-check`
+  (`workers/progress-check/worker.ts`, mirrored by `app/roundProgress.ts`): it
+  reads the PR's current head SHA (the branch ref, atomic with the push) and
+  compares it to the **round-entry head** — the head captured by `pr.capture-head`
+  immediately BEFORE `review-round` ran this round, published as the
+  `roundEntryHead` process variable. `pr.capture-head` sits on EVERY entry into
+  `review-round` (the first round from `Start`, a review-loop re-enter, a
+  human-answer resume, and a husk auto-retry), so within any round there is always
+  a baseline captured against the agent's own starting point — closing the
+  no-baseline gap where a FIRST addressed round had no prior-round head to compare
+  against (and either waved a first-round husk through as progress, or risked
+  mis-escalating a straggler push). If `roundEntryHead` is absent — an older
+  in-flight instance whose flow predates `capture-head`, or a capture read that
+  failed open (it publishes the empty string as its "unknown" sentinel) —
+  progress-check falls back to the head persisted from the previous round
+  (`last_round_head`). A round whose head DID advance past the round-entry baseline
+  is real progress and continues to the review-wait gateway. A round whose head did
+  NOT advance pushed no commit, so re-requesting a review would loop on
+  byte-identical code; `gw-progress` routes it to `gw-husk`, which SPLITS it on a
+  corroboration correlated to the COMPLETING `review-round` element-instance (NOT
+  an aggregate terminal count — a same-round human-answered resume is classified on
+  its own fresh attempt):
+    - a **husk** — no commit AND the completing `review-round` attempt is
+      NON-TERMINAL (the producer harness died mid-run, leaving a stuck instance) —
+      is auto-re-run onto a healthy worker up to `MAX_HUSK_RETRIES` (2) before
+      escalating; and
+    - a **no-advance** — the completing attempt ran to a terminal instance but
+      nothing was pushed — (and a husk that exhausts its retries) escalates to the
+      human `wait-answer` task.
+  The agent-instance read is AVAILABILITY-AWARE via a **two-tier probe** and fails
+  SAFE (ADR 0056). `review-round` is an external-agent service task, so a job that
+  husks BEFORE it ever registers an AgentInstance leaves the scoped `review-round`
+  search EMPTY — indistinguishable, on that query alone, from an engine that has no
+  AgentInstance projection at all. The probe therefore resolves an empty
+  `review-round` search against a SECOND, process-wide read:
+    - if the process-wide read also finds NO instance, the **channel is absent**
+      (an engine with no AgentInstance projection) — UNKNOWN, treated as no-advance,
+      never an auto-retry that could duplicate genuinely-completed work;
+    - if the process-wide read finds ANOTHER instance (from `classify-scope`, an
+      earlier round, etc.), the **channel is PRESENT** but this round registered
+      nothing — a genuine **pre-registration husk**, so it is classified as a husk
+      and auto-retried.
+  A head that cannot be read fails OPEN (continue), so a transient GitHub hiccup
+  never fabricates a no-progress escalation. Two supporting invariants keep an
+  auto-retry clean: `pr.persist-round`
+  records a round IDEMPOTENTLY on `(pr_key, round_no, process_instance_key)` — a husk
+  retry (same process instance) updates its row in place, while a resubmission that
+  re-opens the PR at round 1 in a NEW process instance inserts a fresh row and so
+  never clobbers a prior run's durable round history (migration 102) — and the guard flips the PR back to
+  the running `converging` status before a retry re-enters `review-round` so the
+  poller does not solicit a spurious review against the still-running round. The
+  round cap and the review-wait timeout remain the outer safety nets.
 
 
 ## 5. Agent job contract (`senior:pr-review`)
@@ -544,7 +606,7 @@ queries skip (`merging`), so a slow pass can't double-signal.
 | `NANO_PR_AUTO_MERGE` | 1 | run the merge stage after convergence (`0` = review-only; per-submit `convergeOnly: true` override) |
 | `NANO_PR_MERGE_METHOD` | squash | `squash` \| `merge` \| `rebase` |
 | `NANO_PR_MERGE_ADMIN` | 0 | pass `--admin` on merge |
-| `NANO_PR_REVIEW_WAIT_TIMEOUT` | PT20M | ISO-8601 wait before a stalled review escalates (timer arm of the `wait-review` event-based gateway); malformed → default |
+| `NANO_PR_REVIEW_WAIT_TIMEOUT` | PT30M | ISO-8601 wait before a stalled review escalates (timer arm of the `wait-review` event-based gateway); malformed → default |
 | `NANO_PR_REVIEW_NUDGE_MINUTES` | 5 | cooldown between poller Copilot re-request nudges per PR (clamped 1–1440) |
 
 ## 13. Planning fan-out (`plan-fanout.bpmn`) — issue #14

package/app/contracts.ts

@@ -145,6 +145,7 @@ export const ENV_CONTRACTS = {
     name: "NANO_PR_REVIEW_WAIT_TIMEOUT",
     owner: "app/service.ts",
     semantics: "How long to wait for a review before nudging/escalating (FEEL/ISO-8601 duration).",
+    default: "PT30M",
   },
   NANO_PR_REVIEW_NUDGE_MINUTES: {
     category: "env",

package/app/convergenceEscalationGuard.test.ts

@@ -19,7 +19,8 @@
 //
 // The fix (mirroring the merge loop's `gw-merge-escalated`, PR #331): route EVERY arm that can reach
 // `wait-answer` through the single `gw-escalated` guard, so a `persist-escalation` returning
-// `escalated:false` RE-ENTERS the loop (`gw-guard`) instead of parking a dead wait. This makes the
+// `escalated:false` RE-ENTERS the loop (round processing, `persist-round`) instead of parking a dead
+// wait. This makes the
 // invariant structural — `wait-answer` is reachable ONLY from a `gw-escalated == true` edge, so a
 // "durable answer-wait with no escalation" is unrepresentable.
 //
@@ -77,7 +78,7 @@ test("gw-escalated honours persist-escalation's escalated output for every arm",
   assertStringIncludes(escWait![0], "escalated = true", "the wait arm must be guarded by escalated = true");
   // escalated:false (a non-escalation, e.g. a blank convergeBlockReason) → re-enter the loop, not a dead wait.
   assert(gatewayDefault("gw-escalated", "f_escReenter"), "gw-escalated default must re-enter the loop");
-  assert(flowHasId("f_escReenter", "gw-escalated", "gw-guard"), "the non-escalation arm must re-enter via gw-guard, not park a wait");
+  assert(flowHasId("f_escReenter", "gw-escalated", "persist-round"), "the non-escalation arm must re-enter round processing (persist-round), not park a wait");
 });
 
 test("wait-answer is reachable ONLY from the gw-escalated == true edge (structural invariant)", () => {

package/app/github.test.ts

@@ -3,7 +3,7 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError, listPrsForHead, type Mergeability, type PrState } from "./github.ts";
+import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, isNotAPullRequestError, listPrsForHead, type Mergeability, type PrState } from "./github.ts";
 import { DEFAULT_MERGE_PROTOCOL, type MergeProtocol, type RequiredCheck } from "./mergeProtocol.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
@@ -723,3 +723,127 @@ test("checkConclusions: in-flight runs map to '' for both CheckRun and StatusCon
     "legacy-error": "ERROR",
   });
 });
+
+// ── fetchBranchHead — the atomic branch-ref reader (issue #786) ──────────────
+//
+// The no-progress guard reads the branch ref (git/ref/heads/<branch>), updated ATOMICALLY with the
+// push, rather than the PR object's asynchronously-denormalized head.sha, so a lagging PR projection
+// can never fabricate a stale-but-valid no-advance escalation. Force the token transport and stub
+// `globalThis.fetch` to serve the git-ref endpoint.
+async function withRefFetch<T>(
+  serve: (path: string) => { status: number; body: unknown },
+  fn: () => Promise<T>,
+): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = ((url: string | URL | Request): Promise<Response> => {
+    const path = new URL(String(url)).pathname.replace(/^\/repos\//, "");
+    const { status, body } = serve(path);
+    return Promise.resolve(new Response(JSON.stringify(body), { status }));
+  }) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+test("fetchBranchHead: returns the branch ref's atomic head SHA", async () => {
+  const sha = await withRefFetch(
+    (path) => {
+      assertEquals(path, "o/r/git/ref/heads/feat/x");
+      return { status: 200, body: { object: { sha: "deadbeef" } } };
+    },
+    () => fetchBranchHead("o/r", "feat/x", "tok"),
+  );
+  assertEquals(sha, "deadbeef");
+});
+
+test("fetchBranchHead: a 404 (branch absent) resolves to null, never throws", async () => {
+  const sha = await withRefFetch(
+    () => ({ status: 404, body: { message: "Not Found" } }),
+    () => fetchBranchHead("o/r", "feat/missing", "tok"),
+  );
+  assertEquals(sha, null);
+});
+
+test("fetchBranchHead: no usable transport (token mode, empty token) resolves to null, never throws", async () => {
+  // The documented contract promises `null` when no transport is usable, matching fetchPrHead /
+  // fetchPrBase — a missing token under the token transport must not surface an exception to callers
+  // relying on the Promise<string | null> shape.
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  try {
+    const sha = await fetchBranchHead("o/r", "feat/x", "");
+    assertEquals(sha, null);
+  } finally {
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+});
+
+// ── fetchPrHead — the PR head reader surfaces the head branch's OWNING repo (issue #786) ─────
+//
+// The no-progress head reader resolves the head ref in `headRepo`, so a cross-repo (fork) PR reads
+// the fork's ref, not a same-named branch in the base repo (which would resolve to an unrelated
+// SHA). These assert the transport-level mapping of the source repository through `fetchPrHead`'s
+// REST branch (forced via the token transport), which the handler-level tests — injecting an
+// already-parsed `{ headRepo }` — do not exercise.
+test("fetchPrHead: REST maps head.repo.full_name to the fork's source repository", async () => {
+  const head = await withRefFetch(
+    (path) => {
+      assertEquals(path, "base/repo/pulls/789");
+      return {
+        status: 200,
+        body: {
+          head: { ref: "feat/x", sha: "cafef00d", repo: { full_name: "fork-owner/repo" } },
+          base: { ref: "main" },
+        },
+      };
+    },
+    () => fetchPrHead("base/repo", 789, "tok"),
+  );
+  assertEquals(head, { headRef: "feat/x", headSha: "cafef00d", baseRef: "main", headRepo: "fork-owner/repo" });
+});
+
+test("fetchPrHead: REST fails open to headRepo=null when the head repo is absent (deleted fork)", async () => {
+  const head = await withRefFetch(
+    () => ({
+      status: 200,
+      body: { head: { ref: "feat/x", sha: "cafef00d", repo: null }, base: { ref: "main" } },
+    }),
+    () => fetchPrHead("base/repo", 789, "tok"),
+  );
+  // A null head repo must surface as headRepo=null (the reader then fails open), never the base repo.
+  assertEquals(head?.headRepo, null);
+});
+
+test("fetchPrHead: no usable transport (token mode, empty token) resolves to null, never throws", async () => {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  try {
+    const head = await fetchPrHead("o/r", 1, "");
+    assertEquals(head, null);
+  } finally {
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+});
+
+// A branch name may legally contain `#`, `?`, or spaces. The reader must percent-encode each ref
+// SEGMENT (preserving `/`) before building the API path/URL — otherwise a `#` starts a URL fragment,
+// the path is truncated to the wrong ref, and the no-progress guard fails open (issue #786).
+test("fetchBranchHead: percent-encodes a special-character branch ref (preserving '/')", async () => {
+  const sha = await withRefFetch(
+    (path) => {
+      // The `#` must survive as %23 inside the path, not truncate it into a URL fragment.
+      assertEquals(path, "o/r/git/ref/heads/feat/x%23123");
+      return { status: 200, body: { object: { sha: "cafef00d" } } };
+    },
+    () => fetchBranchHead("o/r", "feat/x#123", "tok"),
+  );
+  assertEquals(sha, "cafef00d");
+});

package/app/github.ts

@@ -1067,17 +1067,25 @@ export async function fetchPrFiles(
   return paths;
 }
 
-/** The PR head ref/sha for D3's trial-merge gate. `null` when no transport is usable. */
+/** The PR head ref/sha for D3's trial-merge gate. `null` when no transport is usable. `headRepo` is
+ * the head branch's OWNING repository as `owner/repo` — the FORK for a cross-repo PR, else the base
+ * repo — so a caller that resolves the head ref (e.g. the no-progress head reader, #786) queries the
+ * repository the head branch actually lives in, not the base repo (where a same-named branch would
+ * resolve to an unrelated SHA). `null` when the head repository cannot be resolved (e.g. a deleted
+ * fork). */
 export async function fetchPrHead(
   repo: string,
   number: number | string,
   token: string,
-): Promise<{ headRef: string | null; headSha: string | null; baseRef: string | null } | null> {
+): Promise<{ headRef: string | null; headSha: string | null; baseRef: string | null; headRepo: string | null } | null> {
   if (await useGh()) {
-    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "headRefName,headRefOid,baseRefName"]);
+    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "headRefName,headRefOid,baseRefName,headRepository,headRepositoryOwner"]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    const j = JSON.parse(out) as { headRefName?: string | null; headRefOid?: string | null; baseRefName?: string | null };
-    return { headRef: j.headRefName ?? null, headSha: j.headRefOid ?? null, baseRef: j.baseRefName ?? null };
+    const j = JSON.parse(out) as { headRefName?: string | null; headRefOid?: string | null; baseRefName?: string | null; headRepository?: { name?: string | null } | null; headRepositoryOwner?: { login?: string | null } | null };
+    const owner = j.headRepositoryOwner?.login;
+    const name = j.headRepository?.name;
+    const headRepo = owner && name ? `${owner}/${name}` : null;
+    return { headRef: j.headRefName ?? null, headSha: j.headRefOid ?? null, baseRef: j.baseRefName ?? null, headRepo };
   }
   if (!token) return null;
   const r = await fetch(`https://api.github.com/repos/${repo}/pulls/${number}`, {
@@ -1085,8 +1093,29 @@ export async function fetchPrHead(
   });
   if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
   // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const j = (await r.json()) as { head?: { ref?: string | null; sha?: string | null }; base?: { ref?: string | null } };
-  return { headRef: j.head?.ref ?? null, headSha: j.head?.sha ?? null, baseRef: j.base?.ref ?? null };
+  const j = (await r.json()) as { head?: { ref?: string | null; sha?: string | null; repo?: { full_name?: string | null } | null }; base?: { ref?: string | null } };
+  return { headRef: j.head?.ref ?? null, headSha: j.head?.sha ?? null, baseRef: j.base?.ref ?? null, headRepo: j.head?.repo?.full_name ?? null };
+}
+
+/** The head commit SHA of `branch` on `repo`, read from the git-ref endpoint
+ * (`git/ref/heads/<branch>`) — the ref that GitHub updates ATOMICALLY with the push, unlike a PR
+ * object's `head.sha`, which is an asynchronously-denormalized projection that can briefly report a
+ * stale-but-valid SHA after a push. The no-progress guard (#786) reads this in preference to the PR
+ * head so a lagging PR denormalization can never fabricate a no-advance escalation. `null` when the
+ * branch does not exist (a 404) or no transport is usable; throws only on a genuine transport
+ * failure. */
+export async function fetchBranchHead(
+  repo: string,
+  branch: string,
+  token: string,
+): Promise<string | null> {
+  // Honor the documented no-transport contract at this public boundary, exactly like the sibling
+  // readers `fetchPrHead`/`fetchPrBase`: with no `gh` CLI and no token there is no usable transport,
+  // which is the idle "unknown" case → `null`, NOT an exception. The internal `branchHeadSha` still
+  // throws in that case for `ensureBaseBranch`'s callers, which treat a missing transport as a hard
+  // failure; this wrapper's `Promise<string | null>` contract promises `null` instead.
+  if (!(await useGh()) && !token) return null;
+  return branchHeadSha(repo, branch, token);
 }
 
 /** The PR's current base branch ref — the branch this PR would land *into*. `null` when no
@@ -1483,7 +1512,13 @@ function isEpicBranch(branch: string): boolean {
 /** Resolve the head commit SHA of `branch` on `repo`, or `null` when the branch does not exist
  * (a 404 from the git-ref endpoint). Throws only on a genuine transport failure. */
 async function branchHeadSha(repo: string, branch: string, token: string): Promise<string | null> {
-  const apiPath = `repos/${repo}/git/ref/heads/${branch}`;
+  // Percent-encode each ref SEGMENT (git permits `#`, `?`, spaces, etc. in a branch name) while
+  // preserving the `/` separators that git uses for hierarchical refs (`feat/x`). Interpolating the
+  // raw name would, in the direct `fetch` URL, let a `#` start a fragment (and `?` a query) — the
+  // path is truncated, the wrong ref (or a 404) is read, and the no-progress guard fails open. gh
+  // api receives the same already-encoded path.
+  const encodedBranch = branch.split("/").map(encodeURIComponent).join("/");
+  const apiPath = `repos/${repo}/git/ref/heads/${encodedBranch}`;
   if (await useGh()) {
     try {
       const out = await runGh(["api", apiPath]);

package/app/persist-escalation.test.ts

@@ -4,8 +4,9 @@
 // `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.
+// escalation. After #786/#789 the max-rounds arm ALSO runs after `persist-round` (the round-cap
+// guard moved downstream of progress classification) and likewise passes `recordRound=false`; an
+// agent-raised arm with no prior round row omits the flag and must still record the round.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import handler from "../workers/persist-escalation/worker.ts";
@@ -49,9 +50,9 @@ test("stalled arm (recordRound=false) does not insert a duplicate rounds row", a
   assertEquals((out as any).escalationId, 42);
 });
 
-test("escalation arm without the flag still records the round", async () => {
+test("an agent-raised 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" } };
+  const job = { variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "needs input" } };
   await handler(job as any, app as any);
   assertEquals(inserts.rounds.length, 1);
   assertEquals((inserts.rounds[0] as any).round_no, 3);
@@ -183,14 +184,15 @@ test("persist-escalation heals from the prKey when repo/prNumber are absent", as
 
 // #333 — the control-flow escalation arms (no-progress / review-stalled / unaddressed-comments /
 // max-rounds) each set an explicit `status="blocked"` + a concrete `question` via `zeebe:input`
-// (recordRound=false for the three that run after `persist-round`). They now route through
+// (recordRound=false on every arm that runs after `persist-round` — which, after #786/#789 moved the
+// round-cap guard downstream of progress classification, now INCLUDES max-rounds). They route through
 // `gw-escalated`, which branches on the worker's `escalated` output. This pins the contract that
 // gateway depends on: a control-flow arm with a real question OPENS an escalation and returns
 // `escalated:true` + the (trimmed) question, so gw-escalated parks a wait carrying that question —
 // never a dead wait with a null question (the #333 defect).
 test("a control-flow arm with a concrete question opens an escalation gw-escalated can park", async () => {
   const { app, inserts } = fakeApp();
-  const question = "No review arrived within the review-wait timeout (PT20M). A human must decide how to proceed.";
+  const question = "No review arrived within the review-wait timeout (PT30M). A human must decide how to proceed.";
   const job = { variables: { prKey: "o/r#5", round: 2, status: "blocked", question, recordRound: false } };
   const out = await handler(job as any, app as any);
   assertEquals((out as any).escalated, true, "a real control-flow escalation reports escalated:true");