@nanobpm/nano-workforce 0.30.0 → 0.32.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# [0.32.0](https://github.com/nanobpm/nano-workforce/compare/v0.31.0...v0.32.0) (2026-08-09)
+
+
+### Features
+
+* **poller:** surface technical incidents on the PR row ([#95](https://github.com/nanobpm/nano-workforce/issues/95)) ([596153c](https://github.com/nanobpm/nano-workforce/commit/596153c0f58a0d511f4a7bac66896dab98a6a5c8)), closes [#94](https://github.com/nanobpm/nano-workforce/issues/94)
+
+# [0.31.0](https://github.com/nanobpm/nano-workforce/compare/v0.30.0...v0.31.0) (2026-08-09)
+
+
+### Bug Fixes
+
+* **retro:** record a blocked retro when the retro process fails to start ([#92](https://github.com/nanobpm/nano-workforce/issues/92)) ([22bf171](https://github.com/nanobpm/nano-workforce/commit/22bf17114160bcd269b26fe635afdcc44c249dbe)), closes [#84](https://github.com/nanobpm/nano-workforce/issues/84)
+* surface no-op plan-fanout epics as incidents instead of green ([#86](https://github.com/nanobpm/nano-workforce/issues/86)) ([#88](https://github.com/nanobpm/nano-workforce/issues/88)) ([8178aad](https://github.com/nanobpm/nano-workforce/commit/8178aad61fbf409990d331a4b08c786782d44cd1))
+
+
+### Features
+
+* **retro:** fold plan-review trace and task outcomes into the retro digest ([#91](https://github.com/nanobpm/nano-workforce/issues/91)) ([00d37e5](https://github.com/nanobpm/nano-workforce/commit/00d37e5a8c19238736d14b46401e7a3a41ee2083)), closes [#84](https://github.com/nanobpm/nano-workforce/issues/84) [#87](https://github.com/nanobpm/nano-workforce/issues/87) [#90](https://github.com/nanobpm/nano-workforce/issues/90)
+* surface plan_reviews audit trace on epic and home pages ([#89](https://github.com/nanobpm/nano-workforce/issues/89)) ([2abaa25](https://github.com/nanobpm/nano-workforce/commit/2abaa253ac5bdd4d31a7bee1a0de412e5df56aae)), closes [#87](https://github.com/nanobpm/nano-workforce/issues/87) [#87](https://github.com/nanobpm/nano-workforce/issues/87) [#87](https://github.com/nanobpm/nano-workforce/issues/87) [#87](https://github.com/nanobpm/nano-workforce/issues/87) [#87](https://github.com/nanobpm/nano-workforce/issues/87)
+
 # [0.30.0](https://github.com/nanobpm/nano-workforce/compare/v0.29.0...v0.30.0) (2026-08-09)
 
 

package/SPEC.md

@@ -420,7 +420,10 @@ Start(issue) → plan → record-plan → implement (parallel MI) → record-res
 - **`record-results`** — app worker `pr.record-results`. Zips `results` back onto
   `plan_tasks` by index, and for each opened `pr` calls the same idempotent
   `submitPr` as §4 — **the handoff**: every fleet-produced PR enrols into the
-  review-convergence loop. Sets `plans` status `done`.
+  review-convergence loop. On success it sets `plans` status `done`; if the epic
+  finalizes having opened **zero** PRs (empty plan, or every task blocked/skipped)
+  it raises a non-retryable `NO_WORK_DISPATCHED` incident instead of completing
+  green — a no-op run must not masquerade as success (issue #86).
 
 **Payloads are untyped** (no `nano:shapes`/`io.nanobpm.dataEnvelope`): the vocab is
 scalar-only and cannot express the `tasks`/`results` lists, so the workers self-type

package/app/plan.test.ts

@@ -53,8 +53,8 @@ Deno.test("valid positive integer → honoured", () => {
 //
 // `plan_reviews` is append-only and the review round is derived from `count(plan_reviews)`.
 // When `startPlan` re-plans a previously finished issue it must clear the prior review rows,
-// otherwise the stale count inflates the next round index and can trip `reviewExhausted` early,
-// bypassing the adversarial gate. This drives `startPlan` against an in-memory data layer and
+// otherwise the stale count inflates the next round index and can reach the review-round cap
+// early, bypassing the adversarial gate. This drives `startPlan` against an in-memory data layer and
 // asserts the `plan_reviews` rows for the plan key are gone after a re-plan.
 import { startPlan } from "./plan.ts";
 

package/app/plan.ts

@@ -150,8 +150,9 @@ export function positiveIntEnv(name: string, fallback: number): number {
   return Number.isInteger(n) && n > 0 ? n : fallback;
 }
 
-/** Max adversarial plan-review rounds before the fan-out proceeds regardless (so a reviewer that
- * never approves can't dead-lock the plan). The last round's findings are still recorded. */
+/** Max adversarial plan-review rounds. Reaching the cap WITHOUT approval is a hard failure: the
+ * fan-out raises a `PLAN_REJECTED` incident rather than dispatching an un-approved plan (issue
+ * #86). The last round's findings are still recorded. */
 export const MAX_PLAN_REVIEW_ROUNDS = positiveIntEnv("NANO_PLAN_REVIEW_ROUNDS", 3);
 
 /** A plan is "done" in exactly these states; everything else (planning, dispatched)
@@ -205,7 +206,7 @@ export async function startPlan(data: DataLayer, engine: EngineClient, parsed: P
     }
     // `plan_reviews` is append-only and the review round is derived from
     // `count(plan_reviews)`, so stale rows from the prior run would inflate the
-    // next round index and trip `reviewExhausted` early (bypassing the gate).
+    // next round index and reach the review-round cap early (bypassing the gate).
     // Clear them here — the table is keyed on `plan_key`, so one delete drops the
     // whole set (mirrors how record-plan clears `plan_task_deps`).
     await planReviews(data).delete(parsed.planKey);

package/app/retro.test.ts

@@ -97,6 +97,10 @@ function seedTask(stores: Record<string, any[]>, task: Record<string, unknown>)
 function seedPr(stores: Record<string, any[]>, pr_key: string, status: string) {
   (stores["pull_requests"] ??= []).push({ pr_key, status });
 }
+// deno-lint-ignore no-explicit-any
+function seedReview(stores: Record<string, any[]>, round: number, approved: number, findings: string | null) {
+  (stores["plan_reviews"] ??= []).push({ plan_key: PLAN, round, approved, findings, created_at: `t${round}`, job_key: null });
+}
 
 Deno.test("autoRetroEnabled: on by default; disabled by 0/false/off/no", () => {
   const prev = process.env.NANO_AUTO_RETRO;
@@ -177,10 +181,42 @@ Deno.test("gatherRetro: separates learnings from notes and folds in deltas", asy
   assertEquals(d.repo, "acme/widgets");
 });
 
+Deno.test("gatherRetro: folds in the plan-review trace and task-outcome shape", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: "t1", task_id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedTask(stores, { id: "t2", task_id: "t2", status: "skipped", pr_key: null });
+  seedTask(stores, { id: "t3", task_id: "t3", status: "opened", pr_key: "acme/widgets#11" });
+  // Two rejected rounds then an approval — out of order to prove the sort.
+  seedReview(stores, 1, 0, "still missing the migration ordering");
+  seedReview(stores, 0, 0, "task t2 depends on t3 but is sequenced first");
+  seedReview(stores, 2, 1, "");
+
+  const d = await gatherRetro(data, PLAN);
+  assertEquals(d.reviewRounds, 3);
+  assertEquals(d.planApproved, true);
+  assertEquals(d.reviewRejections.map((r) => r.round), [0, 1]);
+  assertEquals(d.reviewRejections[0].findings, "task t2 depends on t3 but is sequenced first");
+  assertEquals(d.taskOutcomes.total, 3);
+  assertEquals(d.taskOutcomes.byStatus, { opened: 2, skipped: 1 });
+});
+
+Deno.test("gatherRetro: no reviews → zero rounds, not approved, empty rejections", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  const d = await gatherRetro(data, PLAN);
+  assertEquals(d.reviewRounds, 0);
+  assertEquals(d.planApproved, false);
+  assertEquals(d.reviewRejections, []);
+  assertEquals(d.taskOutcomes, { total: 0, byStatus: {} });
+});
+
 Deno.test("renderRetroBrief: renders learnings + constraints; states 'none' with no learnings", () => {
   const empty = renderRetroBrief({
     planKey: PLAN, repo: "acme/widgets", issueUrl: "", title: null,
     learnings: [], touchedFiles: [], contractChanges: [], constraints: [], notes: [],
+    reviewRounds: 0, reviewRejections: [], planApproved: false,
+    taskOutcomes: { total: 0, byStatus: {} },
     counts: { learnings: 0, deltas: 0, notes: 0 },
   });
   assertStringIncludes(empty, "none");
@@ -192,20 +228,31 @@ Deno.test("renderRetroBrief: renders learnings + constraints; states 'none' with
     contractChanges: [{ taskId: "t1", change: "shape" }],
     constraints: [{ taskId: "t1", constraint: "must X" }],
     notes: [{ author_task: "t2", kind: "note", body: "watch the release lane" }],
+    reviewRounds: 2,
+    reviewRejections: [{ round: 0, findings: "wrong dependency order" }],
+    planApproved: true,
+    taskOutcomes: { total: 2, byStatus: { opened: 1, skipped: 1 } },
     counts: { learnings: 1, deltas: 1, notes: 1 },
   });
   assertStringIncludes(brief, "regen first");
   assertStringIncludes(brief, "must X");
   assertStringIncludes(brief, "watch the release lane");
   assertStringIncludes(brief, "acme/widgets");
+  assertStringIncludes(brief, "Plan review");
+  assertStringIncludes(brief, "wrong dependency order");
+  assertStringIncludes(brief, "Task outcomes");
 });
 
-Deno.test("isDigestEmpty: true only when there are no learnings, deltas, or notes", () => {
-  const base = { planKey: PLAN, repo: "", issueUrl: "", title: null, learnings: [], touchedFiles: [], contractChanges: [], constraints: [], notes: [] };
+Deno.test("isDigestEmpty: empty only with no learnings/deltas/notes AND no review rejections", () => {
+  const base = { planKey: PLAN, repo: "", issueUrl: "", title: null, learnings: [], touchedFiles: [], contractChanges: [], constraints: [], notes: [], reviewRounds: 0, reviewRejections: [], planApproved: false, taskOutcomes: { total: 0, byStatus: {} } };
   assert(isDigestEmpty({ ...base, counts: { learnings: 0, deltas: 0, notes: 0 } }));
   assert(!isDigestEmpty({ ...base, counts: { learnings: 1, deltas: 0, notes: 0 } }));
   assert(!isDigestEmpty({ ...base, counts: { learnings: 0, deltas: 2, notes: 0 } }));
   assert(!isDigestEmpty({ ...base, counts: { learnings: 0, deltas: 0, notes: 1 } }));
+  // A rejected review round is reflection material even with no learnings/deltas/notes.
+  assert(!isDigestEmpty({ ...base, reviewRounds: 2, reviewRejections: [{ round: 0, findings: "bad seq" }], counts: { learnings: 0, deltas: 0, notes: 0 } }));
+  // ...but task-outcome shape alone (a cleanly-approved plan) is not.
+  assert(isDigestEmpty({ ...base, reviewRounds: 1, planApproved: true, taskOutcomes: { total: 3, byStatus: { opened: 3 } }, counts: { learnings: 0, deltas: 0, notes: 0 } }));
 });
 
 Deno.test("recordRetro: inserts then updates the same plan_key row in place", async () => {
@@ -278,6 +325,55 @@ Deno.test("maybeStartRetro: starts the retro exactly once when the last PR lands
   assertEquals(started.length, 1, "fire-once guard");
 });
 
+Deno.test("maybeStartRetro: a createInstance failure records a blocked retro (fire-once guard already consumed)", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedPr(stores, "acme/widgets#10", "merged");
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "learning", body: "regen first" });
+  // deno-lint-ignore no-explicit-any require-await
+  const engine = { async createInstance() { throw new Error("gateway down"); } } as any as EngineClient;
+
+  const r = await maybeStartRetro(data, engine, "acme/widgets#10");
+  assertEquals(r, { started: false, planKey: PLAN, reason: "start-failed" });
+  // The guard is consumed (stamp + claim), so it will never retry...
+  assert(stores["plans"][0].retro_started_at, "retro_started_at is stamped");
+  assertEquals(stores["plan_retro_starts"].length, 1);
+  // ...but the failure is now visible as a blocked retro rather than a silent gap.
+  assertEquals(stores["plan_retros"].length, 1);
+  assertEquals(stores["plan_retros"][0].status, "blocked");
+  assertEquals(stores["plan_retros"][0].pr_key, null);
+  assertStringIncludes(String(stores["plan_retros"][0].summary), "gateway down");
+});
+
+Deno.test("maybeStartRetro: a secondary blocked-retro persistence failure still returns start-failed (not error)", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedPr(stores, "acme/widgets#10", "merged");
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "learning", body: "regen first" });
+  // deno-lint-ignore no-explicit-any require-await
+  const engine = { async createInstance() { throw new Error("gateway down"); } } as any as EngineClient;
+  // recordRetro rethrows non-unique DB errors; simulate the blocked-retro insert hitting a
+  // FOREIGN KEY failure so the persistence in the createInstance-failure handler throws.
+  // deno-lint-ignore no-explicit-any
+  const failingData = {
+    // deno-lint-ignore no-explicit-any
+    table: (name: string, pk?: string) => {
+      const t = (data as any).table(name, pk);
+      if (name !== "plan_retros") return t;
+      return { ...t, insert: () => Promise.reject(new Error("FOREIGN KEY constraint failed")) };
+    },
+  } as any as DataLayer;
+
+  const r = await maybeStartRetro(failingData, engine, "acme/widgets#10");
+  // The secondary persistence failure must NOT be masked as `error` — the guard is still consumed,
+  // so the caller must see `start-failed`, and no phantom retro row is written.
+  assertEquals(r, { started: false, planKey: PLAN, reason: "start-failed" });
+  assert(stores["plans"][0].retro_started_at, "retro_started_at is stamped");
+  assertEquals(stores["plan_retros"].length, 0);
+});
+
 Deno.test("maybeStartRetro: a pre-claimed retro start does not start a duplicate process", async () => {
   const { data, stores } = memData();
   seedPlan(stores);
@@ -323,6 +419,23 @@ Deno.test("maybeStartRetro: complete but empty → records a skipped retro, does
   assertEquals(stores["plan_retros"][0].status, "skipped");
 });
 
+Deno.test("maybeStartRetro: a rejected review round alone is enough to fire the retro", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedPr(stores, "acme/widgets#10", "merged");
+  // No learnings/deltas/notes — only the plan-review trace carries a rejection.
+  seedReview(stores, 0, 0, "task ordering is wrong");
+  seedReview(stores, 1, 1, "");
+  const { engine, started } = fakeEngine();
+
+  const r = await maybeStartRetro(data, engine, "acme/widgets#10");
+  assertEquals(r.started, true);
+  assertEquals(r.planKey, PLAN);
+  assertEquals(started.length, 1);
+  assert(stores["plans"][0].retro_started_at, "retro_started_at must be stamped");
+});
+
 Deno.test("maybeStartRetro: a PR not part of any plan is a no-op", async () => {
   const { data } = memData();
   const { engine, started } = fakeEngine();

package/app/retro.ts

@@ -14,7 +14,7 @@
 // Data access goes through the record gateway (`data.table`), never hand-written SQL — matching
 // app/plan.ts, app/blackboard.ts, and app/taskDelta.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
-import { planTasks } from "./plan.ts";
+import { planReviews, planTasks } from "./plan.ts";
 import { isUniqueViolation, readBlackboard } from "./blackboard.ts";
 import { aggregateEpicDeltas } from "./taskDelta.ts";
 import { TERMINAL_STATUSES } from "./service.ts";
@@ -92,12 +92,24 @@ export interface RetroDigest {
   contractChanges: { taskId: string; change: string }[];
   constraints: { taskId: string; constraint: string }[];
   notes: { author_task: string; kind: string; body: string }[];
+  // Plan-review trace (006_plan_review.sql): how many adversarial review rounds the plan needed
+  // before fan-out, and the critique from every rejected round — the "what was wrong with the
+  // first cut of the decomposition" signal, which is prime retro material even when implementers
+  // posted no learnings of their own. `planApproved` reflects the final round's verdict.
+  reviewRounds: number;
+  reviewRejections: { round: number; findings: string }[];
+  planApproved: boolean;
+  // Execution shape: how the plan's tasks actually resolved (opened a PR, were skipped/blocked,
+  // etc.). Lets the retro reason over decomposition accuracy — e.g. a high skipped/blocked ratio
+  // hints the plan over-decomposed.
+  taskOutcomes: { total: number; byStatus: Record<string, number> };
   counts: { learnings: number; deltas: number; notes: number };
 }
 
 /** Gather a plan's reflection material: the `learning` blackboard entries (the headline), plus the
- * task-delta rollup (contract changes, discovered constraints, cross-slice file touches) and any
- * other non-learning blackboard notes for colour. Reads only — no writes. */
+ * task-delta rollup (contract changes, discovered constraints, cross-slice file touches), the
+ * plan-review trace (rounds + rejection findings), the task-outcome shape, and any other
+ * non-learning blackboard notes for colour. Reads only — no writes. */
 export async function gatherRetro(data: DataLayer, planKey: string): Promise<RetroDigest> {
   const plan = await plansTbl(data).get(planKey);
   const entries = await readBlackboard(data, planKey);
@@ -108,6 +120,22 @@ export async function gatherRetro(data: DataLayer, planKey: string): Promise<Ret
     .filter((e) => e.kind !== "learning")
     .map((e) => ({ author_task: e.author_task, kind: e.kind, body: e.body }));
   const deltas = await aggregateEpicDeltas(data, planKey);
+
+  // Plan-review trace, ordered by round. A rejected round is `approved === 0`; only rounds that
+  // carry findings are worth quoting (an empty rejection has nothing to teach).
+  const reviews = (await planReviews(data).find({ plan_key: planKey }))
+    .slice()
+    .sort((a, b) => a.round - b.round);
+  const reviewRejections = reviews
+    .filter((r) => r.approved === 0 && (r.findings ?? "").trim() !== "")
+    .map((r) => ({ round: r.round, findings: r.findings as string }));
+  const planApproved = reviews.length > 0 && reviews[reviews.length - 1].approved === 1;
+
+  // Task-outcome shape (counts by final status).
+  const tasks = await planTasks(data).find({ plan_key: planKey });
+  const byStatus: Record<string, number> = {};
+  for (const t of tasks) byStatus[t.status] = (byStatus[t.status] ?? 0) + 1;
+
   return {
     planKey,
     repo: plan?.repo ?? planKey.split("#")[0] ?? "",
@@ -118,6 +146,10 @@ export async function gatherRetro(data: DataLayer, planKey: string): Promise<Ret
     contractChanges: deltas.contractChanges,
     constraints: deltas.constraints,
     notes,
+    reviewRounds: reviews.length,
+    reviewRejections,
+    planApproved,
+    taskOutcomes: { total: tasks.length, byStatus },
     counts: {
       learnings: learnings.length,
       deltas: deltas.deltas.length,
@@ -139,8 +171,29 @@ export function renderRetroBrief(d: RetroDigest): string {
     `Target repo: **${d.repo}**${d.issueUrl ? ` · issue: ${d.issueUrl}` : ""}`,
     d.title ? `Epic: ${d.title}` : "",
     "",
-    `### Learnings agents posted while implementing (${d.learnings.length})`,
+    `### Plan review — ${d.reviewRounds} round(s), ${d.planApproved ? "approved" : "not approved"}`,
   ];
+  if (d.reviewRejections.length === 0) {
+    lines.push(
+      d.reviewRounds === 0
+        ? "_(no review rounds recorded)_"
+        : "_(approved with no recorded rejections)_",
+    );
+  } else {
+    lines.push(`The plan was revised after ${d.reviewRejections.length} rejected round(s):`);
+    for (const r of d.reviewRejections) lines.push(`- **round ${r.round}**: ${r.findings}`);
+  }
+  if (d.taskOutcomes.total > 0) {
+    const shape = Object.entries(d.taskOutcomes.byStatus)
+      .sort((a, b) => a[0].localeCompare(b[0]))
+      .map(([s, n]) => `${s}: ${n}`)
+      .join(", ");
+    lines.push("", `### Task outcomes (${d.taskOutcomes.total} task(s))`, shape);
+  }
+  lines.push(
+    "",
+    `### Learnings agents posted while implementing (${d.learnings.length})`,
+  );
   if (d.learnings.length === 0) {
     lines.push("_(none — agents posted no `learning` entries for this epic)_");
   } else {
@@ -164,9 +217,14 @@ export function renderRetroBrief(d: RetroDigest): string {
   return lines.join("\n");
 }
 
-/** True when a digest carries nothing worth an agent run — no learnings, no deltas, no notes. */
+/** True when a digest carries nothing worth an agent run. A plan is worth retrospecting when
+ * implementers shared material (learnings/deltas/notes) OR the plan itself needed revision — a
+ * rejected review round's findings are reflection material in their own right, even when no
+ * learning was posted. (Task-outcome shape alone is NOT: a cleanly-approved plan whose tasks all
+ * ran has nothing to teach.) */
 export function isDigestEmpty(d: RetroDigest): boolean {
-  return d.counts.learnings === 0 && d.counts.deltas === 0 && d.counts.notes === 0;
+  return d.counts.learnings === 0 && d.counts.deltas === 0 && d.counts.notes === 0 &&
+    d.reviewRejections.length === 0;
 }
 
 /** The persisted retro shape (written by pr.retro-record). */
@@ -264,14 +322,40 @@ export async function maybeStartRetro(
     // Stamp before starting so restarts/retries can take the cheap already-started path.
     await plansTbl(data).update(planKey, { retro_started_at: now(), updated_at: now() });
 
-    const { processInstanceKey } = await engine.createInstance({
-      processDefinitionId: RETRO_PROCESS_ID,
-      variables: {
-        planKey,
-        repo: digest.repo,
-        issueUrl: digest.issueUrl,
-      },
-    });
+    let processInstanceKey: string | number | undefined;
+    try {
+      ({ processInstanceKey } = await engine.createInstance({
+        processDefinitionId: RETRO_PROCESS_ID,
+        variables: {
+          planKey,
+          repo: digest.repo,
+          issueUrl: digest.issueUrl,
+        },
+      }));
+    } catch (err) {
+      // The fire-once guard is already consumed (retro_started_at stamped, plan_retro_starts
+      // claimed), so this plan will never re-enter the start path. If we returned here with no
+      // record, the epic surface would show a plan that "started a retro" with nothing to show and
+      // no way to retry. Persist a `blocked` retro instead so the failure stays visible and the
+      // system state is consistent. Recording must not mask the original error in the log.
+      log?.("error", `retro: could not start process for epic ${planKey}`, { err: String(err) });
+      // Persisting the blocked record is best-effort: recordRetro rethrows non-unique DB errors, and
+      // if that escaped here it would fall through to the outer catch and return `error` instead of
+      // `start-failed` — reintroducing the very silent-gap failure this path guards against (guard
+      // consumed, no durable record). Swallow a secondary persistence failure and log it separately
+      // so the createInstance failure path always reports `start-failed`.
+      try {
+        await recordRetro(data, planKey, {
+          status: "blocked",
+          summary: `Retro process could not be started: ${String(err)}`,
+        });
+      } catch (persistErr) {
+        log?.("error", `retro: could not persist blocked retro for epic ${planKey}`, {
+          err: String(persistErr),
+        });
+      }
+      return { started: false, planKey, reason: "start-failed" };
+    }
     log?.("info", `retro: started for epic ${planKey}`, { processInstanceKey, learnings: digest.counts.learnings });
     return { started: true, planKey };
   } catch (err) {

package/app/service.test.ts

@@ -6,13 +6,14 @@
 // loop already guards in `startPlan`). Drives `submitPr` against an in-memory data layer with the
 // GitHub transport forced off so it is hermetic.
 import { assertEquals } from "jsr:@std/assert@1";
-import { submitPr } from "./service.ts";
+import { pollIncidentsImpl, submitPr } from "./service.ts";
 
 // deno-lint-ignore no-explicit-any
 function memTable(rows: any[], key: string) {
   return {
     // deno-lint-ignore no-explicit-any
     get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    all: () => Promise.resolve([...rows]),
     // deno-lint-ignore no-explicit-any
     find: (q: any) =>
       Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
@@ -99,3 +100,154 @@ Deno.test("re-submit of a cancelled PR clears stale open escalations + the denor
     assertEquals(pr.process_key, "PI-9");
   });
 });
+
+// Red/green regression for technical-incident surfacing (issue #94). A convergence/merge instance
+// can hit an engine incident that parks the token; until `pollIncidents` nothing on the PR row
+// reflected it, so the grid kept showing "converging" while the run was dead in the water. This
+// drives the pass's reconciliation core against a stubbed `/v2/incidents/search`:
+//   1. an ACTIVE incident is mirrored onto `incident_key` + `incident_message` (status untouched),
+//   2. once the engine reports no active incident, the columns are cleared idempotently,
+//   3. a PR with no live instance (no process_key / terminal status) is never queried and any
+//      stale incident on it is cleared.
+function incidentFetch(byInstance: Record<string, unknown[]>) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    if (!u.endsWith("/incidents/search")) {
+      throw new Error(`unexpected fetch: ${u}`);
+    }
+    const body = JSON.parse(String(init?.body ?? "{}")) as {
+      filter?: { processInstanceKey?: string };
+    };
+    const items = byInstance[body.filter?.processInstanceKey ?? ""] ?? [];
+    return Promise.resolve(
+      new Response(JSON.stringify({ items }), { status: 200, headers: { "content-type": "application/json" } }),
+    );
+  };
+}
+
+Deno.test("pollIncidents mirrors an ACTIVE incident onto the PR row, then clears it, leaving status untouched", async () => {
+  const row = {
+    pr_key: "owner/repo#7",
+    repo: "owner/repo",
+    number: 7,
+    status: "converging",
+    process_key: "PI-7",
+    incident_key: null as string | null,
+    incident_message: null as string | null,
+    updated_at: "t0",
+  };
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [row], key: "pr_key" },
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    // deno-lint-ignore no-explicit-any
+  } as any;
+  const headers = { "content-type": "application/json" };
+
+  const prevFetch = globalThis.fetch;
+
+  // Red-ish: with an ACTIVE incident on the instance, the pass must surface it (before this
+  // feature the columns stayed null and the incident was invisible).
+  globalThis.fetch = incidentFetch({
+    "PI-7": [{ incidentKey: "INC-1", errorMessage: "boom: unhandled error", state: "ACTIVE", creationTime: "2024-01-01T00:00:00Z" }],
+  }) as typeof fetch;
+  try {
+    await pollIncidentsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(row.incident_key, "INC-1");
+  assertEquals(row.incident_message, "boom: unhandled error");
+  assertEquals(row.status, "converging"); // orthogonal: status is never touched
+
+  // Green: once the engine reports no active incident, the columns clear idempotently.
+  globalThis.fetch = incidentFetch({ "PI-7": [] }) as typeof fetch;
+  try {
+    await pollIncidentsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(row.incident_key, null);
+  assertEquals(row.incident_message, null);
+  assertEquals(row.status, "converging");
+});
+
+Deno.test("pollIncidents never queries a PR with no live instance and clears any stale incident", async () => {
+  const noKey = {
+    pr_key: "owner/repo#8",
+    status: "converging",
+    process_key: null as string | null,
+    incident_key: "STALE-A",
+    incident_message: "left over",
+    updated_at: "t0",
+  };
+  const terminal = {
+    pr_key: "owner/repo#9",
+    status: "merged",
+    process_key: "PI-9",
+    incident_key: "STALE-B",
+    incident_message: "left over",
+    updated_at: "t0",
+  };
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [noKey, terminal], key: "pr_key" },
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    // deno-lint-ignore no-explicit-any
+  } as any;
+  const headers = { "content-type": "application/json" };
+
+  const prevFetch = globalThis.fetch;
+  // Any fetch here is a bug — neither PR has a live instance to inspect.
+  globalThis.fetch = (() => {
+    throw new Error("pollIncidents must not query a PR with no live instance");
+  }) as typeof fetch;
+  try {
+    await pollIncidentsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(noKey.incident_key, null);
+  assertEquals(noKey.incident_message, null);
+  assertEquals(terminal.incident_key, null);
+  assertEquals(terminal.incident_message, null);
+});
+
+Deno.test("pollIncidents picks the oldest incident by creationTime, sorting a missing timestamp last", async () => {
+  const row = {
+    pr_key: "owner/repo#11",
+    status: "converging",
+    process_key: "PI-11",
+    incident_key: null as string | null,
+    incident_message: null as string | null,
+    updated_at: "t0",
+  };
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [row], key: "pr_key" },
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    // deno-lint-ignore no-explicit-any
+  } as any;
+  const headers = { "content-type": "application/json" };
+
+  const prevFetch = globalThis.fetch;
+  // A no-`creationTime` incident must not masquerade as the oldest (empty-string sort bug): the
+  // real earliest ISO timestamp wins even when a timestamp-less incident is returned first.
+  globalThis.fetch = incidentFetch({
+    "PI-11": [
+      { incidentKey: "INC-NOTS", errorMessage: "no timestamp", state: "ACTIVE" },
+      { incidentKey: "INC-OLD", errorMessage: "the first fault", state: "ACTIVE", creationTime: "2024-01-01T00:00:00Z" },
+      { incidentKey: "INC-NEW", errorMessage: "a later fault", state: "ACTIVE", creationTime: "2024-06-01T00:00:00Z" },
+    ],
+  }) as typeof fetch;
+  try {
+    await pollIncidentsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(row.incident_key, "INC-OLD");
+  assertEquals(row.incident_message, "the first fault");
+});