@nanobpm/nano-workforce 0.111.1 → 0.112.0

package/workers/record-wave/worker.test.ts

@@ -274,3 +274,184 @@ test("record-wave runs trial merge for non-queue repos with populated heads", as
     restore();
   }
 });
+
+// ── Fail-closed forensics (issue #360) ─────────────────────────────────────────────────────────────
+// A slice that returns no machine-readable result is still coerced to terminal `blocked` here (the
+// escalation/answer decision already happened in the `implement` subprocess, before this aggregator).
+// But the aggregator must no longer LOSE information when it fails closed: it must (2) retain any PR the
+// agent demonstrably opened so the work is recoverable from the UI (on `draft_pr_key`, NOT `pr_key` —
+// a non-handed-off key on `pr_key` would wedge the delivery rollup), and (3) synthesise a reason so the
+// epic-detail Summary is never blank. Before #360 both were dropped (`pr_key = NULL`, `summary = NULL`).
+test("record-wave retains the PR and synthesises a summary for a no-result slice (issue #360)", async () => {
+  const rows: Row[] = [{ id: 1, plan_key: "owner/repo#64", task_id: "scaffold", status: "pending", wave: 0 }];
+  const { app } = fakeApp(rows);
+
+  await handler(
+    {
+      variables: {
+        planKey: "owner/repo#64",
+        currentWave: 0,
+        waveCount: 1,
+        waveTasks: [{ id: "scaffold" }],
+        // No `status` — the agent finished without a machine-readable result — but it DID open a PR.
+        waveResults: [{ pr: "owner/repo#84" }],
+      },
+    } as any,
+    app,
+  );
+
+  const row = rows[0] as unknown as Record<string, unknown>;
+  // Still fail-closed to `blocked` (we never assume the un-reported PR is mergeable) …
+  assertEquals(row.status, "blocked");
+  // … the PR the agent opened is retained on the DRAFT ref (recoverable from the UI as "Draft PR") …
+  assertEquals(row.draft_pr_key, "owner/repo#84");
+  // … but NOT on `pr_key`: a non-handed-off key there would read as a handed-off slice PR in
+  // `pollDelivery`/promotion rollups (MISSING → in-flight), wedging the epic "converging" forever.
+  assertEquals(row.pr_key ?? null, null);
+  // … and the reason is no longer blank.
+  assertEquals(typeof row.summary, "string");
+  assertEquals((row.summary as string).length > 0, true);
+});
+
+// A slice that DID return a machine-readable status which simply isn't a clean terminal (e.g. an
+// `escalated` slice the operator abandoned, or an SLA auto-abandon — the `implement` subprocess ends
+// without rewriting `status`) must not be misreported as "returned no machine-readable result": it did.
+test("record-wave synthesises an accurate reason for an escalated-then-abandoned slice, not the no-result reason (Copilot advisory, #360)", async () => {
+  const rows: Row[] = [{ id: 1, plan_key: "owner/repo#64", task_id: "scaffold", status: "pending", wave: 0 }];
+  const { app } = fakeApp(rows);
+
+  await handler(
+    {
+      variables: {
+        planKey: "owner/repo#64",
+        currentWave: 0,
+        waveCount: 1,
+        waveTasks: [{ id: "scaffold" }],
+        // The slice escalated; the operator abandoned it, so the subprocess ended with status "escalated".
+        waveResults: [{ status: "escalated" }],
+      },
+    } as any,
+    app,
+  );
+
+  const row = rows[0] as unknown as Record<string, unknown>;
+  assertEquals(row.status, "blocked");
+  const summary = row.summary as string;
+  assertEquals(typeof summary, "string");
+  // Must NOT claim a slice that returned a machine-readable status returned none …
+  assertEquals(summary.includes("no machine-readable result"), false);
+  // … and must name the status it actually reported.
+  assertEquals(summary.includes("escalated"), true);
+});
+
+// The twin invariant of the retention fix: a genuinely HANDED-OFF (`opened` with a usable key) slice
+// must still persist its PR on `pr_key` (the delivery-bearing column `pollDelivery`/promotion join on)
+// and NOT on the draft ref — otherwise a landed slice would never count toward epic delivery.
+test("record-wave persists a handed-off opened slice's PR on pr_key, not draft_pr_key (issue #360)", async () => {
+  const restore = installGithubStub("gh-merge");
+  try {
+    const rows: Row[] = [{ id: 1, plan_key: "owner/repo#64", task_id: "scaffold", status: "pending", wave: 0 }];
+    const { app } = fakeApp(rows);
+
+    await handler(
+      {
+        variables: {
+          planKey: "owner/repo#64",
+          currentWave: 0,
+          waveCount: 1,
+          waveTasks: [{ id: "scaffold" }],
+          waveResults: [{ status: "opened", pr: "owner/repo#84" }],
+        },
+      } as any,
+      app,
+    );
+
+    const row = rows[0] as unknown as Record<string, unknown>;
+    assertEquals(row.status, "opened");
+    assertEquals(row.pr_key, "owner/repo#84");
+    assertEquals(row.draft_pr_key ?? null, null);
+  } finally {
+    restore();
+  }
+});
+
+test("record-wave preserves the agent's own summary rather than overwriting it (issue #360)", async () => {
+  const rows: Row[] = [{ id: 1, plan_key: "owner/repo#64", task_id: "scaffold", status: "pending", wave: 0 }];
+  const { app } = fakeApp(rows);
+
+  await handler(
+    {
+      variables: {
+        planKey: "owner/repo#64",
+        currentWave: 0,
+        waveCount: 1,
+        waveTasks: [{ id: "scaffold" }],
+        waveResults: [{ status: "blocked", summary: "upstream API not ready" }],
+      },
+    } as any,
+    app,
+  );
+
+  const row = rows[0] as unknown as Record<string, unknown>;
+  assertEquals(row.status, "blocked");
+  // A genuine, machine-readable `blocked` with its own summary is left untouched — no synthesis.
+  assertEquals(row.summary, "upstream API not ready");
+});
+
+// The D2 conflict-scan (issue #58) is a deliberate over-approximation of the merge-exclusion graph:
+// a slice whose PR is retained (as a work-preserving DRAFT, NOT handed off) can still touch files a
+// sibling's PR touches, so omitting it would silently under-approximate the exclusions. The no-result
+// path (#360) newly retains such a draft PR (`retainedPr` → `draft_pr_key`), so it MUST be scanned too —
+// exactly like an `escalated` draft already is. This locks the scan set to every retained draft, not
+// only `opened`/`escalated` ones (Copilot advisory, record-wave/worker.ts:126).
+test("record-wave includes a no-result slice's retained draft PR in the D2 conflict scan (Copilot advisory, #360)", async () => {
+  const oldToken = process.env["GITHUB_TOKEN"];
+  const oldTransport = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const oldFetch = globalThis.fetch;
+  process.env["GITHUB_TOKEN"] = "test-token";
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = ((input: string | URL | Request) => {
+    const url = String(input);
+    // Both the handed-off `opened` PR and the retained no-result draft touch the SAME file, so the
+    // scan must derive exactly one exclusion edge between them — but only if BOTH are scanned.
+    if (url.includes("/files")) {
+      return Promise.resolve(new Response(JSON.stringify([{ filename: "src/shared.ts" }])));
+    }
+    return Promise.resolve(new Response("not found", { status: 404 }));
+  }) as typeof fetch;
+  try {
+    const rows: Row[] = [
+      { id: 1, plan_key: "owner/repo#64", task_id: "a", status: "pending", wave: 0 },
+      { id: 2, plan_key: "owner/repo#64", task_id: "b", status: "pending", wave: 0 },
+    ];
+    const { app } = fakeApp(rows);
+    const stores = (app.data as any).table("plan_merge_exclusions", "id");
+
+    await handler(
+      {
+        variables: {
+          planKey: "owner/repo#64",
+          currentWave: 0,
+          waveCount: 1,
+          waveTasks: [{ id: "a" }, { id: "b" }],
+          // `a` handed off an opened PR; `b` returned NO machine-readable status but DID open a PR
+          // (retained as a draft). Both touch src/shared.ts, so they merge-exclude each other.
+          waveResults: [
+            { status: "opened", pr: "owner/repo#101" },
+            { pr: "owner/repo#102" },
+          ],
+        },
+      } as any,
+      app,
+    );
+
+    const edges = await stores.find({});
+    assertEquals(edges.length, 1, "the no-result draft PR must be scanned, yielding one exclusion edge");
+  } finally {
+    if (oldToken == null) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = oldToken;
+    if (oldTransport == null) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = oldTransport;
+    globalThis.fetch = oldFetch;
+  }
+});

package/workers/record-wave/worker.ts

@@ -85,10 +85,11 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
 
   // The tasks with a concurrently-open PR in THIS wave — the set the D2 conflict-scan runs over
   // (cross-wave pairs are moot: the wave barrier merges earlier waves before later ones start).
-  // This includes both `opened` PRs (also handed off below) AND `escalated` tasks' work-preserving
-  // DRAFT PRs (feature.md): a draft's changed files can still overlap a sibling's, so omitting it
-  // would silently under-approximate the merge-exclusion graph (the scan is a deliberate
-  // over-approximation). Escalated drafts are scanned but NEVER handed off (not ready for review).
+  // This includes both `opened` PRs (also handed off below) AND any RETAINED work-preserving DRAFT
+  // PR — an `escalated` task's draft (feature.md) and the no-result path's retained draft (#360). A
+  // draft's changed files can still overlap a sibling's, so omitting it would silently
+  // under-approximate the merge-exclusion graph (the scan is a deliberate over-approximation).
+  // Retained drafts are scanned but NEVER handed off (not ready for review).
   const openedThisWave: { taskId: string; repo: string; number: number | string }[] = [];
   const readyHeadsThisWave: { repo: string; number: number | string }[] = [];
 
@@ -102,21 +103,51 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       : "blocked";
     const summary = str(res.summary);
     const prRef = str(res.pr);
-    // Only trust a PR ref when the agent reports it actually opened one.
+    // Only trust a PR ref as HANDOFF-ready when the agent reports it actually opened one.
     const parsed = status === "opened" && prRef ? parsePr(prRef) : null;
     // A keyless "opened" is effectively blocked: downstream waves gate on `opened` meaning
     // "this dependency has an opened PR", so an "opened" with no usable PR key must NOT satisfy
     // a dependant (it would let dependents run with a phantom, un-mergeable dependency).
     const effectiveStatus = status === "opened" && !parsed ? "blocked" : status;
+    // Issue #360 — a result that isn't a clean, machine-readable terminal (`opened`/`blocked`/
+    // `skipped`): a missing status, or an `escalated` that fell through the answer loop to abandon.
+    // This is the fail-closed path, and it must stop LOSING information:
+    //   (2) never discard a PR the agent demonstrably opened — persist its key on the row even for a
+    //       non-`opened` status so the work is recoverable from the UI, not just SQLite. It is NOT
+    //       handed off (only `parsed`/`opened` is, below) — a non-`opened` PR is not review-ready, so
+    //       it is retained on `draft_pr_key` (the escalation work-preserving column, surfaced as
+    //       "Draft PR" on the epic-detail page) and DELIBERATELY kept OUT of `pr_key`: `pollDelivery`
+    //       and the promotion rollup join every non-null `plan_tasks.pr_key` as a handed-off slice PR,
+    //       so an un-enrolled key there reads as MISSING → in-flight, wedging an otherwise-done epic
+    //       permanently "converging"/Active and blocking promotion (Copilot review, #360).
+    //   (3) synthesise a reason so a blocked slice is never blank on the epic-detail Summary, the way
+    //       record-trial-merge does for its own no-machine-readable-result case.
+    const unreadable = !rawStatus || !isWaveResultStatus(rawStatus);
+    const retainedPr = parsed ?? (prRef ? parsePr(prRef) : null);
+    // Distinguish a slice that reported NO status at all from one that reported a status which simply
+    // isn't a clean terminal (e.g. `escalated` that fell through the answer loop to operator Abandon /
+    // SLA auto-abandon — the subprocess ends without rewriting `status`). The latter DID return a
+    // machine-readable result, so the generic "no result" reason would misreport it.
+    const noResultSummary = !rawStatus
+      ? "The implementation agent returned no machine-readable result"
+      : `The implementation agent did not return a clean terminal result (reported status "${rawStatus}"), so the slice was treated as blocked`;
+    const effectiveSummary = summary ?? (unreadable ? noResultSummary : undefined);
 
     const row = byTaskId.get(taskId);
     if (row) {
       const patch: Partial<PlanTask> = { status: effectiveStatus, updated_at: ts };
-      if (summary !== undefined) patch.summary = summary;
+      if (effectiveSummary !== undefined) patch.summary = effectiveSummary;
       if (parsed?.prKey) {
+        // Handed-off/opened PR — the delivery-bearing key `pollDelivery`/promotion join on.
         patch.pr_key = parsed.prKey;
         // Keep the in-memory row current so a same-wave dependant (rare) sees the PR key.
         row.pr_key = parsed.prKey;
+      } else if (retainedPr?.prKey) {
+        // A PR the agent demonstrably opened but that was NOT handed off (blocked / escalated /
+        // keyless-"opened"): preserve it as a draft ref so the work stays recoverable from the UI,
+        // but keep it out of `pr_key` so it never wedges the delivery rollup (see comment above).
+        patch.draft_pr_key = retainedPr.prKey;
+        row.draft_pr_key = retainedPr.prKey;
       }
       await taskTable.update(row.id, patch);
     }
@@ -162,11 +193,13 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     }
 
     // Include this task's PR in the D2 conflict-scan set when it is concurrently open in the wave:
-    // an `opened` PR (also handed off below), OR an `escalated` task's work-preserving DRAFT PR
-    // (feature.md — `status: "escalated"` may carry the draft `pr` it opened to preserve work).
-    // The draft's changed files can overlap a sibling's, so scanning it keeps the merge-exclusion
-    // graph a conservative over-approximation instead of silently missing those overlaps.
-    const scanPr = parsed ?? (rawStatus === "escalated" && prRef ? parsePr(prRef) : null);
+    // an `opened` PR (also handed off below), OR ANY retained work-preserving DRAFT PR — an
+    // `escalated` task's draft (feature.md — `status: "escalated"` may carry the draft `pr` it
+    // opened) AND the no-result path's retained draft (#360, `retainedPr` → `draft_pr_key`). Any
+    // such draft's changed files can overlap a sibling's, so scanning every retained PR (not just
+    // `opened`/`escalated`) keeps the merge-exclusion graph a conservative over-approximation
+    // instead of silently missing those overlaps.
+    const scanPr = retainedPr;
     if (scanPr) {
       openedThisWave.push({ taskId, repo: scanPr.repo, number: scanPr.number });
     }

package/workers/record-wave-escalation/worker.test.ts

@@ -0,0 +1,95 @@
+// Unit coverage for pr.record-wave-escalation — the plan-fanout implement-stage escalation net (issue
+// #360). It runs on the `w_gw` "clean terminal?" gateway's `not clean` arm, BEFORE the shared
+// `feature-escalation` user task, and must:
+//   • pass through the agent's own answerable question when it declared a genuine escalation, but
+//   • SYNTHESISE an answerable question when the agent left none (a no-machine-readable result) so the
+//     parked task is never a dead end — the fix for the silent epic-death this issue reports, and
+//   • append the resolved question to the canonical `feature_escalations` audit log keyed by `planKey`
+//     (the plan-root IS the subject of an embedded slice), the source `pollUserTasks` reads (issue #358),
+//   • re-emit the resolved `question` so the `feature-escalation` form and the answer loop see it.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import handler, { NO_RESULT_QUESTION } from "./worker.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: tiny in-memory app double, mirrors record-feature-escalation.worker.test
+function fakeApp(): any {
+  const stores: Record<string, Record<string, unknown>[]> = {};
+  return {
+    stores,
+    data: {
+      table(name: string, key: string) {
+        const store = (stores[name] ??= []);
+        return {
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          get: (k: any) => Promise.resolve(store.find((r) => r[key] === k)),
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          find: (q: any) => Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          findOne: (q: any) =>
+            Promise.resolve(store.find((r) => Object.entries(q).every(([f, v]) => r[f] === v)) ?? null),
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          insert: (row: any) => {
+            store.push(row);
+            return Promise.resolve(store.length);
+          },
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          update: (k: any, patch: any) => {
+            const row = store.find((r) => r[key] === k);
+            if (row) Object.assign(row, patch);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+    log: noopLog(),
+  };
+}
+
+test("record-wave-escalation: a no-machine-readable result synthesises an answerable question and audits it (issue #360)", async () => {
+  const app = fakeApp();
+  // The agent finished with no status and no question — the exact failure that used to fall straight to
+  // terminal `blocked` and silently kill the epic. It must now become an answerable escalation.
+  const out = await handler(
+    { jobKey: "job-1", variables: { planKey: "owner/repo#64", status: undefined, question: undefined } } as never,
+    app,
+  );
+
+  assertEquals(out, { question: NO_RESULT_QUESTION });
+  assertEquals(app.stores.feature_escalations.length, 1);
+  assertEquals(app.stores.feature_escalations[0].feature_key, "owner/repo#64");
+  assertEquals(app.stores.feature_escalations[0].question, NO_RESULT_QUESTION);
+  assertEquals(app.stores.feature_escalations[0].job_key, "job-1");
+});
+
+test("record-wave-escalation: a genuine agent escalation passes its own question through unchanged (issue #360)", async () => {
+  const app = fakeApp();
+  const out = await handler(
+    { jobKey: "job-2", variables: { planKey: "owner/repo#64", status: "escalated", question: "Which auth library should the scaffold use?" } } as never,
+    app,
+  );
+
+  assertEquals(out, { question: "Which auth library should the scaffold use?" });
+  assertEquals(app.stores.feature_escalations[0].question, "Which auth library should the scaffold use?");
+});
+
+test("record-wave-escalation: an escalated status with a blank question is still given an answerable one (issue #360)", async () => {
+  // `escalated` with no usable question is as much a dead end as a no-result — the taxonomy classes it a
+  // NON-escalation, so without synthesis the parked task would show nothing to decide. Synthesise instead.
+  const app = fakeApp();
+  const out = await handler(
+    { jobKey: "job-3", variables: { planKey: "owner/repo#64", status: "escalated", question: "   " } } as never,
+    app,
+  );
+
+  assertEquals(out, { question: NO_RESULT_QUESTION });
+  assertEquals(app.stores.feature_escalations[0].question, NO_RESULT_QUESTION);
+});
+
+test("record-wave-escalation: a retried job (same jobKey) reuses its audit row, never duplicating (issue #360)", async () => {
+  const app = fakeApp();
+  const job = { jobKey: "job-retry", variables: { planKey: "owner/repo#64", status: undefined, question: undefined } } as never;
+  await handler(job, app);
+  await handler(job, app);
+  assertEquals(app.stores.feature_escalations.length, 1, "the retry reuses the row, no duplicate append");
+});

package/workers/record-wave-escalation/worker.ts

@@ -0,0 +1,69 @@
+// pr.record-wave-escalation — a plan-fanout wave slice did NOT return a clean terminal result, so its
+// `implement` subprocess routes here (the `w_gw` "clean terminal?" gateway's `not clean` arm) BEFORE
+// the `feature-escalation` user task is created. It is the plan-fanout analogue of feature.bpmn's
+// `record-feature-escalation`, extended with the no-result net of issue #360.
+//
+// The implement stage was the ONLY agent stage with no net for "I couldn't read the agent's result":
+//   • review rounds re-enter the durable review wait (app/roundResultDefault.ts),
+//   • trial merge raises an answerable human escalation (workers/record-trial-merge/worker.ts),
+//   • implement/wave coerced a missing status straight to terminal `blocked` — silently failing the
+//     epic and orphaning any PR the agent opened (issue #360).
+// This worker closes that gap by routing every non-clean-terminal slice onto the SAME
+// `feature-escalation` user task a genuine `status:"escalated"` already uses, so a human can enrol the
+// PR or abandon the slice instead of the epic dying with a blank reason.
+//
+// It does two things while the process variables are still in scope on the job:
+//   • synthesises an answerable `question` when the agent didn't provide one (a no-machine-readable
+//     result carries no question), mirroring record-trial-merge, and re-emits it as the `question`
+//     variable so the `feature-escalation` form and the poller both see it, and
+//   • appends that question to the append-only `feature_escalations` audit log keyed by `planKey` — the
+//     canonical, poller-readable source `pollUserTasks` reads to enrich the parked task's question on
+//     the Tasks inbox (issue #358). The plan-root embeds the slice as a multi-instance subprocess, so
+//     there is no standalone `feature_runs` row; the epic (plan) IS the subject, hence the `planKey`
+//     key. Capturing it HERE (not in the poller) is required because the WASM engine does not surface a
+//     user task's ioMapping-mapped local variables through the user-task query.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { classifyEscalation } from "../../app/escalationTaxonomy.ts";
+import { recordFeatureEscalation } from "../../app/feature.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
+
+// Input typed off the model data envelope (`RecordWaveEscalationIn` in plan-fanout.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.record-wave-escalation"];
+interface Out extends Record<string, unknown> {
+  question: string;
+}
+
+const str = (v: unknown): string | undefined =>
+  typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+
+// The answerable prompt synthesised when the agent left no usable question — the implement-stage
+// analogue of record-trial-merge's synthesised trial-merge question. It names the recoverable work (a
+// PR may exist on the slice's branch) and the two answers the `w_gw_answer` gateway routes on.
+const NO_RESULT_QUESTION =
+  'The implementation agent finished without a machine-readable result (no status was reported), so we cannot tell whether the slice succeeded. It may still have opened a PR (check for a branch targeting the epic base). Choose "Answer" and give guidance to re-run the slice — or choose "Abandon" to skip it and continue the epic.';
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const planKey = job.variables.planKey;
+  const rawQuestion = str(job.variables.question);
+  // The agent's own question is authoritative when it declared a real escalation with one; otherwise
+  // (a no-machine-readable result, or an escalation with a blank question) synthesise an answerable
+  // one so the parked task is never a dead end. Route through the single canonical taxonomy so this
+  // net can never drift from the tier logic every other raise site uses.
+  // A "task"-kind escalation is `decision-required` only when the agent left an answerable question, so
+  // this already covers the blank-question case; the extra `&& rawQuestion` is the type narrowing that lets
+  // us hand the string through without an assertion.
+  const agentEscalated = classifyEscalation({ kind: "task", status: job.variables.status, question: rawQuestion }) ===
+    "decision-required";
+  const question = agentEscalated && rawQuestion ? rawQuestion : NO_RESULT_QUESTION;
+
+  // Append to the canonical `feature_escalations` audit log (the surviving table `pollUserTasks` reads),
+  // keyed by `planKey` because the plan-root instance IS the subject of the embedded slice's escalation.
+  await recordFeatureEscalation(app.data, { featureKey: planKey, question, jobKey: job.jobKey });
+  app.log.info("record-wave-escalation", { planKey, synthesised: question === NO_RESULT_QUESTION });
+
+  // Re-emit the resolved question so the `feature-escalation` form (and the answer loop) see it.
+  return { question };
+};
+
+export default handler;
+export { NO_RESULT_QUESTION };