@nanobpm/nano-workforce 0.69.1 → 0.70.1

package/operations/listAgenticTranscripts.ts

@@ -0,0 +1,61 @@
+// GET /app/api/agentic/transcripts → operationId `listAgenticTranscripts` (ADR 0056, H3 read path #222).
+//
+// The READ counterpart to the write-only transcript store (H3 #146): it lists the durable transcripts an
+// ephemeral agent flushed on job completion, so an operator can review "what did that agent do" AFTER it
+// is gone. Sourced from the mounted relay/transcript service's TranscriptStore (over `app.data`) and
+// correlated via `app/agentic/correlation.ts` (best-effort — jobKey is always recovered from the stream
+// id, engine context only while the job is still live). Feeds the cockpit "past sessions" view.
+//
+// Advisory read-only (ADR 0056): it NEVER gates a BPMN sequence flow. Optional filters (jobKey / process
+// instance / plan / time) narrow the feed. The optional shared-secret guard mirrors getAgenticSupply:
+// when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header; unset -> open.
+
+import { currentCorrelation } from "../app/agentic/correlation.ts";
+import { currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
+import { listTranscripts, type TranscriptFilter } from "../app/agentic/transcript-read.ts";
+import { envVar } from "../app/version.ts";
+import type { AgenticTranscriptList } from "../nano-generated/api-io.d.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+/** Reject an ISO-8601 filter that does not parse (a malformed since/until is a 400, not a silent no-op). */
+function badInstant(value: string | undefined): boolean {
+  return value !== undefined && !Number.isFinite(Date.parse(value));
+}
+
+export default defineOperation("listAgenticTranscripts", async ({ query, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("listAgenticTranscripts rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+
+  if (badInstant(query.since) || badInstant(query.until)) {
+    return { status: 400, body: { error: "invalid since/until: expected an ISO-8601 instant" } };
+  }
+
+  const service = currentRelayTranscriptService();
+  const store = service?.store;
+  if (!store) {
+    // The relay family has not mounted, or is running unpersisted (no DataLayer) - no transcripts to
+    // report, not an error (advisory).
+    const empty: AgenticTranscriptList = { count: 0, generatedAt: new Date().toISOString(), transcripts: [] };
+    return { status: 200, body: empty };
+  }
+
+  const filter: TranscriptFilter = {
+    ...(query.jobKey !== undefined ? { jobKey: query.jobKey } : {}),
+    ...(query.processInstanceKey !== undefined ? { processInstanceKey: query.processInstanceKey } : {}),
+    ...(query.planKey !== undefined ? { planKey: query.planKey } : {}),
+    ...(query.since !== undefined ? { since: query.since } : {}),
+    ...(query.until !== undefined ? { until: query.until } : {}),
+  };
+  const transcripts = listTranscripts(store, currentCorrelation(), filter);
+  const body: AgenticTranscriptList = {
+    count: transcripts.length,
+    generatedAt: new Date().toISOString(),
+    retentionMs: store.ephemeralRetentionMs,
+    transcripts,
+  };
+  return { status: 200, body };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.69.1",
+  "version": "0.70.1",
   "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",

package/pages/cockpit/cockpit.css

@@ -42,6 +42,7 @@
 }
 
 .cockpit-supply-region,
+.cockpit-past-region,
 .cockpit-terminal {
   background: var(--cockpit-panel);
   border: 1px solid var(--cockpit-edge);
@@ -160,3 +161,72 @@
   background: #05080b;
   border-radius: 6px;
 }
+
+/* ── Past sessions (H3 read path / #222): the captured-session history + replay. ──────────────── */
+
+.cockpit-past-header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 8px;
+}
+
+.cockpit-past-title {
+  font-size: 13px;
+  margin: 0;
+  color: var(--cockpit-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.cockpit-past-summary {
+  color: var(--cockpit-muted);
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-past-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-variant-numeric: tabular-nums;
+}
+
+.cockpit-past-replay {
+  background: none;
+  border: none;
+  color: var(--cockpit-text);
+  cursor: pointer;
+  font: inherit;
+  padding: 0;
+  text-align: left;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.cockpit-past-replay:hover { color: #58a6ff; }
+
+.cockpit-past-session[data-active="true"] {
+  background: rgba(88, 166, 255, 0.12);
+}
+
+.cockpit-past-status { color: var(--cockpit-muted); }
+.cockpit-past-size { color: var(--cockpit-muted); }
+.cockpit-past-captured { color: var(--cockpit-muted); font-size: 12px; }
+
+.cockpit-past-empty {
+  color: var(--cockpit-muted);
+  padding: 8px 0;
+}
+
+/* Distinguish a live terminal from a replayed (static) past session at a glance. */
+.cockpit-terminal[data-terminal-mode="replay"] {
+  border-color: #8957e5;
+}
+.cockpit-terminal[data-terminal-mode="replay"] .cockpit-panel-title {
+  color: #b392f0;
+}
+.cockpit-terminal[data-terminal-mode="live"] .cockpit-panel-title {
+  color: var(--cockpit-green);
+}

package/pages/cockpit/mount.js

@@ -21,6 +21,7 @@ import { Terminal } from "@xterm/xterm";
 
 const DEFAULT_REFRESH_MS = 2000;
 const DEFAULT_STALE_AFTER_MS = 15_000;
+const DEFAULT_PAST_FETCH_TIMEOUT_MS = 15_000;
 
 function isPosInt(value) {
   return Number.isSafeInteger(value) && value > 0;
@@ -181,6 +182,113 @@ function renderSupply(host, doc, view, onDrill) {
   host.appendChild(root);
 }
 
+// ── past-sessions projection + render (mirrors app/agentic/cockpit/transcript-view.ts + -render.ts) ──
+
+function humanBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "0 B";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function humanDuration(ms) {
+  if (ms == null || !Number.isFinite(ms) || ms <= 0) return undefined;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.round(m / 60);
+  if (h < 48) return `${h}h`;
+  return `${Math.round(h / 24)}d`;
+}
+
+function sessionLabel(t) {
+  const parts = [];
+  if (t.bpmnProcessId != null) parts.push(t.bpmnProcessId);
+  if (t.elementId != null) parts.push(t.elementId);
+  if (t.processInstanceKey != null) parts.push(`inst ${t.processInstanceKey}`);
+  if (t.planKey != null) parts.push(t.planKey);
+  if (parts.length > 0) return parts.join(" \u00b7 ");
+  if (t.jobKey != null) return `job ${t.jobKey}`;
+  return t.stream;
+}
+
+function transcriptsView(report) {
+  const sessions = (report.transcripts ?? [])
+    .map((t) => ({
+      stream: t.stream,
+      label: sessionLabel(t),
+      jobKey: t.jobKey,
+      status: t.status,
+      lifecycle: t.lifecycle,
+      size: humanBytes(t.byteLength),
+      byteLength: t.byteLength,
+      capturedAt: t.completedAt ?? t.createdAt,
+    }))
+    .sort((a, b) => {
+      const byTime = String(b.capturedAt).localeCompare(String(a.capturedAt));
+      return byTime !== 0 ? byTime : a.stream.localeCompare(b.stream);
+    });
+  return { sessions, count: sessions.length, retention: humanDuration(report.retentionMs) };
+}
+
+function sessionRow(doc, session, onReplay, activeStream) {
+  const row = el(doc, "tr", "cockpit-past-session");
+  row.setAttribute("data-stream", session.stream);
+  row.setAttribute("data-status", session.status);
+  if (session.jobKey != null) row.setAttribute("data-job-key", session.jobKey);
+  if (activeStream === session.stream) row.setAttribute("data-active", "true");
+  const nameCell = el(doc, "td", "cockpit-td cockpit-past-name");
+  const button = el(doc, "button", "cockpit-past-replay", session.label);
+  button.setAttribute("type", "button");
+  button.setAttribute("data-stream", session.stream);
+  if (onReplay) button.addEventListener("click", () => onReplay(session.stream));
+  nameCell.appendChild(button);
+  row.appendChild(nameCell);
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-past-status", session.status));
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-past-size", session.size));
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-past-captured", session.capturedAt));
+  return row;
+}
+
+function renderTranscripts(host, doc, view, onReplay, activeStream) {
+  host.replaceChildren();
+  const root = el(doc, "div", "cockpit-past");
+  root.setAttribute("data-session-count", String(view.count));
+  const header = el(doc, "header", "cockpit-past-header");
+  header.appendChild(el(doc, "h2", "cockpit-past-title", "Past sessions"));
+  const summary = el(doc, "span", "cockpit-past-summary", view.retention != null ? `${view.count} \u00b7 kept ${view.retention}` : `${view.count}`);
+  summary.setAttribute("data-summary", "past");
+  header.appendChild(summary);
+  root.appendChild(header);
+  if (view.count === 0) {
+    const empty = el(doc, "div", "cockpit-past-empty", "No captured sessions yet.");
+    empty.setAttribute("data-empty", "true");
+    root.appendChild(empty);
+    host.appendChild(root);
+    return;
+  }
+  const table = el(doc, "table", "cockpit-past-table");
+  const thead = el(doc, "thead", "cockpit-past-thead");
+  const head = el(doc, "tr", "cockpit-past-head");
+  for (const label of ["session", "status", "size", "captured"]) head.appendChild(el(doc, "th", "cockpit-th", label));
+  thead.appendChild(head);
+  table.appendChild(thead);
+  const tbody = el(doc, "tbody", "cockpit-past-tbody");
+  for (const session of view.sessions) tbody.appendChild(sessionRow(doc, session, onReplay, activeStream));
+  table.appendChild(tbody);
+  root.appendChild(table);
+  host.appendChild(root);
+}
+
+/** Feed a fetched transcript's stored chunks through a resume-from-offset TerminalSession (static playback). */
+function replayTranscript(session, data) {
+  session.handle({ op: "subscribed", stream: data.stream, gap: data.gap, nextOffset: data.nextOffset });
+  for (const entry of data.entries ?? []) {
+    session.handle({ stream: data.stream, offset: entry.offset, chunk: entry.chunk });
+  }
+}
+
 // ── boot orchestration (mirrors app/agentic/cockpit/supply-boot.ts) ────────────────────────────
 
 /** An xterm.js-backed terminal sink mounted into `host`. */
@@ -219,6 +327,10 @@ function relaySocketFactory(url) {
  * @param {number} [opts.refreshMs] — poll interval (default 2000).
  * @param {number} [opts.staleAfterMs] — a worker is rendered "stale" once its last heartbeat is at
  *   least this many ms old (default 15000).
+ * @param {number} [opts.pastFetchTimeoutMs] — upper bound (ms) on a single past-sessions transcripts
+ *   fetch; the fetch is aborted past this so a hung endpoint can't wedge the past panel (default 15000).
+ * @param {string} [opts.transcriptsUrl] — the captured-session list endpoint (default
+ *   /app/api/agentic/transcripts) backing the always-on "past sessions" history + replay.
  * @returns a handle with `.dispose()`.
  */
 export function mountCockpit(host, opts = {}) {
@@ -229,6 +341,7 @@ export function mountCockpit(host, opts = {}) {
   }
   const doc = document;
   const reportUrl = opts.reportUrl ?? "/app/api/agentic/supply";
+  const transcriptsUrl = opts.transcriptsUrl ?? "/app/api/agentic/transcripts";
   const hookSecret = opts.hookSecret;
   const relayUrl = opts.relayUrl ?? defaultRelayUrl(opts.relayToken, opts.relayCapability);
   const refreshMs = opts.refreshMs ?? DEFAULT_REFRESH_MS;
@@ -239,20 +352,40 @@ export function mountCockpit(host, opts = {}) {
     throw new RangeError(`mountCockpit(opts.refreshMs): must be a positive safe integer, got ${refreshMs}.`);
   }
   const staleAfterMs = opts.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+  // Upper bound on a single "past sessions" transcripts fetch. refreshPast() is single-flight, so a
+  // fetch that HANGS (never settles) would otherwise leave `pastRefreshing` stuck true forever and
+  // permanently disable the past panel; a bounded (aborting) fetch clears the flag so the next poll retries.
+  const pastFetchTimeoutMs = opts.pastFetchTimeoutMs ?? DEFAULT_PAST_FETCH_TIMEOUT_MS;
+  if (!isPosInt(pastFetchTimeoutMs)) {
+    throw new RangeError(
+      `mountCockpit(opts.pastFetchTimeoutMs): must be a positive safe integer, got ${pastFetchTimeoutMs}.`,
+    );
+  }
   const connectRelay = relaySocketFactory(relayUrl);
   const onError = (err) => console.error("[cockpit]", err);
 
-  // Stable skeleton: a volatile list region the poll re-renders + a PERSISTENT terminal region a
-  // refresh never touches (so a drilled-in terminal survives a list refresh).
+  const jsonHeaders = () => {
+    const headers = { accept: "application/json" };
+    if (hookSecret) headers["x-hook-secret"] = hookSecret;
+    return headers;
+  };
+
+  // Stable skeleton: a volatile supply-list region + a volatile "past sessions" region the poll
+  // re-renders, and a PERSISTENT terminal region a refresh never touches (so a drilled-in/replayed
+  // terminal survives a list refresh). The terminal panel title distinguishes live vs replayed.
   host.replaceChildren();
   const shell = el(doc, "div", "cockpit-shell");
   const listRegion = el(doc, "div", "cockpit-supply-region");
+  const pastRegion = el(doc, "div", "cockpit-past-region");
   const terminalPanel = el(doc, "section", "cockpit-terminal");
-  terminalPanel.appendChild(el(doc, "h2", "cockpit-panel-title", "Worker terminal"));
+  terminalPanel.setAttribute("data-terminal-mode", "idle");
+  const terminalTitle = el(doc, "h2", "cockpit-panel-title", "Worker terminal");
+  terminalPanel.appendChild(terminalTitle);
   const terminalHost = el(doc, "div", "cockpit-terminal-host");
   terminalHost.setAttribute("data-terminal", "host");
   terminalPanel.appendChild(terminalHost);
   shell.appendChild(listRegion);
+  shell.appendChild(pastRegion);
   shell.appendChild(terminalPanel);
   host.appendChild(shell);
 
@@ -262,13 +395,36 @@ export function mountCockpit(host, opts = {}) {
   let generation = 0;
   let drill; // { stream, client }
   let terminal; // the current xterm sink
+  let mode; // "live" | "replay" | undefined
+  let shownStream;
+  // Bumped by every drillInto()/replayInto()/dispose() that claims the terminal region, so a slow
+  // replay fetch that resolves after a newer selection drops its result instead of clobbering it.
+  let opToken = 0;
+  // True while a refreshPast() fetch is outstanding, so the supply poll never stacks past-fetches
+  // against a slow/hung transcripts endpoint.
+  let pastRefreshing = false;
 
-  function drillInto(stream) {
-    if (disposed || drill?.stream === stream) return;
+  function setMode(next, stream) {
+    mode = next;
+    shownStream = stream;
+    terminalPanel.setAttribute("data-terminal-mode", next ?? "idle");
+    if (next === "live") terminalTitle.textContent = "Worker terminal — live";
+    else if (next === "replay") terminalTitle.textContent = "Worker terminal — replay (past session)";
+    else terminalTitle.textContent = "Worker terminal";
+  }
+
+  function teardownTerminal() {
     drill?.client.close();
     drill = undefined;
     terminal?.dispose?.();
     terminal = undefined;
+  }
+
+  function drillInto(stream) {
+    if (disposed || (mode === "live" && drill?.stream === stream)) return;
+    // Claim the terminal region: bump the op token so an in-flight replay drops its stale result.
+    opToken++;
+    teardownTerminal();
     try {
       terminalHost.replaceChildren();
       const sink = xtermSink(terminalHost);
@@ -283,18 +439,102 @@ export function mountCockpit(host, opts = {}) {
       session = new TerminalSession({ stream, sink, send: (message) => client.sendRelay(message) });
       client.open();
       drill = { stream, client };
+      setMode("live", stream);
+    } catch (err) {
+      // The new terminal failed to build after the prior one was torn down: reset the region to idle
+      // (and drop any partially-built terminal) so the UI never shows a stale "live"/"replay"
+      // indicator with nothing behind it — symmetric with replayInto(), which clears mode up-front.
+      teardownTerminal();
+      setMode(undefined, undefined);
+      onError(err);
+    }
+  }
+
+  async function replayInto(stream) {
+    if (disposed) return;
+    // Claim the terminal region under a fresh op token, captured for the post-fetch re-check below.
+    const token = ++opToken;
+    // Drop any live drill + prior terminal before fetching so replay never overlaps a live stream.
+    teardownTerminal();
+    setMode(undefined, undefined);
+    let data;
+    try {
+      // Bound the fetch: a transcript endpoint that never responds would otherwise leave replay() pending
+      // forever with an in-flight request and the terminal wedged out of live mode. Abort after
+      // pastFetchTimeoutMs so the fetch always settles (here, rejects) and this catch leaves mode idle.
+      const controller = new AbortController();
+      const abortTimer = setTimeout(() => controller.abort(), pastFetchTimeoutMs);
+      abortTimer.unref?.();
+      let res;
+      try {
+        res = await fetch(`${transcriptsUrl}/${encodeURIComponent(stream)}`, { headers: jsonHeaders(), signal: controller.signal });
+      } finally {
+        clearTimeout(abortTimer);
+      }
+      if (!res.ok) throw new Error(`transcript fetch failed: ${res.status}`);
+      data = await res.json();
+    } catch (err) {
+      onError(err);
+      return;
+    }
+    // A newer drill/replay (or dispose) claimed the terminal while this fetch was outstanding — drop
+    // the stale result rather than overwrite the newer selection with an out-of-date replay.
+    if (disposed || token !== opToken) return;
+    try {
+      terminalHost.replaceChildren();
+      const sink = xtermSink(terminalHost);
+      terminal = sink;
+      const session = new TerminalSession({ stream, sink, send: () => {}, from: data.from ?? 0 });
+      replayTranscript(session, data);
+      setMode("replay", stream);
+      void refreshPast();
     } catch (err) {
       onError(err);
     }
   }
 
+  async function refreshPast() {
+    // Single-flight: while one past-fetch is outstanding (including a hung one), skip starting another
+    // so the supply poll can't stack pending fetches against a slow/unresponsive transcripts endpoint.
+    if (pastRefreshing) return;
+    pastRefreshing = true;
+    try {
+      let report;
+      try {
+        // Bound the fetch: refreshPast() is single-flight, so a transcripts endpoint that never responds
+        // would otherwise wedge `pastRefreshing` true forever. Abort after pastFetchTimeoutMs so the fetch
+        // always settles (here, rejects), the finally clears the flag, and the next poll can retry.
+        const controller = new AbortController();
+        const abortTimer = setTimeout(() => controller.abort(), pastFetchTimeoutMs);
+        abortTimer.unref?.();
+        let res;
+        try {
+          res = await fetch(transcriptsUrl, { headers: jsonHeaders(), signal: controller.signal });
+        } finally {
+          clearTimeout(abortTimer);
+        }
+        if (!res.ok) throw new Error(`transcripts fetch failed: ${res.status}`);
+        report = await res.json();
+      } catch (err) {
+        onError(err);
+        return;
+      }
+      if (disposed) return;
+      try {
+        renderTranscripts(pastRegion, doc, transcriptsView(report), replayInto, mode === "replay" ? shownStream : undefined);
+      } catch (err) {
+        onError(err);
+      }
+    } finally {
+      pastRefreshing = false;
+    }
+  }
+
   async function refresh() {
     if (disposed) return;
     let report;
     try {
-      const headers = { accept: "application/json" };
-      if (hookSecret) headers["x-hook-secret"] = hookSecret;
-      const res = await fetch(reportUrl, { headers });
+      const res = await fetch(reportUrl, { headers: jsonHeaders() });
       if (!res.ok) throw new Error(`supply fetch failed: ${res.status}`);
       report = await res.json();
     } catch (err) {
@@ -307,6 +547,8 @@ export function mountCockpit(host, opts = {}) {
     } catch (err) {
       onError(err);
     }
+    // Fire-and-forget: a hung transcripts endpoint must never stall the supply poll's next tick.
+    void refreshPast();
   }
 
   function tick(gen) {
@@ -332,15 +574,14 @@ export function mountCockpit(host, opts = {}) {
   function dispose() {
     if (disposed) return;
     disposed = true;
+    opToken++;
     stop();
-    drill?.client.close();
-    drill = undefined;
-    terminal?.dispose?.();
-    terminal = undefined;
+    teardownTerminal();
+    setMode(undefined, undefined);
   }
 
   start();
-  return { start, stop, dispose, refresh, drill: drillInto };
+  return { start, stop, dispose, refresh, drill: drillInto, replay: replayInto };
 }
 
 /**

package/pages/cockpit.page.json

@@ -30,7 +30,7 @@
       "type": "text",
       "id": "intro",
       "props": {
-        "text": "The live worker/supply view: every connected worker grouped by leaf token, with family, host, current jobs, and liveness — sourced from the agentic presence registry. Drill into a worker to stream its terminal live over the relay; the terminal stays mounted across a list refresh and re-attaches (resume-from-offset) on reconnect. The same view renders embedded here (App View) and standalone on a phone. (The demand×supply matrix, missing-agent-type lights, and the diversity SLO are the enrolment epic's board — not shown here.)",
+        "text": "The live worker/supply view: every connected worker grouped by leaf token, with family, host, current jobs, and liveness — sourced from the agentic presence registry. Drill into a worker to stream its terminal live over the relay; the terminal stays mounted across a list refresh and re-attaches (resume-from-offset) on reconnect. Beside it, a \"past sessions\" history lists the durable transcripts agents flushed on completion — select one to replay its captured terminal statically into the same panel (the title distinguishes live vs replayed). The same view renders embedded here (App View) and standalone on a phone. (The demand×supply matrix, missing-agent-type lights, and the diversity SLO are the enrolment epic's board — not shown here.)",
         "variant": "sub"
       }
     },

package/prompts/review-round.md

@@ -48,20 +48,39 @@ Because several agents may run on the same host at once:
 
 ## What to do in a round
 
-1. **Read the latest review.** Fetch the newest Copilot review + its inline
-   comments on the PR (`gh pr view`, `gh api .../pulls/{n}/reviews`, `.../comments`).
+1. **Read the latest review AND every still-open thread.** Fetch the newest Copilot
+   review + its inline comments on the PR (`gh pr view`, `gh api .../pulls/{n}/reviews`,
+   `.../comments`). Then **also enumerate every UNRESOLVED review thread on the PR**,
+   not just the latest review's comments — findings accumulate as durable threads, so
+   an earlier round's comment stays open until someone resolves it, and the newest
+   review will **not** re-list it. Treat the full set of open threads as your backlog
+   for this round, not only the latest review:
+
+   ```sh
+   # Every open thread across ALL reviews (this is your real backlog, oldest included):
+   # `pageInfo{hasNextPage endCursor}` surfaces truncation AND gives you the cursor to page with: if
+   # `hasNextPage` is `true` there are >100 threads this page can't see — re-run passing that
+   # `endCursor` back as `$after` until `hasNextPage` is `false`; never treat one page as "every"
+   # thread. Omit `-F after=…` (leaving `$after` null) for the first page.
+   gh api graphql -f query='query($o:String!,$r:String!,$n:Int!,$after:String){repository(owner:$o,name:$r){
+     pullRequest(number:$n){reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor}nodes{id isResolved path line
+       comments(first:100){nodes{databaseId author{login} body}}}}}}}' -F o=OWNER -F r=REPO -F n=PR   # add -F after=END_CURSOR to page
+   ```
+
    Also read Copilot's **suppressed / low-confidence** advisories — the collapsed
    "low confidence" list Copilot folds into the **review body** (`.../reviews`
    `body`). These are NOT in the default inline-comment API set, so a plain
    `.../comments` read misses them; scan the review body for them explicitly.
    If `answer` is present, treat it as the human's decision on the escalation you
    raised last round and act on it first.
-2. **Triage each comment** into: *fix* (correct, worth doing), *nitpick* (apply
+2. **Triage each item** into: *fix* (correct, worth doing), *nitpick* (apply
    silently), *needs human input* (design/product/tradeoff you can't decide), or
-   *push back* (wrong / false positive — reply with evidence, make no change).
-   Triage the suppressed / low-confidence advisories the **same** way — but do not
-   treat "suppressed" as either automatically actionable or automatically ignorable:
-   if one is a **cheap, correct** robustness/correctness win, just do it (a
+   *push back* (wrong / false positive — reply with evidence, make no change). Triage
+   **every open thread from step 1**, including ones raised in earlier rounds that the
+   latest review did not repeat — do not skip a thread just because it is not in the
+   newest review. Triage the suppressed / low-confidence advisories the **same** way —
+   but do not treat "suppressed" as either automatically actionable or automatically
+   ignorable: if one is a **cheap, correct** robustness/correctness win, just do it (a
    *nitpick*); otherwise **decline it explicitly with a one-line rationale in your
    `summary`** (e.g. "declined suppressed advisory X — input already validated
    upstream at Y"). Never silently drop one.
@@ -93,6 +112,26 @@ Because several agents may run on the same host at once:
    # Resolve the thread whose databaseId matched the comment you handled:
    gh api graphql -f query='mutation($id:ID!){resolveReviewThread(input:{threadId:$id}){thread{isResolved}}}' -F id=THREAD_NODE_ID
    ```
+5a. **Acknowledge every suppressed / low-confidence advisory with a resolvable ack
+   thread.** Suppressed advisories live in the review **body**, not as inline
+   comment threads, so they cannot be resolved and Copilot **re-lists them every
+   round**. The process now *deterministically blocks convergence* until each one
+   carries a **resolved** acknowledgement, so a decision you only wrote into your
+   `summary` is invisible to the gate. For each suppressed advisory you applied or
+   declined (step 2), post a **new review comment thread** whose body contains the
+   verbatim marker **`nano-ack: <path>:<line>`** — copied exactly from Copilot's
+   bold `**<path>:<line>**` header for that advisory — then **resolve** that thread.
+   The gate matches on the marker **text**, so the thread may sit on any valid diff
+   line; only the exact `path:line` string must match. Example:
+
+   ```sh
+   # Post the ack thread (pick any changed line in the diff for path/line). Use the PR's real HEAD
+   # SHA as commit_id — `git rev-parse HEAD` can drift from the PR head; ask GitHub:
+   CID=$(gh api repos/OWNER/REPO/pulls/PR --jq .head.sha)
+   gh api repos/OWNER/REPO/pulls/PR/comments -f commit_id="$CID" -f path=PATH -F line=LINE -f side=RIGHT \
+     -f body='Applied. nano-ack: <path>:<line>'   # or: 'Declined, false positive — <reason>. nano-ack: <path>:<line>'
+   # Then resolve it exactly like any other thread (map its databaseId -> thread node id -> resolveReviewThread).
+   ```
 6. **Do NOT request, re-request, or remove the reviewer yourself.** Keeping
    Copilot attached is the **process's** job: a deterministic poller ensures a
    Copilot review is requested (idempotently) whenever this PR is waiting, and it
@@ -118,11 +157,18 @@ Consider the PR **converged** when the latest review has no actionable comment:
 - every new comment is a nitpick you already handled or intentionally declined,
   **or**
 - the only remaining items are suppressed / low-confidence advisories you have
-  triaged and either applied or declined-with-rationale (a suppressed advisory
-  you have recorded a decision on does **not** block convergence), **or**
+  triaged and either applied or declined-with-rationale **and acknowledged with a
+  resolved `nano-ack:` thread** (step 5a) — an advisory you have merely decided on
+  in prose still **blocks** convergence until its ack thread is resolved, **or**
 - Copilot is looping — reiterating a point you already addressed or pushed back
   on (two rounds of the same substantive point = converged).
 
+Returning `converged` is necessary but **not sufficient**: after you return it the
+process runs a deterministic gate that re-checks GitHub and will **block** convergence
+(routing to a human) while **any** review thread is unresolved or **any** suppressed
+advisory lacks a resolved `nano-ack:` thread. Resolve every thread and acknowledge
+every advisory (steps 5 + 5a) *before* you converge, or the PR bounces to a human.
+
 ### No review has landed yet — return `waiting`, do NOT escalate
 
 A PR is **not** converged merely because there are zero reviews and zero