@nanobpm/nano-workforce 0.187.3 → 0.187.5

package/app/roundProgress.ts

@@ -68,3 +68,147 @@ export function routeProgress(
   if (!previousHead || !currentHead) return "continue";
   return currentHead === previousHead ? "escalate" : "continue";
 }
+
+// ── Husk classification & bounded self-heal (issue #786) ─────────────────────
+//
+// A no-advance `addressed` round is not one failure mode but two, and they warrant different
+// handling:
+//
+//  • `husk` — the agent job completed reporting `addressed`, but the COMPLETING attempt minted NO
+//    durable work: no commit was pushed AND the round's completing `review-round` agent-instance did
+//    not reach a terminal state — either it registered a non-terminal instance, or it husked before
+//    registering any instance at all (the producer harness died mid-run, so the round is a phantom —
+//    jwulf/c8ctl-plugin-nano#230/#229). The verdict is scoped to the completing attempt via the
+//    attempt watermark (Copilot #789), so an EARLIER attempt's terminal instance neither masks nor
+//    fabricates this one. This is a transient worker/harness defect, not a real design impasse, so it
+//    is *resumable onto a healthy worker*: re-run the SAME round rather than parking a human. Bounded
+//    by {@link MAX_HUSK_RETRIES} so a persistently-husking worker still escalates instead of looping
+//    forever.
+//
+//  • `no-advance` — the agent DID run to a terminal agent-instance but pushed no commit (it genuinely
+//    believes nothing was needed, or is wrong about the code). Re-running would loop on identical
+//    reasoning, so this escalates to a human immediately, exactly as before.
+//
+// The head-diff (`routeProgress`) still TRIGGERS the no-progress path; the agent-instance
+// corroboration only SPLITS it into husk vs. no-advance so the auto-heal and the escalation message
+// are accurate.
+
+/** Why a no-advance `addressed` round made no progress — see the block comment above. */
+export type NoProgressReason = "husk" | "no-advance";
+
+/** How many times a husked round is auto-re-run onto a (hopefully healthy) worker before the loop
+ * gives up and escalates to a human. The bound is what keeps the self-heal from looping forever on a
+ * persistently-husking worker. */
+export const MAX_HUSK_RETRIES = 2;
+
+/** The full decision for a recorded round: whether it progressed, the running husk-retry count to
+ * carry forward, and — when it did NOT progress — whether to auto-retry the same round (`huskRetry`),
+ * the classified `reason`, and (when escalating) the human-facing `question`. This is the single
+ * source of truth the `pr.progress-check` worker returns and `gw-progress`/`gw-husk` route on. */
+export interface ProgressDecision {
+  readonly progressed: boolean;
+  readonly huskRetries: number;
+  readonly huskRetry?: boolean;
+  readonly reason?: NoProgressReason;
+  readonly question?: string;
+}
+
+/** Coerce an externally-supplied husk-retry counter (a process variable that is null/blank on the
+ * first husk, and could be any shape after a variable regression) to a non-negative integer. */
+function normalizeRetries(value: number | null | undefined): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return 0;
+  return Math.floor(value);
+}
+
+/** Build the human-facing escalation question for a no-progress round, tuned to its {@link
+ * NoProgressReason} so the human sees "the agent produced no durable work (a husk)" rather than the
+ * generic "no commit was pushed" when that is what actually happened. */
+export function noProgressQuestion(
+  round: number,
+  reason: NoProgressReason,
+  huskRetriesExhausted: boolean,
+): string {
+  if (reason === "husk") {
+    const tail = huskRetriesExhausted
+      ? ` and re-running the round ${MAX_HUSK_RETRIES} time(s) did not help (the worker keeps husking)`
+      : "";
+    return (
+      `Round ${round} reported the review comments were addressed, but the agent produced no ` +
+      `durable work — no commit was pushed and the COMPLETING review attempt recorded no terminal ` +
+      `agent-instance (a husked round; the worker likely died mid-run)${tail}. A human must decide ` +
+      `how to proceed (reply to resume the loop).`
+    );
+  }
+  return (
+    `Round ${round} reported the review comments were addressed, but the PR head did not advance ` +
+    `(no commit was pushed), so another review round would loop on identical code. A human must ` +
+    `decide how to proceed (reply to resume the loop).`
+  );
+}
+
+/** The canonical no-progress decision, mirroring {@link routeProgress} for the head-diff trigger and
+ * then splitting a no-advance round into a bounded husk auto-retry vs. an immediate escalation.
+ *
+ *  • A round that progressed (head advanced, or a legitimately non-addressed status, or an
+ *    unreadable head that fails OPEN, or a no-baseline addressed round) returns `{ progressed: true,
+ *    huskRetries: 0 }` — real progress RESETS the husk counter so a later, unrelated husk starts
+ *    fresh. A first-addressed-round husk is no longer a special case here: `pr.capture-head` records
+ *    the round's entry head into `roundEntryHead` BEFORE `review-round` runs, so within-round there
+ *    is always a baseline and a husk that pushed nothing takes the no-advance/husk split below.
+ *  • A husked round under the retry cap returns `{ progressed: false, huskRetry: true,
+ *    huskRetries: n+1 }` — `gw-husk` re-enters `review-round` (the SAME round) to try a healthy
+ *    worker.
+ *  • A husked round at the cap, or any `no-advance` round, returns `{ progressed: false,
+ *    huskRetry: false, huskRetries: 0, question }` — `gw-husk` routes to the human escalation. The
+ *    counter resets so a human-answered resume gets fresh retries.
+ *
+ * `agentWorkObserved` is the agent-instance corroboration for the COMPLETING `review-round`
+ * element-instance (see {@link decideProgress}'s reader in workers/progress-check): `true` when the
+ * newest correlated `review-round` instance is TERMINAL (→ `no-advance`); `false` — a SUCCESSFUL,
+ * positively-corroborated read whose newest correlated instance is NON-terminal (the completing
+ * attempt husked) → `husk`; and `null`/`undefined` — an UNKNOWN read (the engine channel was
+ * unavailable/absent — e.g. an empty instance list on the read-as-absence testkit — or the read
+ * threw) → `no-advance`, never an auto-retry, so a transient or absent AgentInstance read can never
+ * duplicate genuinely-completed agent work. Only a positively-corroborated non-terminal completing
+ * instance is a husk; an absent/empty read is UNKNOWN, not a husk. */
+export function decideProgress(
+  status: string | null | undefined,
+  previousHead: string | null | undefined,
+  currentHead: string | null | undefined,
+  round: number,
+  agentWorkObserved: boolean | null | undefined,
+  currentHuskRetries: number | null | undefined,
+  maxHuskRetries: number = MAX_HUSK_RETRIES,
+): ProgressDecision {
+  if (routeProgress(status, previousHead, currentHead) === "continue") {
+    // Fail-open: the head advanced (real progress → RESET the husk counter), a legitimately
+    // non-addressed status, an unreadable current head, OR a no-baseline addressed round. The
+    // no-baseline case is now handled structurally UPSTREAM: `pr.capture-head` records the round's
+    // entry head into `roundEntryHead` BEFORE `review-round` runs, so the baseline is always present
+    // within the round — a first-addressed-round husk leaves `currentHead === roundEntryHead` and
+    // takes the `escalate` path below (split into husk vs. no-advance), while a real push advances
+    // the head and legitimately continues. The old no-baseline husk special-case (which had to guess
+    // from `agentWorkObserved` alone, with the opposing risk of mis-escalating a straggler push) is
+    // therefore gone: with a within-round baseline there is no no-baseline case left to special-case.
+    return { progressed: true, huskRetries: 0 };
+  }
+  // Only a POSITIVELY-corroborated husk (`false` — a successful AgentInstance search whose NEWEST
+  // correlated `review-round` instance is NON-terminal, i.e. the completing attempt died mid-run) is
+  // one we may auto-retry. `true` (that newest correlated instance is TERMINAL) is a real no-advance;
+  // and an UNKNOWN read (`null`/`undefined` — an empty/absent instance list or a thrown read, i.e.
+  // the engine channel was unavailable) must NOT auto-retry, since re-running could duplicate agent
+  // work that actually did run. So an unknown read fails safe to `no-advance` (escalate to a human),
+  // exactly as the pre-#786 loop did — only a corroborated non-terminal completing instance is husk.
+  const reason: NoProgressReason = agentWorkObserved === false ? "husk" : "no-advance";
+  const retries = normalizeRetries(currentHuskRetries);
+  if (reason === "husk" && retries < maxHuskRetries) {
+    return { progressed: false, huskRetry: true, huskRetries: retries + 1, reason };
+  }
+  return {
+    progressed: false,
+    huskRetry: false,
+    huskRetries: 0,
+    reason,
+    question: noProgressQuestion(round, reason, reason === "husk" && retries >= maxHuskRetries),
+  };
+}

package/app/roundResultDefault.test.ts

@@ -74,10 +74,10 @@ test("escalation is an explicit needs_input/blocked arm gated on a non-blank que
   assertStringIncludes(esc, 'trim(question) != ""');
 });
 
-test("the default (addressed) arm carries no condition and re-enters the guard", () => {
+test("the default (addressed) arm carries no condition and re-enters round processing", () => {
   const addressed = flowElement("f_addressed");
   assert(addressed, "f_addressed flow missing");
-  assertStringIncludes(addressed, 'targetRef="gw-guard"');
+  assertStringIncludes(addressed, 'targetRef="persist-round"');
   // A default flow must have NO conditionExpression.
   assert(
     !/conditionExpression/.test(addressed),
@@ -95,9 +95,10 @@ test("regression: an empty/unknown status no longer routes to persist-escalation
   for (const f of intoEscalation) {
     assertStringIncludes(f, "conditionExpression");
   }
-  // The addressed default must land on the guard (which re-solicits the review), not escalation.
+  // The addressed default must land on round processing (persist-round → check-progress, which
+  // re-solicits the review after the round-cap gate downstream), not escalation.
   const addressed = flowElement("f_addressed");
-  assert(addressed && /targetRef="gw-guard"/.test(addressed), "default arm must re-enter gw-guard");
+  assert(addressed && /targetRef="persist-round"/.test(addressed), "default arm must re-enter round processing");
 });
 
 // The canonical router (app/roundResultDefault.ts) mirrors the gw-status routing above, with the
@@ -161,7 +162,7 @@ test("persist-escalation routes through the gw-escalated liveness gateway, not s
   );
 });
 
-test("gw-escalated waits only when an escalation was opened, else re-enters the guard", () => {
+test("gw-escalated waits only when an escalation was opened, else re-enters round processing", () => {
   const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-escalated"[^>]*>/);
   assert(gw, "gw-escalated gateway missing");
   // Its default arm must be the re-enter (no-escalation) arm, never the answer-wait.
@@ -175,12 +176,13 @@ test("gw-escalated waits only when an escalation was opened, else re-enters the
   assertStringIncludes(wait, 'targetRef="wait-answer"');
   assertStringIncludes(wait, "escalated = true");
 
-  // The default (no-escalation) arm carries no condition and re-enters gw-guard (forward
-  // progress), so a non-escalation early return can never wedge on wait-answer.
+  // The default (no-escalation) arm carries no condition and re-enters round processing
+  // (persist-round → check-progress → the round-cap gate), so a non-escalation early return can
+  // never wedge on wait-answer.
   const reenter = flowElement("f_escReenter");
   assert(reenter, "f_escReenter flow missing");
   assertStringIncludes(reenter, 'sourceRef="gw-escalated"');
-  assertStringIncludes(reenter, 'targetRef="gw-guard"');
+  assertStringIncludes(reenter, 'targetRef="persist-round"');
   assert(
     !/conditionExpression/.test(reenter),
     "f_escReenter is the default arm and must not carry a conditionExpression",

package/app/service.test.ts

@@ -89,6 +89,10 @@ test("re-submit of a cancelled PR marks stale open escalations", async () => {
           title: "old title",
           status: "abandoned", // terminal -> re-open path
           current_round: 3,
+          last_round_head: "stale-sha-from-prior-run",
+          last_progress_job_key: "old-job-key-from-prior-run",
+          last_progress_result: "{\"progressed\":false,\"huskRetries\":0}",
+          last_progress_agent_watermark: "999",
         }],
         key: "pr_key",
       },
@@ -120,6 +124,16 @@ test("re-submit of a cancelled PR marks stale open escalations", async () => {
     const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
     assertEquals(pr.status, "converging");
     assertEquals(pr.current_round, 1);
+    // The no-progress head baseline is scoped to the prior run; a fresh run must clear it so the
+    // first addressed round is compared from a clean slate and the bounded husk retry isn't bypassed
+    // when the branch changed between runs (#786).
+    assertEquals(pr.last_round_head, null);
+    // The at-least-once replay stamp + attempt watermark are ALSO run-scoped and must be cleared so a
+    // straggler `pr.progress-check` from the prior run can't replay a stale outcome into the fresh run
+    // (Copilot PR #789).
+    assertEquals(pr.last_progress_job_key, null);
+    assertEquals(pr.last_progress_result, null);
+    assertEquals(pr.last_progress_agent_watermark, null);
     assertEquals(pr.open_escalation_id, undefined);
     assertEquals(pr.open_escalation_question, undefined);
     assertEquals(pr.process_key, "PI-9");

package/app/service.ts

@@ -284,6 +284,23 @@ export interface PullRequest {
   // review for this PR, so the nudge is throttled to one attempt per REVIEW_NUDGE_MS window.
   // NULL means never nudged.
   last_nudge_at: string | null;
+  // No-progress head baseline (033_pr_round_head.sql, issue #786): the PR head SHA observed at the
+  // last recorded round, written by pr.progress-check to detect an addressed round that pushed no
+  // commit. Scoped to the current convergence run — cleared on re-open so a resubmission starts from
+  // a clean slate. NULL before the first round is recorded.
+  last_round_head: string | null;
+  // At-least-once idempotency for pr.progress-check (103_pr_progress_idempotency.sql): the engine
+  // job key that produced the last committed progress decision, and that decision's serialized
+  // `PrProgressCheckOut`. On a lost-ack redelivery the guard recognizes its own job key and replays
+  // the recorded outcome instead of recomputing against the already-advanced `last_round_head`.
+  last_progress_job_key: string | null;
+  last_progress_result: string | null;
+  // Attempt watermark for pr.progress-check husk correlation (103; Copilot PR #789): the greatest
+  // `review-round` AgentInstance key an earlier progress-check already accounted for. Lets the next
+  // round tell a freshly-registered attempt from a historical one, so a current attempt that husks
+  // 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;
   // 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;
@@ -565,6 +582,24 @@ export async function submitPr(
       waiting_since: null,
       last_review_id: null,
       last_nudge_at: null,
+      // Clear the no-progress head baseline: it is scoped to the PRIOR convergence run, and a fresh
+      // run at round 1 must compare its first addressed round against a clean slate. Leaving a stale
+      // `last_round_head` lets a resubmission whose branch changed read `currentHead !== previousHead`
+      // on its first husked round, mis-route it as progress, and bypass the bounded husk retry (#786).
+      last_round_head: null,
+      // Clear the attempt watermark too: it is scoped to the prior convergence run's `review-round`
+      // instances (Copilot #789). A fresh run mints new, higher-keyed instances so a carried-over
+      // watermark would still be below them, but clearing keeps the per-run husk-correlation state
+      // unambiguous and self-contained.
+      last_progress_agent_watermark: null,
+      // Clear the at-least-once REPLAY stamp too (Copilot PR #789). The idempotency guard replays a
+      // recorded outcome whenever a redelivered job key matches this row; if the stamp survived a
+      // re-open, an OLD `pr.progress-check` delivery redelivered after the NEW convergence instance
+      // starts would still match its job key here and replay a stale escalation/progress effect into
+      // the fresh run. Clearing it makes the new run treat any such straggler as an unknown key (a
+      // normal, freshly-computed decision) rather than replaying the prior run's outcome.
+      last_progress_job_key: null,
+      last_progress_result: null,
       outcome: null,
       converged_at: null,
       merged_at: null,

package/db/migrations/102_rounds_process_instance_key.sql

@@ -0,0 +1,28 @@
+-- Scope pr.persist-round's idempotent upsert to the process instance that wrote the row (issue #786).
+--
+-- The idempotent `(pr_key, round_no)` upsert in pr.persist-round exists so a husk auto-retry — which
+-- re-enters `review-round` WITHOUT advancing the round counter, in the SAME convergence process
+-- instance — updates its round-record row in place instead of manufacturing a duplicate history row.
+-- Round ownership was previously INFERRED from `status` (reuse any non-`needs_input`/`blocked` row),
+-- but status is not identity: `submitPr` re-opens a previously converged/abandoned/merged PR at
+-- `current_round = 1` WITHOUT deleting `rounds` history, so a fresh convergence run (a NEW process
+-- instance) at round 1 would find the prior run's `addressed`/`waiting`/`converged` round-1 row and
+-- overwrite its summary/transcript/worker/timestamps — destroying the canonical history across
+-- resubmissions.
+--
+-- Persist the writing process instance's key so the upsert can reuse ONLY a row THIS run wrote: a
+-- husk retry (same `process_instance_key`) updates in place; a resubmission (a different key) inserts
+-- a fresh row, leaving every prior run's history intact. Additive and nullable — pre-#786 rows and
+-- rows written by an engine that does not surface the key read back NULL for this column.
+--
+-- Upgrade behaviour of those NULL rows (persist-round's reuse predicate):
+--   * A KEYED engine job (the normal production case) reuses a row ONLY when its key equals the
+--     current `process_instance_key`, so a NULL-key row NEVER matches and is never reused. The
+--     status-only heuristic applies ONLY to a KEYLESS job (testkit/synthetic, no process key).
+--   * Consequently a husk auto-retry that straddles this deploy — its first attempt wrote a NULL-key
+--     row before the migration, its retry runs after with a concrete key — will not reuse that
+--     earlier row and instead inserts a fresh round-record row. That lost idempotency is INTENTIONAL
+--     and self-healing: it touches only a run whose husk-retry brackets the deploy, costs at worst
+--     one duplicate history row for that single round, and never corrupts data or history.
+-- Additive and nullable, so it is safe to apply forward over any earlier schema and re-runs are no-ops.
+ALTER TABLE rounds ADD COLUMN process_instance_key TEXT;

package/db/migrations/103_pr_progress_idempotency.sql

@@ -0,0 +1,29 @@
+-- Make the `pr.progress-check` guard (workers/progress-check/worker.ts) idempotent under the
+-- engine's AT-LEAST-ONCE job delivery. The guard advances the `last_round_head` baseline as its
+-- observation of the current round's head; a job whose side-effects landed but whose completion-ack
+-- was LOST is redelivered with the SAME job key. Without an idempotency record the redelivery reads
+-- the just-advanced baseline as `previousHead`, sees "head did not advance", and can mis-escalate an
+-- already-progressed round (Copilot review, PR #789).
+--
+-- These two columns record, in the SAME atomic row update that advances the baseline and writes the
+-- resting status, the job key that produced the decision and the serialized worker outcome. On
+-- redelivery the guard recognizes its own job key and REPLAYS the recorded outcome instead of
+-- recomputing against the mutated baseline. Because the stamp and the baseline advance are one
+-- update, a redelivery either sees the whole record (replay) or none of it (recompute from the
+-- un-advanced baseline → same decision) — never a half-state. A husk auto-retry re-enters
+-- `review-round` as a NEW job key, so it is never mistaken for a redelivery.
+--
+--   • last_progress_job_key  — the engine job key of the last progress-check that committed a write.
+--   • last_progress_result   — that job's serialized `PrProgressCheckOut` (JSON), replayed verbatim.
+--   • last_progress_agent_watermark — the greatest `review-round` AgentInstance key an earlier
+--     progress-check has ALREADY accounted for (Copilot PR #789). It lets the next round distinguish
+--     a freshly-registered `review-round` attempt from a historical one, so a CURRENT attempt that
+--     husks BEFORE the worker registers its AgentInstance is classified as a husk (bounded auto-
+--     retry) instead of being masked by a prior round's terminal instance and mis-escalated.
+--
+-- Forward-only, additive (expand): all columns are nullable with no default. Numbered after the
+-- current highest prefix (102); the runner wraps each file in its own transaction, so this file must
+-- NOT contain BEGIN/COMMIT.
+ALTER TABLE pull_requests ADD COLUMN last_progress_job_key TEXT;
+ALTER TABLE pull_requests ADD COLUMN last_progress_result TEXT;
+ALTER TABLE pull_requests ADD COLUMN last_progress_agent_watermark TEXT;

package/db/migrations/104_pull_requests_read_model_progress_idempotency.sql

@@ -0,0 +1,55 @@
+-- Re-create the `pull_requests_read_model` VIEW so it re-exports the base columns added by
+-- 103_pr_progress_idempotency.sql (`last_progress_job_key`, `last_progress_result`,
+-- `last_progress_agent_watermark`). 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 is 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 094 with the two new base pass-throughs 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 103.
+
+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.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;

package/docs/agent-guide.md

@@ -470,7 +470,7 @@ Work through this order:
 3. **Check for an open escalation** (§3) — the process may simply be waiting for a
    human answer. Answer it.
 4. **A review that never arrives** escalates on its own after
-   `NANO_PR_REVIEW_WAIT_TIMEOUT` (default `PT20M`); the poller also re-nudges the
+   `NANO_PR_REVIEW_WAIT_TIMEOUT` (default `PT30M`); the poller also re-nudges the
    reviewer periodically. If the reviewer bot is not provisioned on the repo, no
    review will ever land — that is a repo-config problem, not an app bug.
 5. **Cancel + resubmit** as a last resort. Cancel through the **app-owned** door —

package/e2e/convergence-escalation.e2e.ts

@@ -181,13 +181,14 @@ describe("nano-workforce PR review-loop escalation (U4 userTask)", () => {
     assert.equal(completed.body.ok, true, "the userTask was completed");
 
     // The typed answer resumed the loop back into the review round: the token took
-    // wait-answer → record-answer (which retires the escalations row) → review-round, and the
-    // review agent saw exactly the submitted answer. An empty or wrong completion would surface a
-    // different `capturedAnswer` — this is the falsifiable core.
+    // wait-answer → record-answer (which retires the escalations row) → capture-head → review-round
+    // (the round-entry head is re-captured before each review round, #786), and the review agent saw
+    // exactly the submitted answer. An empty or wrong completion would surface a different
+    // `capturedAnswer` — this is the falsifiable core.
     await app.settle();
     const flows = takenFlows(app);
     assert.ok(
-      flows.includes("wait-answer->record-answer") && flows.includes("record-answer->review-round"),
+      flows.includes("wait-answer->record-answer") && flows.includes("record-answer->capture-head"),
       `the answer resumed the loop through record-answer back to the review round (flows: ${flows.join(", ")})`,
     );
     assert.equal(reviewCalls, 2, "the review agent ran a second round after the answer");

package/e2e/feature-run.e2e.ts

@@ -23,6 +23,7 @@ import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
+import { settleFully } from "./support/time.ts";
 import { pollUserTasks } from "../app/service.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -103,7 +104,11 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
       const featureKey = "owner/repo#7";
       const started = await app.api?.call("startFeature", { body: { issue: featureKey, ...startBody } });
       assert.equal(started?.status, 202, "startFeature accepted the issue");
-      await app.settle();
+      // Fixpoint (not a single tick): the `converge` hand-off enrolls the opened PR via `submitPr`,
+      // whose nested `createInstance` re-entrantly runs the new `capture-head` host task (#786) and
+      // leaves `pr.converge-feature`'s own completion undrained until a later settle — see
+      // `settleFully`.
+      await settleFully(app);
       const run = await app.db
         .table<FeatureRow>("feature_runs", "feature_key")
         .findOne({ feature_key: featureKey });

package/e2e/plan-fanout-sla.e2e.ts

@@ -25,7 +25,7 @@ import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
-import { advancePastTimer } from "./support/time.ts";
+import { advancePastTimer, settleFully } from "./support/time.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -95,7 +95,10 @@ describe("plan-fanout escalation SLA + assignment (U5)", () => {
       const planKey = "owner/repo#1";
       const started = await app.api?.call("startPlanFanout", { body: { issue: planKey, baseBranch: "epic/e2e" } });
       assert.equal(started?.status, 202, "startPlanFanout accepted the issue");
-      await app.settle();
+      // Fixpoint (not a single tick): the wave fan-out enrolls each opened PR via `submitPr`, whose
+      // nested `createInstance` re-entrantly runs the new `capture-head` host task (#786) and leaves
+      // the enroller's completion undrained until a later settle — see `settleFully`.
+      await settleFully(app);
       const plan = await app.db
         .table<{ plan_key: string; process_key: string | null }>("plans", "plan_key")
         .findOne({ plan_key: planKey });

package/e2e/plan-fanout.e2e.ts

@@ -22,7 +22,7 @@ import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
-import { advancePastTimer } from "./support/time.ts";
+import { advancePastTimer, settleFully } from "./support/time.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -93,7 +93,11 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
       const planKey = "owner/repo#1";
       const started = await app.api?.call("startPlanFanout", { body: { issue: planKey, baseBranch: "epic/e2e" } });
       assert.equal(started?.status, 202, "startPlanFanout accepted the issue");
-      await app.settle();
+      // Drive the whole fanout to quiescence: a wave whose PRs open enrolls each PR via
+      // `pr.record-wave` -> `submitPr` -> nested `createInstance`, whose re-entrant drain leaves the
+      // enroller undrained for a tick (issue #786's `pr.capture-head`). A single settle parks the
+      // plan one tick early (before the trial-merge gate opens), so settle to true quiescence.
+      await settleFully(app);
       const plan = await app.db
         .table<{ plan_key: string; process_key: string | null }>("plans", "plan_key")
         .findOne({ plan_key: planKey });

package/e2e/support/time.ts

@@ -31,3 +31,37 @@ export async function advancePastTimer(
   await app.engine.advanceTime(ms);
   await app.settle();
 }
+
+/**
+ * Settle the deterministic harness to true quiescence — repeat {@link TestApp.settle} until no job
+ * remains mid-flight (`ACTIVATED`) — for any scenario where a worker ENROLLS a PR.
+ *
+ * The canonical convergence enrollment `submitPr` (used by `pr.record-wave`, `pr.converge-feature`
+ * and `pr.delivery-connector`) calls `engine.createInstance` from INSIDE a worker job handler. The
+ * urban-testkit services that nested creation with a nested `drain()`; now that `convergence-loop`
+ * opens with the host `pr.capture-head` task (issue #786), that nested drain runs real re-entrant
+ * host work and — per the testkit's documented re-entrancy — leaves the ENROLLING worker's own
+ * completion "undrained until a later settle". A single `settle()` therefore observes the enroller
+ * one tick early (e.g. a `feature_runs` row still `opened`, or a plan not yet parked on its
+ * trial-merge task). At real runtime the async job stream drains this with no extra prompting; the
+ * harness just needs to be driven to quiescence.
+ *
+ * The reliable quiescence signal is a job in state `ACTIVATED`: that is a leased, mid-flight job —
+ * the undrained enrolling-worker completion the re-entrancy leaves behind. A `settle()` drains every
+ * *registered*-worker job to completion, so once no `ACTIVATED` job remains the only jobs left are
+ * genuine external parks (`CREATED` agent jobs with no registered worker), and the harness is
+ * quiescent. Keying on `ACTIVATED` is precise, not a retry-and-hope: it is NOT sufficient to compare
+ * successive `snapshot()` signatures, because the undrained completion is invisible between certain
+ * settles (two passes look identical while work is still pending), so a naive fixpoint returns early
+ * and the re-entrant work later fires against a closing DB.
+ */
+export async function settleFully(
+  app: Pick<TestApp, "settle" | "engine">,
+  maxRounds = 16,
+): Promise<void> {
+  for (let round = 0; round < maxRounds; round++) {
+    await app.settle();
+    const jobs = await app.engine.searchJobs({});
+    if (!jobs.some((job) => job.state === "ACTIVATED")) return;
+  }
+}

package/nano.app.json

@@ -120,6 +120,10 @@
       "taskType": "pr.persist-round",
       "handler": "workers/persist-round/worker.ts"
     },
+    {
+      "taskType": "pr.capture-head",
+      "handler": "workers/capture-head/worker.ts"
+    },
     {
       "taskType": "pr.persist-escalation",
       "handler": "workers/persist-escalation/worker.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.187.3",
+  "version": "0.187.5",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",