@nanobpm/nano-workforce 0.200.8 → 0.201.0

package/app/roundChurn.ts

@@ -0,0 +1,265 @@
+// Non-converging churn guard — the canonical, testable detector the `pr.progress-check` worker uses
+// to escalate a review loop that is making head-advancing "progress" every round yet never reaches a
+// fixed point (issue #870).
+//
+// The no-progress guard in app/roundProgress.ts catches the OTHER failure mode: an `addressed` round
+// whose PR head did NOT advance (no commit pushed). Churn is the opposite shape — EVERY round pushes
+// a commit, so the head advances and `routeProgress` legitimately returns `continue`, round after
+// round. The trap is that the findings never end: a contested surface (e.g. a fail-closed static
+// analyzer whose bypass forms are unbounded) keeps producing 1–3 new findings in the SAME file,
+// the review agent patches them, the patch adds more surface for the next review, and the loop runs
+// to `maxRounds` (or forever) without a human ever being asked to make the scope call.
+//
+// This detector reads the durable `rounds` history and reports churn when the trailing run of
+// consecutive `addressed` rounds keeps landing findings in the SAME file(s) over a window of rounds.
+// It is deliberately conservative — it requires the SAME file to appear in EVERY round of the window
+// — so normal multi-round convergence (findings in different areas, trending down) is never escalated
+// early. When it fires, the worker routes the round to the SAME human escalation path the no-advance
+// guard uses (gw-husk → persist-escalation-noprogress), carrying an actionable scope question.
+import { isAddressedStatus } from "./roundProgress.ts";
+
+/** How many CONSECUTIVE `addressed` rounds must all land findings in the same file before the loop is
+ * declared non-converging and escalated for a human scope decision. Four matches the issue's
+ * suggested threshold (#870) — long enough that a legitimately-converging loop whose findings move
+ * between areas never reaches it, short enough to catch a stuck surface well below a high `maxRounds`
+ * cap. */
+export const CHURN_WINDOW = 4;
+
+/** One recorded round, projected to just the fields churn detection reads: its number (for ordering),
+ * its `status` (to find the trailing consecutive `addressed` run), and its `summary` (the agent's
+ * round summary, the durable free-text the contested file names are mined from). */
+export interface ChurnRound {
+  readonly roundNo: number;
+  readonly status: string | null | undefined;
+  readonly summary: string | null | undefined;
+}
+
+/** The churn verdict. `churning:false` is the common case (continue the loop). When `churning:true`,
+ * `file` is the contested surface, `rounds` is how many consecutive rounds hit it, and `question` is
+ * the human-facing scope decision to carry into the escalation. */
+export interface ChurnResult {
+  readonly churning: boolean;
+  readonly file?: string;
+  readonly rounds?: number;
+  readonly question?: string;
+}
+
+// A maximal run of path characters (`\w`, plus `.@~+/-`). Splitting the summary into these runs
+// first — a single linear scan — isolates each candidate token (a non-path char like a space, comma,
+// backtick, or `:` ends a run), so the path shape below is only ever tested ANCHORED at a run's start
+// and never re-tried at every offset of the whole summary. The trailing `-` keeps that metacharacter
+// literal (a filename hyphen) rather than a range.
+const PATH_RUN_RE = /[\w.@~+/-]+/g;
+
+// The KNOWN source/config/doc/build extensions a mined file path's FINAL dotted component must be —
+// shared by BOTH the nested and root matchers below. A permissive `[A-Za-z0-9]+`/`[A-Za-z]{2,}`
+// extension mines dotted API symbols and prose as fake files — `z.object`, `object.keys`,
+// `example.com`, `schema.ts.parse` all look like `name.ext` — so four rounds that each mention the
+// same qualified symbol while fixing DIFFERENT real files would intersect on that symbol and falsely
+// escalate (Copilot review of #870). Restricting the extension to a real-file allowlist rejects those
+// (`object`, `keys`, `com`, `parse` are not file extensions) while keeping every genuine file. It is
+// fail-open in the safe direction: an exotic-but-real extension it omits (`.svelte` is listed; a
+// brand-new one is not) only ever MISSES a churn signal, never fabricates one. The allowlist contains
+// no digits or single letters, so it also excludes version strings (`4.8`), sentence-ending
+// abbreviations (`e.g`, `i.e`), and initialisms (`U.S`).
+const ROOT_FILE_EXT =
+  "(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|json|jsonc|json5|md|markdown|yml|yaml|toml|xml|html|css|scss|" +
+  "less|sql|sh|bash|zsh|py|rb|go|rs|java|kt|kts|swift|c|h|cc|hh|cpp|cxx|hpp|cs|fs|vue|svelte|php|" +
+  "pl|pm|lua|dart|ex|exs|erl|hrl|clj|cljs|scala|groovy|gradle|properties|ini|cfg|conf|config|env|" +
+  "lock|mod|sum|mk|cmake|txt|bpmn|form|dmn|proto|graphql|gql|prisma|tf|hcl)";
+
+// A NESTED repository-relative file path, ANCHORED at the start of a candidate run: one or more `dir/`
+// segments followed by a `name.ext`. Requiring at least one slash AND an extension keeps bare words
+// ("addressed", "zod") and prose out, so only genuine file references are mined. Because it is matched
+// against one bounded run (not scanned across the whole text), the inner `(?:…\/)+` backtracking on a
+// long UNTERMINATED `dir/` run (e.g. `"a/".repeat(n)` with no closing `name.ext`) is paid ONCE at a
+// single start position — linear in the run length — rather than the O(n²) a global re-scan would
+// cost, which would otherwise let an adversarial summary (a long directory listing, minified stack
+// trace, or base64/data-URI blob) stall the `pr.progress-check` worker inside the convergence loop.
+//
+// Like the root form below, the FINAL dotted component must be an allowlisted ROOT_FILE_EXT and the
+// trailing `(?![\w.@~+-])` negative lookahead refuses any following path char — crucially another
+// `.segment`. Without those, a SLASH-qualified API chain like `src/schema.ts.parse` /
+// `lib/config.json.parse` was mined WHOLE as a fake repo file: four summaries that cite that same
+// qualified symbol while fixing different real files intersect on it and falsely escalate, exactly the
+// class the root allowlist already closes (Copilot review of #870). The basename's first char is a
+// non-dot path char so a true `name.ext` anchors the stem; the greedy `[\w.@~+-]*` still lets a
+// multi-dot basename (`dir/foo.test.ts`, `lib/nano.app.json`) match whole by backtracking the LAST
+// allowlisted dot as the separator.
+const NESTED_PATH_RE = new RegExp(
+  `^(?:[\\w.@~+-]+\\/)+[\\w@~+-][\\w.@~+-]*\\.${ROOT_FILE_EXT}(?![\\w.@~+-])`,
+  "i",
+);
+
+// A ROOT-LEVEL file (no directory segment): a bare `name.ext`. Root repository files — `package.json`,
+// `README.md`, `tsconfig.json`, `nano.app.json` — are legitimate churn surfaces too, but the nested
+// form above excludes them because it REQUIRES a slash, so a loop repeatedly editing `package.json`
+// would never escalate (issue #870 follow-up). Matching a bare `name.ext` re-admits the prose that the
+// required slash kept out, so this form is deliberately STRICTER to compensate, on three axes — all
+// now shared with the nested matcher above via ROOT_FILE_EXT + the trailing lookahead:
+//
+//  1. The extension must be a KNOWN source/config/doc/build extension (ROOT_FILE_EXT above), not just
+//     "any letters" — see that constant's comment for why (`z.object`, `example.com`, `Deno.land` are
+//     rejected because `object`/`com`/`land` are not file extensions).
+//  2. The extension must still be at least two ALPHABETIC characters (the allowlist contains no digits
+//     or single letters), which keeps excluding version strings (`4.8`), sentence-ending abbreviations
+//     (`e.g`, `i.e`), and initialisms (`U.S`).
+//  3. The allowlisted extension must be the FINAL dotted component of the token. The trailing
+//     `(?![\w.@~+-])` negative lookahead refuses any following path character — crucially another
+//     `.segment` — so an API chain like `schema.ts.parse` / `config.json.parse` is NOT truncated to a
+//     fake `schema.ts` / `config.json` root file (a `\b`-only anchor succeeds before that next dot and
+//     mined the truncation, Copilot review of #870). Trailing SENTENCE punctuation is stripped from the
+//     candidate token in {@link extractFiles} BEFORE matching, so `README.md.` still mines `README.md`.
+//
+// The stem is greedy and MAY contain dots (`foo.test.ts`, `nano.app.json`): backtracking lets the LAST
+// dot be the separator so a multi-dot root file matches whole, while the allowlisted final extension
+// still anchors the match. Tried only AFTER the nested form, and like it anchored at the run start (no
+// global re-scan), so it adds no backtracking cost — it only ever ADDS real root-level files, never
+// removes a nested path the form above already mines.
+const ROOT_FILE_RE = new RegExp(`^[\\w@~+-][\\w.@~+-]*\\.${ROOT_FILE_EXT}(?![\\w.@~+-])`, "i");
+
+// A ROOT-LEVEL dotfile or extensionless basename — the churn surfaces the `name.ext` form above can
+// NEVER match because they have a leading dot and no basename (`.gitignore`, `.env`, `.editorconfig`,
+// `.gitattributes`) or no extension at all (`Dockerfile`, `Makefile`). The allowlist/comment above
+// name these as legitimate surfaces, so a loop repeatedly editing `.gitignore` must escalate too
+// (Copilot review of #870). A CLOSED allowlist of well-known basenames — not "any dotfile" — keeps the
+// match conservative (prose like "the environment" or "docker build" is never mined), and the trailing
+// `(?![\w.@~+-])` requires an EXACT whole-token match so a dotted variant (`.env.local`,
+// `Dockerfile.prod`) is left un-mined (fail-open) rather than collapsed to the base name.
+const ROOT_BASENAME_RE =
+  /^(?:\.(?:gitignore|gitattributes|editorconfig|env|dockerignore|npmrc|nvmrc|prettierrc|eslintrc|babelrc)|Dockerfile|Makefile|Rakefile|Gemfile|Procfile|Caddyfile|CODEOWNERS)(?![\w.@~+-])/i;
+
+// A whole URL span (`scheme://…host/path…`). A citation link's path (e.g.
+// `github.com/o/r/blob/main/docs/guide.md`) otherwise looks exactly like a repo-relative file, so a
+// summary that cites the SAME link every round while fixing DIFFERENT real files would false-escalate
+// as churn naming the URL as the contested file. Strip URL spans before mining so only genuine repo
+// paths remain. `\S+` is linear (no backtracking).
+const URL_RE = /\b[a-z][a-z0-9+.-]*:\/\/\S+/giu;
+
+// A SCHEME-LESS citation URL's host+path (`github.com/o/r/blob/main/docs/guide.md`), ANCHORED at a
+// candidate run's start. URL_RE only strips spans with an explicit `scheme://`; a bare `host.tld/path`
+// citation survives it and then satisfies NESTED_PATH_RE (dir segments + an allowlisted `guide.md`), so
+// four summaries that cite the SAME link while fixing DIFFERENT real files would intersect on the URL
+// and falsely escalate as churn (Copilot review of #870). A repo-relative path's FIRST segment is a
+// plain directory name — a dotfile dir (`.github/…`) has a LEADING dot (no label before it, so this
+// `(?:label\.)+` prefix can't match) and an ordinary dir (`src/…`) has no dot at all — whereas a URL
+// host is `label(.label)*.tld/`, so a leading dot-containing host segment followed by `/` reliably
+// marks a citation URL, not a file. Tested ONCE per bounded run (like NESTED_PATH_RE), the
+// `(?:[\w-]+\.)+` prefix is linear: the `\.` delimiter makes label boundaries unambiguous, so there is
+// no catastrophic backtracking even on an adversarial dotted run. REJECTING (not truncating) the whole
+// token is fail-open: the rare real path whose first directory literally contains a dot only MISSES a
+// churn signal, never fabricates one — the same safe direction the extension allowlist already favours.
+const SCHEMELESS_URL_RE = /^(?:[\w-]+\.)+[a-z]{2,}\/[\w.@~+-]/i;
+
+// Defensive cap on the free text scanned. The matcher above is linear, so this is belt-and-suspenders
+// (bounding Set growth and any unforeseen pathological input), not the primary perf guard; real round
+// summaries are far shorter, and truncating one only ever drops a churn SIGNAL (fail-open), never
+// fabricates one.
+const MAX_SCAN = 20000;
+
+/** Mine the set of distinct file paths referenced in a round summary. A non-string / empty summary
+ * yields an empty set. The summary is length-bounded and URL spans are stripped, then each maximal
+ * path-char run is tested for the path shape anchored at its start (see MAX_SCAN / URL_RE /
+ * PATH_RUN_RE / NESTED_PATH_RE / ROOT_FILE_RE / ROOT_BASENAME_RE). Each run's trailing sentence
+ * punctuation and closing brackets are stripped BEFORE matching so the same file referenced with
+ * different surrounding punctuation collapses to one key and the allowlisted extension anchors to the
+ * token end. */
+export function extractFiles(summary: string | null | undefined): Set<string> {
+  const files = new Set<string>();
+  if (typeof summary !== "string" || summary.trim() === "") return files;
+  const scanned = summary.slice(0, MAX_SCAN).replace(URL_RE, " ");
+  for (const run of scanned.matchAll(PATH_RUN_RE)) {
+    // Strip trailing sentence punctuation / closing brackets BEFORE matching: `.` is itself a path
+    // char, so a sentence-ending `README.md.` arrives in the run with its period attached. Removing it
+    // first lets the allowlisted extension anchor cleanly to the END of the token (ROOT_FILE_RE's
+    // `(?![\w.@~+-])` lookahead), instead of a `\b` that also fired before that trailing dot.
+    const token = run[0].replace(/[),.;:'"`\]]+$/u, "").trim();
+    if (token === "") continue;
+    // Reject a scheme-less citation URL (`github.com/o/r/blob/main/docs/guide.md`) before mining: its
+    // host+path otherwise looks exactly like a nested repo file (see SCHEMELESS_URL_RE). URL_RE already
+    // removed any `scheme://` span, so this closes the remaining citation-URL hole.
+    if (SCHEMELESS_URL_RE.test(token)) continue;
+    const hit = token.match(NESTED_PATH_RE) ?? token.match(ROOT_FILE_RE) ?? token.match(ROOT_BASENAME_RE);
+    if (hit === null) continue;
+    const path = hit[0].trim();
+    if (path !== "") files.add(path);
+  }
+  return files;
+}
+
+/** Build the human-facing escalation question for a churning loop, framed — per the issue — as a
+ * SCOPE decision, not a request to keep looping. The answer the human gives is threaded into the next
+ * round's context (the `answer` variable), so it must offer concrete, actionable choices. */
+export function churnQuestion(file: string, rounds: number): string {
+  return (
+    `Convergence is not converging: the last ${rounds} review rounds all reported the comments were ` +
+    `addressed, yet the findings keep landing in the same file (\`${file}\`) with no fixed point in ` +
+    `sight — a contested surface whose findings never end (e.g. a fail-closed analyzer whose bypass ` +
+    `forms are unbounded). Rather than burn more rounds, this needs a human SCOPE decision: ` +
+    `(a) narrow or simplify the contested surface in \`${file}\`; (b) defer the remaining findings ` +
+    `to a follow-up issue and accept the current state as non-blocking; or (c) accept the residual ` +
+    `findings as non-blocking and let the loop converge. Reply with the decision to resume the loop.`
+  );
+}
+
+/** Detect non-converging churn over a PR's recorded rounds.
+ *
+ * Churn = the trailing run of CONSECUTIVE `addressed` rounds is at least `window` long AND some single
+ * file appears in the summary of EVERY round of the most recent `window`. Requiring the same file in
+ * all `window` rounds is what keeps normal convergence (findings that move between areas and trend
+ * down) from escalating: a loop whose findings are in different files each round has no file common to
+ * the whole window, so it continues. A non-`addressed` round (a `waiting` round, or a prior human
+ * escalation recorded as `needs_input`/`blocked`) BREAKS the consecutive run — a human already made a
+ * call, so the churn clock restarts after it.
+ *
+ * The verdict is conservative by construction: a round with NO extractable file path in its summary
+ * also breaks the signal (the intersection can't include a file absent from one round), so churn is
+ * only ever reported on a genuinely same-file, same-surface loop.
+ *
+ * `resetAfterRound` is the run-scoped churn-reset watermark (issue #870): the round number at which a
+ * churn escalation was last raised AND answered by a human for THIS run. A churn escalation routes
+ * through `persist-escalation-noprogress` with `recordRound=false`, so it writes NO `blocked` round —
+ * and the human-answer resume re-enters the SAME numeric round (the round counter only advances at the
+ * review-wait gateway). Without this watermark `detectChurn` would therefore see the identical trailing
+ * `addressed` window the instant the resumed round is recorded and re-raise the SAME question forever
+ * (which durable adjudication may auto-resume repeatedly). Dropping every round at or before the
+ * watermark makes the human's scope decision restart the churn clock exactly as a recorded
+ * `needs_input`/`blocked` round would: churn can only fire again after a fresh `window` of same-file
+ * rounds ACCUMULATES past the decision. */
+export function detectChurn(
+  rounds: readonly ChurnRound[],
+  window: number = CHURN_WINDOW,
+  resetAfterRound = 0,
+): ChurnResult {
+  // Drop rounds at or before the churn-reset watermark so a human scope decision restarts the clock.
+  const live = resetAfterRound > 0 ? rounds.filter((r) => r.roundNo > resetAfterRound) : rounds;
+  if (window < 1 || live.length < window) return { churning: false };
+
+  // Order by round number, then walk back over the trailing CONSECUTIVE `addressed` run.
+  const sorted = [...live].sort((a, b) => a.roundNo - b.roundNo);
+  const trailing: ChurnRound[] = [];
+  for (let i = sorted.length - 1; i >= 0; i--) {
+    const r = sorted[i];
+    if (r === undefined || !isAddressedStatus(r.status)) break;
+    trailing.unshift(r);
+  }
+  if (trailing.length < window) return { churning: false };
+
+  // Intersect the file sets of the most-recent `window` addressed rounds. A single empty set means no
+  // same-file signal — bail immediately.
+  const recent = trailing.slice(-window);
+  const fileSets = recent.map((r) => extractFiles(r.summary));
+  if (fileSets.some((s) => s.size === 0)) return { churning: false };
+  let common = fileSets[0] ?? new Set<string>();
+  for (let i = 1; i < fileSets.length && common.size > 0; i++) {
+    const next = fileSets[i] ?? new Set<string>();
+    common = new Set([...common].filter((f) => next.has(f)));
+  }
+  if (common.size === 0) return { churning: false };
+
+  // Deterministic choice when several files are common to the whole window: the lexicographically
+  // smallest, so the escalation question is stable across redeliveries of the same round.
+  const [file] = [...common].sort();
+  if (file === undefined) return { churning: false };
+  return { churning: true, file, rounds: recent.length, question: churnQuestion(file, recent.length) };
+}

package/app/roundProgress.test.ts

@@ -222,13 +222,21 @@ async function makeUnderTest(
     processKey: string | null,
     stillOwns: () => Promise<boolean>,
   ) => Promise<{ healed: boolean; sha?: string; reason?: string }>,
+  readRounds?: (
+    prKey: string,
+    processInstanceKey: string | null | undefined,
+  ) => Promise<{ roundNo: number; status: string | null | undefined; summary: string | null | undefined }[]>,
 ) {
   const { makeHandler } = await import("../workers/progress-check/worker.ts");
   // Default the self-heal OFF (always `{ healed: false }`) so the existing escalation tests keep
   // escalating without touching the real WorldStore/GitHub deps; the #818 tests inject a healing stub.
   const heal = selfHeal ?? (async () => ({ healed: false }));
+  // Default the round-history reader to an EMPTY history so the existing tests never trip the churn
+  // guard (#870); the churn tests inject a stub history. An injected reader also avoids the fakeApp
+  // table double (which implements only get/update, not find).
+  const rounds = readRounds ?? (async () => []);
   // biome-ignore lint/suspicious/noExplicitAny: test double for the injectable worker deps.
-  return makeHandler({ readHead, ...(readAgentWork ? { readAgentWork } : {}), selfHeal: heal as any });
+  return makeHandler({ readHead, ...(readAgentWork ? { readAgentWork } : {}), selfHeal: heal as any, readRounds: rounds as any });
 }
 
 test("progress-check: a non-addressed round records the baseline and consumes the attempt watermark but never escalates", async () => {
@@ -378,6 +386,221 @@ test("progress-check: self-heal is NOT attempted on a progressed round (only bef
   assertEquals(healCalls, 0, "a genuinely-progressing round never consults the self-heal");
 });
 
+// ── Non-converging churn guard (#870) ────────────────────────────────────────
+
+/** A trailing run of `count` `addressed` rounds whose summaries all name `file`. */
+function churnHistory(count: number, file: string) {
+  return Array.from({ length: count }, (_, i) => ({
+    roundNo: i + 1,
+    status: "addressed" as const,
+    summary: `chore: fail closed on bypass form ${i} in \`${file}\``,
+  }));
+}
+
+test("progress-check: a head-advancing round whose findings keep hitting the same file ESCALATES for a scope decision (#870 repro)", async () => {
+  // The repro: the head ADVANCED (sha-1 → sha-2), so the no-progress guard continues — but the
+  // durable round history shows the findings keep landing in the same analyzer file round after
+  // round. Instead of parking for yet another review, the worker escalates with a scope question.
+  const file = "hooks/post/720-pure-zod-schemas.ts";
+  const handler = await makeUnderTest(
+    async () => "sha-2", // head advanced → decideProgress says "progressed"
+    async () => true,
+    undefined,
+    async () => churnHistory(4, file),
+  );
+  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: 22, huskRetries: 0 } } as any,
+    app as any,
+  );
+  assertEquals(out.progressed, false, "a churning loop is routed to escalation, not another review");
+  assertEquals(out.huskRetry, false, "churn escapes the husk auto-retry straight to the human");
+  assertEquals(out.noProgressReason, "churn");
+  assertStringIncludes(String(out.noProgressQuestion), file);
+  assertStringIncludes(String(out.noProgressQuestion), "SCOPE");
+  // It does NOT park at waiting_review — the escalation worker owns the status (like no-advance).
+  const parked = updates.find((u) => u.patch.status === "waiting_review");
+  assertEquals(parked, undefined, "a churn escalation never parks the PR at waiting_review");
+  // The baseline still advances so a redelivery replays rather than recomputing.
+  assertEquals(updates.at(-1)!.patch.last_round_head, "sha-2");
+});
+
+test("progress-check: the churn history read is SCOPED to the current run (#870)", async () => {
+  // Regression for cross-run history mixing: `rounds` is retained across resubmissions (migration
+  // 102), so the reader must filter by the job's processInstanceKey. The worker must pass its own
+  // `processInstanceKey` through to the reader — not a bare prKey — so a prior run's rows never leak
+  // into THIS run's churn window.
+  let seenKey: string | null | undefined = "unset";
+  const handler = await makeUnderTest(
+    async () => "sha-2",
+    async () => true,
+    undefined,
+    async (_prKey, pik) => {
+      seenKey = pik;
+      return []; // this run has no churning history of its own
+    },
+  );
+  const { app, updates } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler(
+    { processInstanceKey: "run-B", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 7, huskRetries: 0 } } as any,
+    app as any,
+  );
+  assertEquals(seenKey, "run-B", "the reader is scoped to the calling job's process instance");
+  assertEquals(out.progressed, true, "with no in-run churn history the loop parks for review");
+  assertEquals(updates.at(-1)!.patch.status, "waiting_review");
+});
+
+test("projectRunScopedRounds: only CURRENT-run rows can contribute to churn (#870 review)", async () => {
+  // The SCOPED-reader test above injects a reader returning [], so it exercises only the key forwarding
+  // — the actual row-filtering would still pass if removed or inverted. This covers the pure projection
+  // directly: `rounds` is retained across resubmissions (migration 102), so the default reader MUST
+  // drop any row not stamped with the calling job's processInstanceKey, including a legacy NULL-key row.
+  const { projectRunScopedRounds } = await import("../workers/progress-check/worker.ts");
+  const rows = [
+    { round_no: 1, status: "addressed", summary: "run B edit `src/a.ts`", process_instance_key: "run-B" },
+    { round_no: 2, status: "addressed", summary: "run B edit `src/b.ts`", process_instance_key: "run-B" },
+    { round_no: 9, status: "converged", summary: "prior run finished `src/z.ts`", process_instance_key: "run-A" },
+    { round_no: 3, status: "addressed", summary: "legacy row `src/c.ts`", process_instance_key: null },
+  ];
+  // Known key: ONLY the two run-B rows survive — the prior run's terminal `converged` row (which would
+  // break the trailing addressed run) and the legacy NULL-key row are both dropped.
+  const scoped = projectRunScopedRounds(rows, "run-B");
+  assertEquals(
+    scoped.map((r) => r.roundNo).sort((a, b) => a - b),
+    [1, 2],
+    "a prior run's rows and a legacy NULL-key row never leak into this run's window",
+  );
+  assertEquals(scoped.every((r) => r.status === "addressed"), true);
+  // Absent key (testkit/synthetic job that persisted no key): fall back to the WHOLE history, matching
+  // persist-round's own null-key fallback.
+  assertEquals(projectRunScopedRounds(rows, null).length, rows.length, "absent key falls back to full history");
+  assertEquals(projectRunScopedRounds(rows, undefined).length, rows.length, "undefined key falls back to full history");
+  // A numeric processInstanceKey is coerced to string before comparison.
+  const numeric = [{ round_no: 1, status: "addressed", summary: "x", process_instance_key: "42" }];
+  assertEquals(projectRunScopedRounds(numeric, 42 as unknown as string).length, 1, "numeric key is coerced to string");
+});
+
+test("progress-check: a churn escalation STAMPS the run-scoped churn-reset watermark (#870)", async () => {
+  // When churn fires, the worker must persist `churn_escalated_round = roundNo` so the human-answer
+  // resume (which re-enters the same numeric round and writes no `blocked` row) restarts the clock.
+  const file = "hooks/post/720-pure-zod-schemas.ts";
+  const handler = await makeUnderTest(
+    async () => "sha-2",
+    async () => true,
+    undefined,
+    async () => churnHistory(4, file),
+  );
+  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: 22, huskRetries: 0 } } as any,
+    app as any,
+  );
+  assertEquals(out.noProgressReason, "churn");
+  assertEquals(updates.at(-1)!.patch.churn_escalated_round, 22, "the escalating round is stamped as the churn-reset watermark");
+});
+
+test("progress-check: the churn-reset watermark SUPPRESSES re-escalation on the human-answer resume (#870)", async () => {
+  // The resumed round re-enters the SAME numeric round the escalation fired on (the counter only
+  // advances at review-wait), so the history is the identical churning window. With the row's
+  // `churn_escalated_round` already set to that round, `detectChurn` drops the answered window and the
+  // loop continues instead of re-raising the identical question.
+  const file = "hooks/post/720-pure-zod-schemas.ts";
+  const handler = await makeUnderTest(
+    async () => "sha-3",
+    async () => true,
+    undefined,
+    async () => churnHistory(4, file), // rounds 1..4, same file
+  );
+  // The PR row already carries the watermark stamped when the escalation was raised at round 4.
+  const { app, updates } = fakeApp({ last_round_head: "sha-2", churn_escalated_round: 4 });
+  const out = await handler(
+    { processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 4, huskRetries: 0 } } as any,
+    app as any,
+  );
+  assertEquals(out.progressed, true, "the answered churn window never re-escalates — the loop continues");
+  assertEquals(out.noProgressReason, undefined);
+  assertEquals(updates.at(-1)!.patch.status, "waiting_review");
+});
+
+test("progress-check: normal convergence (findings trending down across different files) does NOT escalate early (#870)", async () => {
+  // The counter-case the acceptance calls out: head advances AND the findings move between areas, so
+  // no single file spans the window → the loop continues to the next review as before.
+  const handler = await makeUnderTest(
+    async () => "sha-2",
+    async () => true,
+    undefined,
+    async () => [
+      { roundNo: 1, status: "addressed", summary: "fix src/a.ts" },
+      { roundNo: 2, status: "addressed", summary: "fix src/b.ts" },
+      { roundNo: 3, status: "addressed", summary: "fix src/c.ts" },
+      { roundNo: 4, status: "addressed", summary: "fix src/d.ts" },
+    ],
+  );
+  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, true, "a converging loop continues to the next review");
+  assertEquals(out.noProgressReason, undefined);
+  assertEquals(updates.at(-1)!.patch.status, "waiting_review", "it parks for the next review as normal");
+});
+
+test("progress-check: a NO-ADVANCE round is still caught by the no-progress guard even without churn history (#870 is additive)", async () => {
+  // Churn is additive to — never a replacement for — the no-advance guard: an unchanged head with a
+  // terminal agent-instance still escalates as no-advance, regardless of the (empty) churn history.
+  const handler = await makeUnderTest(async () => "sha-1", async () => true, undefined, async () => []);
+  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.noProgressReason, "no-advance", "the no-advance path is unchanged by the churn guard");
+});
+
+test("progress-check: the churn guard fails OPEN when the round-history read throws", async () => {
+  // A datasource hiccup must never fabricate a churn escalation — the read rejects, the worker
+  // `.catch`es to an empty history, and the progressing round parks for review as normal.
+  const handler = await makeUnderTest(
+    async () => "sha-2",
+    async () => true,
+    undefined,
+    async () => {
+      throw new Error("db down");
+    },
+  );
+  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: 10, huskRetries: 0 } } as any,
+    app as any,
+  );
+  assertEquals(out.progressed, true, "an unreadable round history fails open to continue");
+  assertEquals(updates.at(-1)!.patch.status, "waiting_review");
+});
+
+test("progress-check: a non-addressed `waiting` round never consults the churn guard", async () => {
+  // A `waiting` round short-circuits before the progressed branch, so even a churning history is
+  // irrelevant — it parks for review.
+  let readRoundsCalled = false;
+  const handler = await makeUnderTest(
+    async () => "sha-2",
+    async () => ({ work: true, consumedKey: "9" }),
+    undefined,
+    async () => {
+      readRoundsCalled = true;
+      return churnHistory(4, "dir/file.ts");
+    },
+  );
+  const { app } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler(
+    { processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "waiting", repo: "o/r", prNumber: 1, round: 8 } } as any,
+    app as any,
+  );
+  assertEquals(out.progressed, true);
+  assertEquals(readRoundsCalled, false, "a non-addressed round never reaches the churn check");
+});
+
 test("progress-check: a no-advance round with no recoverable checkpoint still escalates (#818)", async () => {
   // The self-heal declines (no reachable fast-forward checkpoint) → the round escalates exactly as
   // before the self-heal existed.

package/app/service.test.ts

@@ -205,6 +205,9 @@ test("re-submit of a cancelled PR marks stale open escalations", async () => {
           last_progress_job_key: "old-job-key-from-prior-run",
           last_progress_result: "{\"progressed\":false,\"huskRetries\":0}",
           last_progress_agent_watermark: "999",
+          // The run-scoped churn-reset watermark names a round number in the PRIOR run's numbering
+          // (issue #870); a fresh run must clear it (see the assertion below).
+          churn_escalated_round: 2,
         }],
         key: "pr_key",
       },
@@ -247,6 +250,10 @@ test("re-submit of a cancelled PR marks stale open escalations", async () => {
     assertEquals(pr.last_progress_job_key, null);
     assertEquals(pr.last_progress_result, null);
     assertEquals(pr.last_progress_agent_watermark, null);
+    // The run-scoped churn-reset watermark is ALSO run-scoped and must be cleared: it names a round
+    // number in the PRIOR run's numbering, so a carried-over watermark could drop the fresh run's
+    // early rounds from the churn window and silently suppress its first churn escalation (#870).
+    assertEquals(pr.churn_escalated_round, null);
     assertEquals(pr.open_escalation_id, undefined);
     assertEquals(pr.open_escalation_question, undefined);
     assertEquals(pr.process_key, "PI-9");

package/app/service.ts

@@ -370,6 +370,13 @@ export interface PullRequest {
   // BEFORE registering its AgentInstance is classified as a husk instead of masked by a prior round's
   // terminal instance. Cleared on re-open with the rest of the per-run state. NULL before any read.
   last_progress_agent_watermark: string | null;
+  // Run-scoped churn-reset watermark (117_pull_requests_churn_escalated_round.sql, issue #870): the
+  // round number at which the non-converging same-surface churn guard last escalated for a human
+  // scope decision on THIS run. `detectChurn` (app/roundChurn.ts) drops rounds at or before it, so a
+  // human's answer restarts the churn clock (the escalation writes no `blocked` round and the resume
+  // re-enters the same numeric round). Cleared on re-open with the rest of the per-run state; NULL
+  // before any churn escalation.
+  churn_escalated_round: number | null;
   // Merge-protocol liveness (012_merge_protocol_attempt.sql): head commit last nudged by the
   // frugal-CI fresh-head-run remedy. A rebase changes the head and therefore permits a new nudge.
   fresh_head_run_head: string | null;
@@ -866,6 +873,11 @@ async function submitPrCritical(
         // normal, freshly-computed decision) rather than replaying the prior run's outcome.
         last_progress_job_key: null,
         last_progress_result: null,
+        // Clear the run-scoped churn-reset watermark (issue #870): it names a round number in the
+        // PRIOR convergence run's numbering. A fresh run restarts at round 1, so a carried-over
+        // watermark could drop the new run's early rounds from the churn window (or, after the new
+        // run passes that number, silently expire). Reset it so the new run's churn clock starts clean.
+        churn_escalated_round: null,
         outcome: null,
         converged_at: null,
         merged_at: null,

package/db/migrations/117_pull_requests_churn_escalated_round.sql

@@ -0,0 +1,12 @@
+-- Run-scoped churn-reset watermark (issue #870). Records the round number at which the
+-- non-converging same-surface churn guard last escalated for a human scope decision on THIS
+-- convergence run. The churn escalation routes through `persist-escalation-noprogress` with
+-- `recordRound=false` (it writes no `blocked` round) and the human-answer resume re-enters the SAME
+-- numeric round (the round counter only advances at the review-wait gateway), so without this
+-- watermark `detectChurn` (app/roundChurn.ts) would re-observe the identical trailing `addressed`
+-- window the instant the resumed round is recorded and re-raise the SAME question forever. Dropping
+-- every round at or before the watermark makes the human's decision restart the churn clock exactly
+-- as a recorded `needs_input`/`blocked` round would. Nullable + no default: NULL means "no churn
+-- escalation yet" (treated as 0 by the reader). Scoped to the run by `submitPr`, which clears it in
+-- the atomic reopen reset alongside the other per-run baselines.
+ALTER TABLE pull_requests ADD COLUMN churn_escalated_round INTEGER;

package/db/migrations/118_pull_requests_read_model_churn_escalated_round.sql

@@ -0,0 +1,55 @@
+-- Re-create the `pull_requests_read_model` VIEW so it re-exports the base column added by
+-- 117_pull_requests_churn_escalated_round.sql (`churn_escalated_round`). The read-model VIEW must
+-- pass through EVERY base `pull_requests` column (the static pages↔schema contract guard +
+-- app/pullRequestReadModel.test.ts DRIFT GUARD assert it), so adding a base column obliges a fresh
+-- VIEW definition — 094/104 are immutable and cannot be edited in place.
+--
+-- Every DERIVED column below is emitted VERBATIM from the ONE declaration in
+-- app/pullRequestReadModel.ts (`pullRequestReadModel.sqlSelectFor(col, { baseAlias: "pr" })`) — the
+-- same closed-DSL AST that drives the runtime TS via `fnFor`, so the two lowerings cannot diverge.
+-- This file is a mechanical re-emission of 104 with the one new base pass-through added; the
+-- derived `list_bucket`/`ack_open` expressions are unchanged. The drift guard now points at THIS
+-- migration (the latest VIEW definition).
+--
+-- Forward-only VIEW definition (DROP then CREATE), sourced off the managed `pull_requests__tracking`
+-- re-export of the base table so a terminated PR classifies on ENGINE TRUTH. SQLite does not validate
+-- a view body at CREATE time. The runner wraps each file in its own transaction, so this file must
+-- NOT contain BEGIN/COMMIT. Numbered after 117.
+
+DROP VIEW IF EXISTS pull_requests_read_model;
+
+CREATE VIEW pull_requests_read_model AS
+SELECT
+  pr.pr_key AS pr_key,
+  pr.repo AS repo,
+  pr.number AS number,
+  pr.url AS url,
+  pr.title AS title,
+  COALESCE(pr.derived_status, pr.status) AS status,
+  pr.current_round AS current_round,
+  pr.process_key AS process_key,
+  pr.waiting_since AS waiting_since,
+  pr.last_review_id AS last_review_id,
+  pr.outcome AS outcome,
+  pr.created_at AS created_at,
+  pr.updated_at AS updated_at,
+  pr.converged_at AS converged_at,
+  pr.merged_at AS merged_at,
+  pr.active_worker AS active_worker,
+  pr.lease_until AS lease_until,
+  pr.last_nudge_at AS last_nudge_at,
+  pr.fresh_head_run_head AS fresh_head_run_head,
+  pr.abandon_token AS abandon_token,
+  pr.incident_key AS incident_key,
+  pr.incident_message AS incident_message,
+  pr.last_round_head AS last_round_head,
+  pr.last_progress_job_key AS last_progress_job_key,
+  pr.last_progress_result AS last_progress_result,
+  pr.last_progress_agent_watermark AS last_progress_agent_watermark,
+  pr.churn_escalated_round AS churn_escalated_round,
+  pr.root_request_key AS root_request_key,
+  pr.epic_phase_label AS epic_phase_label,
+  pr.acknowledged_at AS acknowledged_at,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND (NOT COALESCE(COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open
+FROM pull_requests__tracking pr;