@nanobpm/nano-workforce 0.26.0

package/app/reviewWait.test.ts

@@ -0,0 +1,70 @@
+// Contract for the review-wait liveness policy — the ISO-8601 timeout validation handed to the
+// process's timer catch, and the Copilot re-request nudge cooldown. Both are env-driven, so a
+// blank/malformed operator value must fall back to a sane default rather than deploy an
+// uninterpretable timer or a runaway nudge interval. Run with `deno test -A`.
+import { assertEquals } from "jsr:@std/assert@1";
+import {
+  clampNudgeMinutes,
+  DEFAULT_REVIEW_NUDGE_MINUTES,
+  DEFAULT_REVIEW_WAIT_TIMEOUT,
+  MAX_REVIEW_NUDGE_MINUTES,
+  reviewWaitTimeout,
+} from "./reviewWait.ts";
+
+Deno.test("reviewWaitTimeout: blank / absent / malformed → default", () => {
+  assertEquals(reviewWaitTimeout(undefined), DEFAULT_REVIEW_WAIT_TIMEOUT);
+  assertEquals(reviewWaitTimeout(""), DEFAULT_REVIEW_WAIT_TIMEOUT);
+  assertEquals(reviewWaitTimeout("   "), DEFAULT_REVIEW_WAIT_TIMEOUT);
+  assertEquals(reviewWaitTimeout("20m"), DEFAULT_REVIEW_WAIT_TIMEOUT); // missing leading P/T
+  assertEquals(reviewWaitTimeout("P"), DEFAULT_REVIEW_WAIT_TIMEOUT); // no component
+  assertEquals(reviewWaitTimeout("PT"), DEFAULT_REVIEW_WAIT_TIMEOUT); // T with no time component
+  assertEquals(reviewWaitTimeout("garbage"), DEFAULT_REVIEW_WAIT_TIMEOUT);
+});
+
+Deno.test("reviewWaitTimeout: a valid ISO-8601 duration is honoured and upper-cased", () => {
+  assertEquals(reviewWaitTimeout("PT30M"), "PT30M");
+  assertEquals(reviewWaitTimeout("pt30m"), "PT30M");
+  assertEquals(reviewWaitTimeout(" PT1H30M "), "PT1H30M");
+  assertEquals(reviewWaitTimeout("PT45S"), "PT45S");
+  assertEquals(reviewWaitTimeout("P1D"), "P1D");
+  assertEquals(reviewWaitTimeout("P1DT2H"), "P1DT2H");
+});
+
+Deno.test("reviewWaitTimeout: a custom fallback is used when the value is invalid", () => {
+  assertEquals(reviewWaitTimeout("nope", "PT10M"), "PT10M");
+  assertEquals(reviewWaitTimeout(undefined, "PT10M"), "PT10M");
+});
+
+Deno.test("clampNudgeMinutes: blank / absent / non-numeric → fallback", () => {
+  assertEquals(clampNudgeMinutes(""), DEFAULT_REVIEW_NUDGE_MINUTES);
+  assertEquals(clampNudgeMinutes("   "), DEFAULT_REVIEW_NUDGE_MINUTES);
+  assertEquals(clampNudgeMinutes(undefined), DEFAULT_REVIEW_NUDGE_MINUTES);
+  assertEquals(clampNudgeMinutes(null), DEFAULT_REVIEW_NUDGE_MINUTES);
+  assertEquals(clampNudgeMinutes("abc"), DEFAULT_REVIEW_NUDGE_MINUTES);
+  assertEquals(clampNudgeMinutes(NaN), DEFAULT_REVIEW_NUDGE_MINUTES);
+});
+
+Deno.test("clampNudgeMinutes: a valid positive value (string or number) is honoured", () => {
+  assertEquals(clampNudgeMinutes("10"), 10);
+  assertEquals(clampNudgeMinutes(15), 15);
+  assertEquals(clampNudgeMinutes(" 7 "), 7);
+});
+
+Deno.test("clampNudgeMinutes: fractional values are truncated", () => {
+  assertEquals(clampNudgeMinutes("5.9"), 5);
+  assertEquals(clampNudgeMinutes(3.2), 3);
+});
+
+Deno.test("clampNudgeMinutes: zero and negatives fall back (a 0 cooldown would hammer the API)", () => {
+  assertEquals(clampNudgeMinutes(0), DEFAULT_REVIEW_NUDGE_MINUTES);
+  assertEquals(clampNudgeMinutes("-4"), DEFAULT_REVIEW_NUDGE_MINUTES);
+});
+
+Deno.test("clampNudgeMinutes: above the ceiling is clamped, not rejected", () => {
+  assertEquals(clampNudgeMinutes(100_000), MAX_REVIEW_NUDGE_MINUTES);
+  assertEquals(clampNudgeMinutes(String(MAX_REVIEW_NUDGE_MINUTES + 1)), MAX_REVIEW_NUDGE_MINUTES);
+});
+
+Deno.test("clampNudgeMinutes: an oversized fallback is itself clamped to the ceiling", () => {
+  assertEquals(clampNudgeMinutes("", MAX_REVIEW_NUDGE_MINUTES + 50), MAX_REVIEW_NUDGE_MINUTES);
+});

package/app/reviewWait.ts

@@ -0,0 +1,59 @@
+// Review-wait liveness policy, kept as a pure module (no env, no I/O) so it is trivially
+// testable — mirrors app/rounds.ts. `service.ts` builds the fleet-wide REVIEW_WAIT_TIMEOUT and
+// REVIEW_NUDGE_MS on top of these, and the process's timer catch is seeded with the validated
+// ISO-8601 duration at submit.
+//
+// Two knobs govern the review-wait watchdog:
+//   • the *timeout* — an ISO-8601 duration handed to the process's `wait-review-timeout` timer
+//     catch (the far side of the event-based-gateway race against `review-ready`). If no fresh
+//     review arrives within it, the loop escalates to a human instead of hanging forever.
+//   • the *nudge cooldown* — how long the poller waits between automatic Copilot re-requests for
+//     one waiting PR, so a re-request that Copilot dismisses is retried without hammering the API.
+
+/** Default review-wait timeout (ISO-8601 duration): how long the loop waits for a fresh review
+ * before the timer arm of the event-based gateway fires and it escalates to a human. */
+export const DEFAULT_REVIEW_WAIT_TIMEOUT = "PT20M";
+
+// A pragmatic ISO-8601 duration matcher: requires a leading `P`, at least one component, and a
+// `T` before any time components (with at least one time component after it). Good enough to
+// reject an obviously-malformed env value before it is baked into a timer expression the engine
+// would fail to interpret; not a full grammar (we don't need fractional seconds here).
+const ISO_DURATION = /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/;
+
+/** Validate an ISO-8601 duration for the review-wait timer, falling back to `def` when the value
+ * is absent, blank, or malformed — a bad env value must never deploy an uninterpretable timer
+ * expression into the process. Normalises to upper case (`pt20m` → `PT20M`). */
+export function reviewWaitTimeout(
+  raw: string | undefined,
+  def: string = DEFAULT_REVIEW_WAIT_TIMEOUT,
+): string {
+  const s = (raw ?? "").trim().toUpperCase();
+  return s !== "" && ISO_DURATION.test(s) ? s : def;
+}
+
+/** Default cooldown (minutes) between automatic Copilot re-request nudges for one waiting PR.
+ * Kept comfortably below the review-wait timeout default so several nudges are attempted before
+ * the loop escalates. */
+export const DEFAULT_REVIEW_NUDGE_MINUTES = 5;
+
+/** Upper bound on the nudge cooldown — a runaway value could park a genuinely-stalled PR for days
+ * with no re-request. Mirrors the ceiling discipline in rounds.ts. */
+export const MAX_REVIEW_NUDGE_MINUTES = 24 * 60;
+
+/** Coerce the operator-supplied nudge cooldown (env `NANO_PR_REVIEW_NUDGE_MINUTES`, minutes) into
+ * a sane positive integer. Absent / blank / non-numeric / zero / negative / NaN fall back to
+ * `fallback`; values above the ceiling are clamped down (and so is an oversized `fallback`, so it
+ * can never bypass the ceiling). */
+export function clampNudgeMinutes(
+  value: unknown,
+  fallback: number = DEFAULT_REVIEW_NUDGE_MINUTES,
+): number {
+  const safeFallback = Number.isFinite(fallback)
+    ? Math.min(Math.max(Math.trunc(fallback), 1), MAX_REVIEW_NUDGE_MINUTES)
+    : DEFAULT_REVIEW_NUDGE_MINUTES;
+  const n = typeof value === "number" ? value : Number(String(value ?? "").trim());
+  if (!Number.isFinite(n)) return safeFallback;
+  const i = Math.trunc(n);
+  if (i < 1) return safeFallback;
+  return Math.min(i, MAX_REVIEW_NUDGE_MINUTES);
+}

package/app/rounds.test.ts

@@ -0,0 +1,74 @@
+// Contract for clampRounds — the per-submit round-cap coercion. The submit form renders every
+// field as a text input (the runtime hardcodes type="text"), so the override arrives as a string
+// and a blank field must fall back to the fleet default. Run with `deno test`.
+import { assertEquals } from "jsr:@std/assert@1";
+import { clampCiFixBudget, clampRounds, MAX_CI_FIX_CEILING, MAX_ROUNDS_CEILING } from "./rounds.ts";
+
+Deno.test("blank / absent / non-numeric → fallback", () => {
+  assertEquals(clampRounds("", 20), 20);
+  assertEquals(clampRounds("   ", 20), 20);
+  assertEquals(clampRounds(undefined, 20), 20);
+  assertEquals(clampRounds(null, 20), 20);
+  assertEquals(clampRounds("abc", 20), 20);
+  assertEquals(clampRounds(NaN, 20), 20);
+});
+
+Deno.test("a valid positive value (string or number) is honoured", () => {
+  assertEquals(clampRounds("5", 20), 5);
+  assertEquals(clampRounds(30, 20), 30);
+  assertEquals(clampRounds(" 12 ", 20), 12);
+});
+
+Deno.test("fractional values are truncated to a whole round", () => {
+  assertEquals(clampRounds("7.9", 20), 7);
+  assertEquals(clampRounds(3.2, 20), 3);
+});
+
+Deno.test("zero and negatives fall back (a cap < 1 would escalate before round 1)", () => {
+  assertEquals(clampRounds(0, 20), 20);
+  assertEquals(clampRounds("-4", 20), 20);
+});
+
+Deno.test("above the ceiling is clamped, not rejected", () => {
+  assertEquals(clampRounds(1000, 20), MAX_ROUNDS_CEILING);
+  assertEquals(clampRounds(String(MAX_ROUNDS_CEILING + 1), 20), MAX_ROUNDS_CEILING);
+});
+
+Deno.test("an oversized fallback is itself clamped to the ceiling", () => {
+  // A blank/invalid input falls back — but the fallback must not bypass the ceiling.
+  assertEquals(clampRounds("", MAX_ROUNDS_CEILING + 50), MAX_ROUNDS_CEILING);
+  assertEquals(clampRounds("   ", MAX_ROUNDS_CEILING + 1), MAX_ROUNDS_CEILING);
+  assertEquals(clampRounds(0, MAX_ROUNDS_CEILING + 999), MAX_ROUNDS_CEILING);
+  assertEquals(clampRounds("abc", MAX_ROUNDS_CEILING + 1), MAX_ROUNDS_CEILING);
+});
+
+// clampCiFixBudget — the merge stage's CI-fix attempt budget (NANO_PR_MAX_CI_FIX_ROUNDS). Unlike
+// clampRounds it ALLOWS 0, because 0 is a meaningful setting: disable auto-fix so a blocked PR
+// escalates to a human immediately.
+Deno.test("ci-fix budget: blank / non-numeric / negative → fallback", () => {
+  assertEquals(clampCiFixBudget("", 3), 3);
+  assertEquals(clampCiFixBudget("   ", 3), 3);
+  assertEquals(clampCiFixBudget(undefined, 3), 3);
+  assertEquals(clampCiFixBudget(null, 3), 3);
+  assertEquals(clampCiFixBudget("abc", 3), 3);
+  assertEquals(clampCiFixBudget(NaN, 3), 3);
+  assertEquals(clampCiFixBudget("-1", 3), 3);
+});
+
+Deno.test("ci-fix budget: 0 is honoured (disables auto-fix), unlike clampRounds", () => {
+  assertEquals(clampCiFixBudget(0, 3), 0);
+  assertEquals(clampCiFixBudget("0", 3), 0);
+  // Contrast: the round cap treats 0 as invalid and falls back.
+  assertEquals(clampRounds(0, 3), 3);
+});
+
+Deno.test("ci-fix budget: a valid positive value is honoured and truncated", () => {
+  assertEquals(clampCiFixBudget("5", 3), 5);
+  assertEquals(clampCiFixBudget(2, 3), 2);
+  assertEquals(clampCiFixBudget("4.8", 3), 4);
+});
+
+Deno.test("ci-fix budget: above the ceiling is clamped; oversized fallback too", () => {
+  assertEquals(clampCiFixBudget(1000, 3), MAX_CI_FIX_CEILING);
+  assertEquals(clampCiFixBudget("", MAX_CI_FIX_CEILING + 5), MAX_CI_FIX_CEILING);
+});

package/app/rounds.ts

@@ -0,0 +1,48 @@
+// The per-submit round-cap coercion, kept as a pure module (no env, no I/O) so it is trivially
+// testable — mirrors app/waves.ts. `service.ts` builds the fleet default MAX_ROUNDS on top of it,
+// and the submit form / webhook / start action each pass a caller-supplied override through it.
+
+/** Upper bound on the review-round cap. A cap of 0 would escalate before the first round; an
+ * unbounded cap could run the agent (and its cost) indefinitely, so overrides are clamped here. */
+export const MAX_ROUNDS_CEILING = 100;
+
+/** Coerce an arbitrary caller-supplied round cap into a sane positive integer, falling back to
+ * `fallback` when the value is absent, blank, non-numeric, zero/negative, or NaN. The submit form
+ * sends strings (the runtime renders every field as text), so this accepts `string | number |
+ * unknown`. Values above MAX_ROUNDS_CEILING are clamped down rather than rejected — and the same
+ * clamp is applied to `fallback`, so an oversized fallback can never bypass the safety ceiling. */
+export function clampRounds(value: unknown, fallback: number): number {
+  const safeFallback = Number.isFinite(fallback)
+    ? Math.min(Math.max(Math.trunc(fallback), 1), MAX_ROUNDS_CEILING)
+    : 1;
+  const n = typeof value === "number" ? value : Number(String(value ?? "").trim());
+  if (!Number.isFinite(n)) return safeFallback;
+  const i = Math.trunc(n);
+  if (i < 1) return safeFallback;
+  return Math.min(i, MAX_ROUNDS_CEILING);
+}
+
+/** Ceiling on CI-fix attempts, mirroring MAX_ROUNDS_CEILING — an unbounded budget could dispatch
+ * the `senior:fix-ci` agent (and its cost) indefinitely against a stubbornly-red PR. */
+export const MAX_CI_FIX_CEILING = 20;
+
+/** Coerce the operator-supplied CI-fix budget (env `NANO_PR_MAX_CI_FIX_ROUNDS`) into a sane
+ * non-negative integer. Unlike {@link clampRounds} this ALLOWS 0 — a budget of 0 disables
+ * auto-fix so a blocked PR escalates to a human immediately. Absent / blank / non-numeric /
+ * negative / NaN fall back to `fallback`; values above the ceiling are clamped down (and so is an
+ * oversized `fallback`, so it can never bypass the ceiling). */
+export function clampCiFixBudget(value: unknown, fallback: number): number {
+  const safeFallback = Number.isFinite(fallback)
+    ? Math.min(Math.max(Math.trunc(fallback), 0), MAX_CI_FIX_CEILING)
+    : 0;
+  // Blank / absent → fallback. This guard is essential BEFORE coercion: Number("") is 0, so a
+  // blank env var must not be mistaken for an explicit 0 (which legitimately disables auto-fix).
+  if (value === null || value === undefined) return safeFallback;
+  const trimmed = typeof value === "number" ? value : String(value).trim();
+  if (trimmed === "") return safeFallback;
+  const n = typeof trimmed === "number" ? trimmed : Number(trimmed);
+  if (!Number.isFinite(n)) return safeFallback;
+  const i = Math.trunc(n);
+  if (i < 0) return safeFallback;
+  return Math.min(i, MAX_CI_FIX_CEILING);
+}

package/app/service.test.ts

@@ -0,0 +1,101 @@
+// Red/green regression for re-submit clearing stale open escalations (Magikcraft/nano-bpm
+// #597/#599). When a cancelled/converged PR is re-submitted, `submitPr` re-opens it for a fresh
+// convergence run. Any escalation left `open` by the prior run — plus the denormalised
+// `open_escalation_*` pointer on the PR row — must be cleared, or the answer form resurfaces a
+// dead "(no question provided)" question on the re-opened PR (the same stale-row class the plan
+// 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";
+
+// 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),
+    // deno-lint-ignore no-explicit-any
+    find: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    // deno-lint-ignore no-explicit-any
+    insert: (r: any) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    // deno-lint-ignore no-explicit-any
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r);
+    },
+    // deno-lint-ignore no-explicit-any
+    delete: (k: any) => {
+      for (let i = rows.length - 1; i >= 0; i--) if (rows[i][key] === k) rows.splice(i, 1);
+      return Promise.resolve();
+    },
+  };
+}
+
+function withGithubOff(run: () => Promise<void>): Promise<void> {
+  const prevMode = Deno.env.get("NANO_PR_GITHUB_TRANSPORT");
+  const prevTok = Deno.env.get("GITHUB_TOKEN");
+  Deno.env.set("NANO_PR_GITHUB_TRANSPORT", "token"); // no token below -> fetchPrMeta returns null
+  Deno.env.delete("GITHUB_TOKEN");
+  return run().finally(() => {
+    if (prevMode !== undefined) Deno.env.set("NANO_PR_GITHUB_TRANSPORT", prevMode);
+    else Deno.env.delete("NANO_PR_GITHUB_TRANSPORT");
+    if (prevTok !== undefined) Deno.env.set("GITHUB_TOKEN", prevTok);
+  });
+}
+
+Deno.test("re-submit of a cancelled PR clears stale open escalations + the denormalised pointer", async () => {
+  await withGithubOff(async () => {
+    const PR_KEY = "owner/repo#42";
+    const stores: Record<string, { rows: unknown[]; key: string }> = {
+      pull_requests: {
+        rows: [{
+          pr_key: PR_KEY,
+          repo: "owner/repo",
+          number: 42,
+          url: "https://github.com/owner/repo/pull/42",
+          title: "old title",
+          status: "abandoned", // terminal -> re-open path
+          current_round: 3,
+          open_escalation_id: 5,
+          open_escalation_question: "(no question provided)",
+        }],
+        key: "pr_key",
+      },
+      escalations: {
+        rows: [{ id: 5, pr_key: PR_KEY, round_no: 3, kind: "question", question: "(no question provided)", status: "open" }],
+        key: "id",
+      },
+      pr_dependencies: { rows: [], 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 engine = {
+      createInstance: () => Promise.resolve({ processInstanceKey: "PI-9" }),
+      // deno-lint-ignore no-explicit-any
+    } as any;
+
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 42,
+      url: "https://github.com/owner/repo/pull/42",
+      prKey: PR_KEY,
+    });
+
+    // The prior run's open escalation is retired (not left "open" to resurface a dead form) …
+    const esc = stores.escalations.rows[0] as Record<string, unknown>;
+    assertEquals(esc.status, "stale");
+    // … and the PR row is re-opened with the denormalised escalation pointer cleared.
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.status, "converging");
+    assertEquals(pr.current_round, 1);
+    assertEquals(pr.open_escalation_id, null);
+    assertEquals(pr.open_escalation_question, null);
+    assertEquals(pr.process_key, "PI-9");
+  });
+});