@nanobpm/nano-workforce 0.26.0

package/workers/record-plan-review/worker.ts

@@ -0,0 +1,92 @@
+// pr.record-plan-review — record one adversarial plan-review round and decide whether the
+// fan-out proceeds or the planner revises (issue: gate the plan before dispatch).
+//
+// The `senior:plan-review` agent critiqued the levelized plan and emitted `{ approved, findings }`.
+// This worker:
+//   • derives the current round from the append-only `plan_reviews` log (no counter variable),
+//     using the engine jobKey as an idempotency guard so a retried job reuses its row,
+//   • records this round's verdict + findings,
+//   • decides the loop: `planApproved` (reviewer said yes) and `reviewExhausted` (the round cap
+//     is reached, so we proceed regardless rather than dead-lock on a reviewer that never
+//     approves), and re-emits the findings as `planFindings` so a revise round feeds the planner.
+//
+// The BPMN gateway proceeds to `select-wave` when `planApproved or reviewExhausted`, else loops
+// back to `plan`. A missing/ambiguous `approved` is treated as NOT approved (revise) — but the
+// round cap still bounds the loop, so the plan can never wedge.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { MAX_PLAN_REVIEW_ROUNDS, type PlanReview, planReviews } from "../../app/plan.ts";
+
+interface In extends Record<string, unknown> {
+  planKey: string;
+  approved?: unknown;
+  findings?: unknown;
+}
+interface Out extends Record<string, unknown> {
+  planApproved: boolean;
+  reviewExhausted: boolean;
+  planFindings: string;
+}
+
+// Only an explicit boolean-true (or the string "true") approves; anything else — including a
+// missing verdict — means revise. Bounded by the round cap, so this can't loop forever.
+const isApproved = (v: unknown): boolean =>
+  v === true || (typeof v === "string" && v.trim().toLowerCase() === "true");
+
+export const str = (v: unknown): string => {
+  if (typeof v === "string") return v;
+  if (v == null) return "";
+  // JSON.stringify can throw (BigInt, circular refs) or return undefined (functions/symbols).
+  // Never let a bad variable fail the whole job — fall back to String(v).
+  try {
+    return JSON.stringify(v) ?? String(v);
+  } catch {
+    return String(v);
+  }
+};
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const planKey = job.variables.planKey;
+  const approved = isApproved(job.variables.approved);
+  const findings = str(job.variables.findings).trim();
+  const ts = new Date().toISOString();
+  const jobKey = job.jobKey;
+
+  const reviews = planReviews(app.data);
+
+  // Idempotency guard: deriving the round from count(plan_reviews) is not retry-safe on its own.
+  // A job retried after the insert (crash/timeout post-write) re-runs with the SAME jobKey — if
+  // this job already recorded a row, reuse it rather than appending a duplicate, which would
+  // inflate the count and trip `reviewExhausted` early. Otherwise this is the first attempt:
+  // derive the 0-based next round from the append-only log and record it under this jobKey.
+  const recorded: PlanReview = (await reviews.findOne({ plan_key: planKey, job_key: jobKey })) ??
+    await (async () => {
+      const round = await reviews.count({ plan_key: planKey }); // 0-based: next round index
+      const row: PlanReview = {
+        plan_key: planKey,
+        round,
+        approved: approved ? 1 : 0,
+        findings: findings || null,
+        created_at: ts,
+        job_key: jobKey,
+      };
+      await reviews.insert(row);
+      return row;
+    })();
+
+  const round = recorded.round;
+  const roundApproved = recorded.approved === 1;
+  const roundFindings = recorded.findings ?? "";
+
+  // Exhausted once this round is the last permitted one (round is 0-based).
+  const reviewExhausted = round + 1 >= MAX_PLAN_REVIEW_ROUNDS;
+  if (!roundApproved) {
+    app.log(reviewExhausted ? "warn" : "info", `record-plan-review: ${planKey} round ${round}`, {
+      approved: roundApproved,
+      reviewExhausted,
+    });
+  }
+
+  return { planApproved: roundApproved, reviewExhausted, planFindings: roundFindings };
+};
+
+export default handler;

package/workers/record-results/worker.ts

@@ -0,0 +1,30 @@
+// pr.record-results — the wave loop has finished; finalize the plan (issue #20).
+//
+// PR enrollment now happens per wave in `pr.record-wave` (so later waves can declare earlier
+// waves' PRs as dependencies), leaving this worker as the terminal finalizer: it summarizes the
+// plan from `plan_tasks` and marks it `done`. It reads no `results` — every task's outcome was
+// already recorded by `record-wave` (opened / blocked) or `select-wave` (skipped).
+import type { AppJobHandler } from "@nanobpm/urban";
+import { planTasks } from "../../app/plan.ts";
+
+interface In extends Record<string, unknown> {
+  planKey: string;
+}
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  const { planKey } = job.variables;
+  const ts = new Date().toISOString();
+
+  const rows = await planTasks(app.data).find({ plan_key: planKey });
+  const opened = rows.filter((r) => r.status === "opened").length;
+
+  const patch: Record<string, unknown> = { status: "done", updated_at: ts };
+  // When the planner emitted no tasks, `record-plan` already set a meaningful outcome (its
+  // note) and moved the plan to `done`. Preserve it rather than overwriting with "0 PR(s)…".
+  if (rows.length > 0) patch.outcome = `${opened} PR(s) dispatched to convergence`;
+  await app.data.table("plans", "plan_key").update(planKey, patch);
+
+  return {};
+};
+
+export default handler;

package/workers/record-trial-merge/worker.test.ts

@@ -0,0 +1,104 @@
+import { assertEquals, assertStringIncludes } from "jsr:@std/assert@1";
+import handler, { parseResult } from "./worker.ts";
+
+function fakeApp() {
+  const inserts: Record<string, unknown[]> = { plan_trial_merges: [] };
+  const app = {
+    data: {
+      table(name: string, _key: string) {
+        return {
+          // deno-lint-ignore require-await
+          async find(_q: unknown) {
+            return [];
+          },
+          // deno-lint-ignore require-await
+          async insert(row: unknown) {
+            (inserts[name] ??= []).push(row);
+            return 7;
+          },
+          // deno-lint-ignore require-await
+          async update(_key: unknown, _patch: unknown) {},
+        };
+      },
+    },
+    log: () => undefined,
+  };
+  return { app, inserts };
+}
+
+Deno.test("record-trial-merge shapes clean results as proceed", async () => {
+  const { app, inserts } = fakeApp();
+  const out = await handler(
+    // deno-lint-ignore no-explicit-any
+    { key: 11, variables: { planKey: "o/r#69", currentWave: 2, result: "clean", summary: "green" } } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  ) as Record<string, unknown>;
+
+  assertEquals(out.trialMergeRed, false);
+  assertEquals(inserts.plan_trial_merges.length, 1);
+  // deno-lint-ignore no-explicit-any
+  assertEquals((inserts.plan_trial_merges[0] as any).result, "clean");
+});
+
+Deno.test("parseResult trims valid agent result strings", () => {
+  assertEquals(parseResult("clean\n"), "clean");
+  assertEquals(parseResult(" merge-conflict "), "merge-conflict");
+  assertEquals(parseResult("unknown"), "suite-failed");
+});
+
+Deno.test("record-trial-merge escalates only suite-failed results", async () => {
+  const { app } = fakeApp();
+  const out = await handler(
+    // deno-lint-ignore no-explicit-any
+    {
+      key: 12,
+      variables: {
+        planKey: "o/r#69",
+        currentWave: 3,
+        result: "suite-failed",
+        summary: "combined test failed",
+        failing: ["integration suite"],
+      },
+    } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  ) as Record<string, unknown>;
+
+  assertEquals(out.trialMergeRed, true);
+  assertEquals(out.task, { id: "trial-merge-wave-3", title: "Trial merge gate for wave 3" });
+  assertStringIncludes(String(out.question ?? ""), "combined test failed");
+  assertStringIncludes(String(out.question ?? ""), "proceed");
+});
+
+Deno.test("record-trial-merge renders odd failing payloads without throwing", async () => {
+  const { app } = fakeApp();
+  const out = await handler(
+    // deno-lint-ignore no-explicit-any
+    {
+      variables: {
+        planKey: "o/r#69",
+        result: "suite-failed",
+        summary: "combined test failed",
+        failing: [1n],
+      },
+    } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  ) as Record<string, unknown>;
+
+  assertEquals(out.trialMergeRed, true);
+  assertStringIncludes(String(out.question ?? ""), "Failing:");
+});
+
+Deno.test("record-trial-merge treats textual conflicts as pass-through", async () => {
+  const { app } = fakeApp();
+  const out = await handler(
+    // deno-lint-ignore no-explicit-any
+    { variables: { planKey: "o/r#69", result: "merge-conflict", conflicts: [{ prs: [1, 2] }] } } as any,
+    // deno-lint-ignore no-explicit-any
+    app as any,
+  ) as Record<string, unknown>;
+
+  assertEquals(out.trialMergeRed, false);
+});

package/workers/record-trial-merge/worker.ts

@@ -0,0 +1,88 @@
+// pr.record-trial-merge — persist the D3 trial-merge gate result and shape the BPMN gateway vars.
+// Only `suite-failed` escalates. `clean` and textual `merge-conflict` proceed; D2/D6 own textual
+// conflict ordering, while D3 owns clean-merge/combined-suite-red semantic conflicts.
+import type { AppJobHandler } from "@nanobpm/urban";
+import {
+  recordTrialMergeAudit,
+  trialMergeDecision,
+  trialMergeTaskId,
+  type TrialMergeResult,
+} from "../../app/trialMerge.ts";
+
+interface In extends Record<string, unknown> {
+  planKey: string;
+  currentWave?: unknown;
+  trialMergeWave?: unknown;
+  waveOpenHeads?: unknown;
+  result?: unknown;
+  conflicts?: unknown;
+  failing?: unknown;
+  summary?: unknown;
+}
+interface Out extends Record<string, unknown> {
+  trialMergeRed: boolean;
+  question?: string;
+  task?: { id: string; title: string };
+  summary?: string;
+}
+
+const RESULTS = new Set<TrialMergeResult>(["clean", "merge-conflict", "suite-failed"]);
+const str = (v: unknown): string | undefined =>
+  typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+const waveNo = (v: unknown): number => {
+  const n = Math.trunc(Number(v));
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+};
+const safeJson = (v: unknown): string => {
+  try {
+    return JSON.stringify(v) ?? String(v);
+  } catch {
+    return String(v);
+  }
+};
+
+function parseResult(v: unknown): TrialMergeResult {
+  const s = typeof v === "string" ? v.trim() : "";
+  return RESULTS.has(s as TrialMergeResult) ? (s as TrialMergeResult) : "suite-failed";
+}
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const planKey = job.variables.planKey;
+  const wave = waveNo(job.variables.trialMergeWave ?? job.variables.currentWave);
+  const result = parseResult(job.variables.result);
+  const summary = str(job.variables.summary) ??
+    (result === "suite-failed" ? "Trial merge suite failed or returned no machine-readable result" : result);
+  const rawJobKey = (job as { key?: unknown }).key;
+  const jobKey = rawJobKey == null ? null : String(rawJobKey);
+
+  try {
+    await recordTrialMergeAudit(app.data, {
+      planKey,
+      wave,
+      result,
+      heads: job.variables.waveOpenHeads,
+      conflicts: job.variables.conflicts,
+      failing: job.variables.failing,
+      summary,
+      jobKey,
+    });
+  } catch (err) {
+    app.log("error", `record-trial-merge: audit persist failed for ${planKey} wave ${wave}`, { err: String(err) });
+  }
+
+  const trialMergeRed = trialMergeDecision(result) === "escalate";
+  if (!trialMergeRed) return { trialMergeRed, summary };
+
+  const failing = Array.isArray(job.variables.failing) && job.variables.failing.length > 0
+    ? ` Failing: ${safeJson(job.variables.failing).slice(0, 1000)}`
+    : "";
+  return {
+    trialMergeRed,
+    summary,
+    task: { id: trialMergeTaskId(wave), title: `Trial merge gate for wave ${wave}` },
+    question: `${summary}${failing}\n\nD3 needs a human decision: either the PR heads merged cleanly and the combined suite failed, or the trial-merge agent did not return a valid machine-readable result. Decide the design/infrastructure fix, update the PR heads if needed, then answer to rerun the trial merge; answer exactly \"proceed\" only to override and continue without rerunning.`,
+  };
+};
+
+export default handler;
+export { parseResult };

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

@@ -0,0 +1,221 @@
+// Red/green regression for retrying a wave when `select-wave` deliberately left pending work
+// behind a non-fatal wait (D7 / issue #63). Advancing past that wave would make `record-results`
+// finish the plan with a still-pending task.
+import { assertEquals } from "jsr:@std/assert@1";
+import handler from "./worker.ts";
+import type { PlanTaskStatus } from "../../app/plan.ts";
+import { _clearMergeProtocolCache } from "../../app/mergeProtocol.ts";
+
+interface Row {
+  id: number;
+  plan_key: string;
+  task_id: string;
+  status: PlanTaskStatus;
+  wave?: number | null;
+}
+
+function fakeApp(rows: Row[]) {
+  const planUpdates: Record<string, unknown>[] = [];
+  const stores: Record<string, Record<string, unknown>[]> = {
+    plan_tasks: rows as unknown as Record<string, unknown>[],
+    plan_task_deps: [],
+    pull_requests: [],
+    pr_dependencies: [],
+    escalations: [],
+    plans: [],
+    plan_task_deltas: [],
+    plan_merge_exclusions: [],
+  };
+  return {
+    app: {
+      data: {
+        table(name: string, key: string) {
+          const store = stores[name] ??= [];
+          return {
+            // deno-lint-ignore no-explicit-any
+            get: (k: any) =>
+              Promise.resolve(store.find((r) => ((r as unknown) as Record<string, unknown>)[key] === k)),
+            // deno-lint-ignore no-explicit-any
+            find: (q: any) =>
+              Promise.resolve(
+                store.filter((r) =>
+                  Object.entries(q).every(([f, v]) =>
+                    ((r as unknown) as Record<string, unknown>)[f] === v
+                  )
+                ),
+              ),
+            // deno-lint-ignore no-explicit-any
+            insert: (row: any) => {
+              store.push(row);
+              return Promise.resolve(store.length);
+            },
+            // deno-lint-ignore no-explicit-any
+            update: (k: any, patch: any) => {
+              if (name === "plans") {
+                planUpdates.push({ key: k, patch });
+                return Promise.resolve(undefined);
+              }
+              const row = store.find((r) =>
+                ((r as unknown) as Record<string, unknown>)[key] === k
+              );
+              if (row) Object.assign(row, patch);
+              return Promise.resolve(row);
+            },
+          };
+        },
+      },
+      log: () => undefined,
+      engine: {
+        createInstance: () => Promise.resolve({ processInstanceKey: "pi" }),
+      },
+      // deno-lint-ignore no-explicit-any
+    } as any,
+    planUpdates,
+  };
+}
+
+function installGithubStub(method: "gh-merge" | "mergify-queue") {
+  _clearMergeProtocolCache();
+  const oldTransport = Deno.env.get("NANO_PR_GITHUB_TRANSPORT");
+  const oldToken = Deno.env.get("GITHUB_TOKEN");
+  const oldFetch = globalThis.fetch;
+  Deno.env.set("NANO_PR_GITHUB_TRANSPORT", "token");
+  Deno.env.set("GITHUB_TOKEN", "test-token");
+  globalThis.fetch = ((input: string | URL | Request) => {
+    const url = String(input);
+    if (url.includes("/contents/AGENTS.md")) {
+      if (method === "mergify-queue") {
+        return Promise.resolve(new Response('```merge-protocol\n{ "land": { "method": "mergify-queue" } }\n```'));
+      }
+      return Promise.resolve(new Response("not found", { status: 404 }));
+    }
+    if (url.includes("/contents/.github/merge-protocol.json")) {
+      return Promise.resolve(new Response(JSON.stringify({ land: { method } })));
+    }
+    const pr = url.match(/\/pulls\/(\d+)/)?.[1] ?? "0";
+    if (url.includes("/files")) return Promise.resolve(new Response("[]"));
+    if (url.includes("/pulls/")) {
+      return Promise.resolve(new Response(JSON.stringify({
+        title: `PR ${pr}`,
+        body: "",
+        head: { ref: `feature-${pr}`, sha: `sha-${pr}` },
+      })));
+    }
+    return Promise.resolve(new Response("not found", { status: 404 }));
+  }) as typeof fetch;
+  return () => {
+    if (oldTransport == null) Deno.env.delete("NANO_PR_GITHUB_TRANSPORT");
+    else Deno.env.set("NANO_PR_GITHUB_TRANSPORT", oldTransport);
+    if (oldToken == null) Deno.env.delete("GITHUB_TOKEN");
+    else Deno.env.set("GITHUB_TOKEN", oldToken);
+    globalThis.fetch = oldFetch;
+    _clearMergeProtocolCache();
+  };
+}
+
+Deno.test("record-wave retries the same wave when a task is still pending", async () => {
+  const rows: Row[] = [{
+    id: 2,
+    plan_key: "owner/repo#63",
+    task_id: "b",
+    status: "pending",
+    wave: 1,
+  }];
+  const { app, planUpdates } = fakeApp(rows);
+
+  const out = await handler(
+    // deno-lint-ignore no-explicit-any
+    {
+      variables: {
+        planKey: "owner/repo#63",
+        currentWave: 1,
+        waveCount: 2,
+        waveTasks: [],
+        waveResults: [],
+      },
+    } as any,
+    app,
+  ) as Record<string, unknown>;
+
+  assertEquals(out, {
+    currentWave: 1,
+    hasMoreWaves: true,
+    waveOpenHeads: [],
+    runTrialMerge: false,
+    trialMergeWave: 1,
+    trialMergeSkipReason: "wave-still-pending",
+  });
+  assertEquals((planUpdates[0].patch as Record<string, unknown>).gate_wave, 1);
+});
+
+Deno.test("record-wave skips trial merge for mergify-queue repos with 2+ heads", async () => {
+  const restore = installGithubStub("mergify-queue");
+  try {
+    const rows: Row[] = [
+      { id: 1, plan_key: "owner/repo#69", task_id: "a", status: "pending", wave: 0 },
+      { id: 2, plan_key: "owner/repo#69", task_id: "b", status: "pending", wave: 0 },
+    ];
+    const { app } = fakeApp(rows);
+    const out = await handler(
+      // deno-lint-ignore no-explicit-any
+      {
+        variables: {
+          planKey: "owner/repo#69",
+          currentWave: 0,
+          waveCount: 1,
+          waveTasks: [{ id: "a" }, { id: "b" }],
+          waveResults: [
+            { status: "opened", pr: "owner/repo#1" },
+            { status: "opened", pr: "owner/repo#2" },
+          ],
+        },
+      } as any,
+      app,
+    ) as Record<string, unknown>;
+
+    assertEquals(out.runTrialMerge, false);
+    assertEquals(out.trialMergeSkipReason, "mergify-queue");
+    assertEquals(out.waveOpenHeads, [
+      { repo: "owner/repo", prNumber: 1, headRef: "feature-1", headSha: "sha-1" },
+      { repo: "owner/repo", prNumber: 2, headRef: "feature-2", headSha: "sha-2" },
+    ]);
+  } finally {
+    restore();
+  }
+});
+
+Deno.test("record-wave runs trial merge for non-queue repos with populated heads", async () => {
+  const restore = installGithubStub("gh-merge");
+  try {
+    const rows: Row[] = [
+      { id: 1, plan_key: "owner/repo#69", task_id: "a", status: "pending", wave: 0 },
+      { id: 2, plan_key: "owner/repo#69", task_id: "b", status: "pending", wave: 0 },
+    ];
+    const { app } = fakeApp(rows);
+    const out = await handler(
+      // deno-lint-ignore no-explicit-any
+      {
+        variables: {
+          planKey: "owner/repo#69",
+          currentWave: 0,
+          waveCount: 1,
+          waveTasks: [{ id: "a" }, { id: "b" }],
+          waveResults: [
+            { status: "opened", pr: "owner/repo#1" },
+            { status: "opened", pr: "owner/repo#2" },
+          ],
+        },
+      } as any,
+      app,
+    ) as Record<string, unknown>;
+
+    assertEquals(out.runTrialMerge, true);
+    assertEquals(out.trialMergeSkipReason, undefined);
+    assertEquals(out.waveOpenHeads, [
+      { repo: "owner/repo", prNumber: 1, headRef: "feature-1", headSha: "sha-1" },
+      { repo: "owner/repo", prNumber: 2, headRef: "feature-2", headSha: "sha-2" },
+    ]);
+  } finally {
+    restore();
+  }
+});