@nanobpm/nano-workforce 0.48.2 → 0.50.0

package/workers/merge/worker.test.ts

@@ -6,6 +6,7 @@
 // token transport and stubs `globalThis.fetch` so the single-PR GET reports `merged: true`.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
+import { _clearMergeProtocolCache } from "../../app/mergeProtocol.ts";
 import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 
@@ -95,3 +96,114 @@ test("pr.merge short-circuits an already-merged PR without re-running the land p
     assertEquals(calls.some((u) => /comments|merge$/.test(u)), false);
   });
 });
+
+// The land protocol has three terminal outcomes, dispatched by the worker's exhaustive `matchTags`
+// (worker.ts §"Exhaustive dispatch"). The already-merged short-circuit above never reaches that
+// dispatch, so the two land branches below — `queued` (repo lands via an on-demand merge queue) and
+// `blocked` (GitHub refuses the merge) — pin the behaviour of that critical terminal switch so a
+// regression in any arm is caught. Both drive the token transport and route GitHub calls through a
+// stubbed `globalThis.fetch`.
+// Each recorded call keeps the HTTP method alongside the URL so tests can assert not just *which*
+// endpoint the worker hit but *how* (e.g. enqueue via POST, merge via PUT) — a URL-only matcher
+// would stay green if the verb regressed.
+type GithubCall = { url: string; method: string };
+
+function withGithub(
+  routes: (url: string, init: RequestInit | undefined) => Response | null,
+  run: (calls: GithubCall[]) => Promise<void>,
+): Promise<void> {
+  const oldTransport = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const oldToken = process.env["GITHUB_TOKEN"];
+  const oldFetch = globalThis.fetch;
+  const calls: GithubCall[] = [];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "test-token";
+  _clearMergeProtocolCache();
+  globalThis.fetch = ((input: string | URL | Request, init?: RequestInit) => {
+    const url = String(input);
+    calls.push({ url, method: (init?.method ?? "GET").toUpperCase() });
+    const res = routes(url, init);
+    return Promise.resolve(res ?? new Response("not found", { status: 404 }));
+  }) as typeof fetch;
+  return run(calls).finally(() => {
+    if (oldTransport == null) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = oldTransport;
+    if (oldToken == null) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = oldToken;
+    globalThis.fetch = oldFetch;
+    _clearMergeProtocolCache();
+  });
+}
+
+test("pr.merge routes a mergify-queue repo through the queued branch (enqueue comment, status=queued)", async () => {
+  // AGENTS.md publishes a mergify-queue land protocol, so the worker enqueues via a comment rather
+  // than issuing a direct merge; the queued arm of `matchTags` marks the PR `queued` and returns.
+  const protocol =
+    "# repo\n\n```merge-protocol\n{ \"land\": { \"method\": \"mergify-queue\", \"comment\": \"@mergifyio queue\" } }\n```\n";
+  await withGithub(
+    (url) => {
+      if (/\/contents\/AGENTS\.md$/.test(url)) return new Response(protocol);
+      if (/\/pulls\/\d+$/.test(url)) return new Response(JSON.stringify({ merged: false, mergeable_state: "clean" }));
+      if (/\/issues\/\d+\/comments$/.test(url)) return new Response(JSON.stringify({ id: 1 }), { status: 201 });
+      return null;
+    },
+    async (calls) => {
+      const { app, stores } = fakeApp();
+      const out = (await handler(
+        { variables: { prKey: "acme/widgets#7", repo: "acme/widgets", prNumber: 7 } } as any,
+        app,
+      )) as Record<string, unknown>;
+
+      // Queued arm: waits for `merge-landed`, so it reports `queued` (not `merged`/`blocked`).
+      assertEquals(out, { mergeStatus: "queued" });
+
+      // Enqueued via the protocol's comment (POST), never a direct merge PUT.
+      assertEquals(
+        calls.some((c) => /\/issues\/\d+\/comments$/.test(c.url) && c.method === "POST"),
+        true,
+      );
+      assertEquals(calls.some((c) => /\/merge$/.test(c.url)), false);
+
+      // Audit row records the queue-comment land, and the PR row is flipped to `queued`.
+      assertEquals(stores.merges.length, 1);
+      assertEquals(stores.merges[0].outcome, "queued");
+      assertEquals(stores.merges[0].method, "queue-comment");
+      assertEquals(stores.pull_requests.find((r) => r.pr_key === "acme/widgets#7")?.status, "queued");
+    },
+  );
+});
+
+test("pr.merge routes a refused merge through the blocked branch (escalation payload)", async () => {
+  // Default (gh-merge) protocol; GitHub refuses the merge PUT, so `mergePr` reports `blocked` and the
+  // blocked arm of `matchTags` shapes the human-facing escalation question from the failure detail.
+  await withGithub(
+    (url) => {
+      if (/\/pulls\/\d+\/merge$/.test(url))
+        return new Response("Pull Request is not mergeable", { status: 405, statusText: "Method Not Allowed" });
+      if (/\/pulls\/\d+$/.test(url)) return new Response(JSON.stringify({ merged: false, mergeable_state: "dirty" }));
+      return null; // no AGENTS.md / merge-protocol.json → DEFAULT gh-merge protocol
+    },
+    async (calls) => {
+      const { app, stores } = fakeApp();
+      const out = (await handler(
+        { variables: { prKey: "acme/widgets#9", repo: "acme/widgets", prNumber: 9 } } as any,
+        app,
+      )) as Record<string, unknown>;
+
+      // Blocked arm: surfaces both the loop-terminal `mergeStatus` and the escalation `status`.
+      assertEquals(out.mergeStatus, "blocked");
+      assertEquals(out.status, "blocked");
+      assertEquals(typeof out.question, "string");
+      assertEquals((out.question as string).startsWith("Automated merge was blocked:"), true);
+
+      // Attempted a real merge PUT (not an enqueue comment), and recorded a blocked audit row.
+      assertEquals(
+        calls.some((c) => /\/pulls\/\d+\/merge$/.test(c.url) && c.method === "PUT"),
+        true,
+      );
+      assertEquals(calls.some((c) => /\/comments$/.test(c.url)), false);
+      assertEquals(stores.merges.length, 1);
+      assertEquals(stores.merges[0].outcome, "blocked");
+    },
+  );
+});

package/workers/merge/worker.ts

@@ -9,6 +9,7 @@
 // calls live in app/github.ts; this worker records the attempt in the `merges` audit table and
 // shapes the escalation payload on a block.
 import type { AppJobHandler } from "@nanobpm/urban";
+import { matchTags, tag } from "@nanobpm/urban/effect";
 import { abandonTokenFromUrl } from "../../app/abandon.ts";
 import { checkBaseTarget } from "../../app/baseGuard.ts";
 import { enqueueViaComment, fetchPrState, mergePr } from "../../app/github.ts";
@@ -134,25 +135,29 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     at: now,
   });
 
-  if (outcome === "queued") {
-    await app.data.table("pull_requests", "pr_key").update(prKey, {
-      status: "queued",
-      updated_at: now,
-    });
-    return { mergeStatus: "queued" };
-  }
-  if (outcome === "merged") {
-    return { mergeStatus: "merged" };
-  }
-  // blocked → hand the escalation machinery a concrete question.
+  // Exhaustive dispatch on the land outcome. Modelled as a tagged value so
+  // `matchTags` forces a handler for every case — adding a new outcome to the
+  // `"merged" | "queued" | "blocked"` union becomes a compile error here rather
+  // than silently falling through to the "blocked" branch.
   const docHint = protocol?.doc ? ` See the repo's merge protocol (${protocol.doc}).` : "";
-  return {
-    mergeStatus: "blocked",
-    status: "blocked",
-    question:
-      `Automated merge was blocked: ${detail}. ` +
-      `Resolve it on GitHub (rebase / fix a required check / grant merge rights), then reply to retry.${docHint}`,
-  };
+  return await matchTags(tag(outcome, { detail }), {
+    queued: async () => {
+      await app.data.table("pull_requests", "pr_key").update(prKey, {
+        status: "queued",
+        updated_at: now,
+      });
+      return { mergeStatus: "queued" };
+    },
+    merged: async () => ({ mergeStatus: "merged" }),
+    // blocked → hand the escalation machinery a concrete question.
+    blocked: async (o) => ({
+      mergeStatus: "blocked",
+      status: "blocked",
+      question:
+        `Automated merge was blocked: ${o.detail}. ` +
+        `Resolve it on GitHub (rebase / fix a required check / grant merge rights), then reply to retry.${docHint}`,
+    }),
+  });
 };
 
 export default handler;

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

@@ -0,0 +1,89 @@
+// Regression coverage for record-plan's operator-visibility wave progress projection (issue #137).
+//
+// record-plan initializes plans.wave_count/current_wave/wave_label when a plan is dispatched. The
+// three fields must stay consistent: a taskful plan gets wave_count N, current_wave 0, "1/N"; a
+// taskless plan gets all three NULL (never wave_count 0 against NULL current_wave/wave_label, which
+// would leak a misleading value to the epics-index — the documented contract is "NULL until
+// dispatched with tasks").
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import handler from "./worker.ts";
+
+interface Row extends Record<string, unknown> {
+  id?: number;
+  plan_key: string;
+}
+
+function fakeApp() {
+  const planTasks: Row[] = [];
+  const planTaskDeps: Row[] = [];
+  const plans: Row[] = [{ plan_key: "owner/repo#137" }];
+  let nextId = 1;
+  const app = {
+    log: { error() {}, info() {}, warn() {} },
+    data: {
+      table(name: string, key: string) {
+        const store = name === "plan_tasks"
+          ? planTasks
+          : name === "plan_task_deps"
+          ? planTaskDeps
+          : plans;
+        return {
+          find: (q: Record<string, unknown>) =>
+            Promise.resolve(
+              store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)),
+            ),
+          insert: (row: Row) => {
+            store.push({ ...row, id: row.id ?? nextId++ });
+            return Promise.resolve();
+          },
+          delete: (k: unknown) => {
+            for (let i = store.length - 1; i >= 0; i--) {
+              if (store[i][key] === k) store.splice(i, 1);
+            }
+            return Promise.resolve();
+          },
+          update: (k: unknown, patch: Record<string, unknown>) => {
+            const row = store.find((r) => r[key] === k);
+            if (row) Object.assign(row, patch);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+  } as any;
+  return { app, plans, planTasks };
+}
+
+test("record-plan initializes wave progress fields for a taskful plan", async () => {
+  const { app, plans } = fakeApp();
+  await handler(
+    {
+      variables: {
+        planKey: "owner/repo#137",
+        tasks: [
+          { id: "a", prompt: "do A" },
+          { id: "b", prompt: "do B", dependsOn: ["a"] },
+        ],
+      },
+    } as any,
+    app,
+  );
+  assertEquals(plans[0].status, "dispatched");
+  assertEquals(plans[0].wave_count, 2);
+  assertEquals(plans[0].current_wave, 0);
+  assertEquals(plans[0].wave_label, "1/2");
+});
+
+test("record-plan leaves all three wave progress fields NULL for a taskless plan", async () => {
+  const { app, plans } = fakeApp();
+  await handler(
+    { variables: { planKey: "owner/repo#137", tasks: [], note: "planner emitted no tasks" } } as any,
+    app,
+  );
+  assertEquals(plans[0].status, "done");
+  // No wave to implement => no misleading wave_count: 0 while current_wave/wave_label are NULL.
+  assertEquals(plans[0].wave_count, null);
+  assertEquals(plans[0].current_wave, null);
+  assertEquals(plans[0].wave_label, null);
+});

package/workers/record-plan/worker.ts

@@ -123,6 +123,14 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const patch: Record<string, unknown> = {
     status: tasks.length > 0 ? "dispatched" : "done",
     task_count: tasks.length,
+    // Operator-visibility progress projection (issue #137): total waves (N), and the wave the
+    // fleet is actively implementing (0 at dispatch). `select-wave` advances current_wave per
+    // wave; a taskless plan gets no wave (NULL) since there is nothing to implement. Display-only.
+    // All three fields stay NULL until dispatched with tasks — a taskless plan must not leak a
+    // misleading wave_count: 0 while current_wave/wave_label are NULL (inconsistent projection).
+    wave_count: tasks.length > 0 ? waveCount : null,
+    current_wave: tasks.length > 0 ? 0 : null,
+    wave_label: tasks.length > 0 ? `1/${waveCount}` : null,
     updated_at: ts,
   };
   if (tasks.length === 0) patch.outcome = note ? str(note) : "planner emitted no tasks";

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

@@ -142,6 +142,62 @@ test("record-wave retries the same wave when a task is still pending", async ()
     trialMergeSkipReason: "wave-still-pending",
   });
   assertEquals((planUpdates[0].patch as Record<string, unknown>).gate_wave, 1);
+  // Retry keeps the projection on the same (still-pending) wave.
+  assertEquals((planUpdates[0].patch as Record<string, unknown>).current_wave, 1);
+});
+
+test("record-wave pins current_wave to the last index and clears gate_wave on the final wave", async () => {
+  const rows: Row[] = [{
+    id: 9,
+    plan_key: "owner/repo#63",
+    task_id: "z",
+    status: "opened",
+    wave: 2,
+  }];
+  const { app, planUpdates } = fakeApp(rows);
+
+  await handler(
+    {
+      variables: {
+        planKey: "owner/repo#63",
+        currentWave: 2,
+        waveCount: 3,
+        waveTasks: [],
+        waveResults: [],
+      },
+    } as any,
+    app,
+  );
+
+  // Final wave (2 of 3): no successor wave — gate cleared, projection pinned to N-1 so the
+  // epics-index reads 3/3 rather than the one-past-the-end nextWave (3).
+  assertEquals((planUpdates[0].patch as Record<string, unknown>).gate_wave, null);
+  assertEquals((planUpdates[0].patch as Record<string, unknown>).current_wave, 2);
+  assertEquals((planUpdates[0].patch as Record<string, unknown>).wave_label, "3/3");
+});
+
+test("record-wave keeps all wave-progress fields NULL for a taskless plan (waveCount 0)", async () => {
+  // A taskless plan runs record-wave with waveCount 0 (the MI `implement` step completed
+  // immediately). All three progress fields must stay NULL together — never current_wave=0 against
+  // a NULL wave_label, which would clobber record-plan/select-wave's NULL projection.
+  const { app, planUpdates } = fakeApp([]);
+
+  await handler(
+    {
+      variables: {
+        planKey: "owner/repo#70",
+        currentWave: 0,
+        waveCount: 0,
+        waveTasks: [],
+        waveResults: [],
+      },
+    } as any,
+    app,
+  );
+
+  const patch = planUpdates[0].patch as Record<string, unknown>;
+  assertEquals(patch.current_wave, null);
+  assertEquals(patch.wave_label, null);
 });
 
 test("record-wave skips trial merge for mergify-queue repos with 2+ heads", async () => {

package/workers/record-wave/worker.ts

@@ -278,6 +278,18 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const nextWave = stillPendingCurrentWave ? currentWave : currentWave + 1;
   const hasMoreWaves = stillPendingCurrentWave || nextWave < waveCount;
 
+  // Operator-visibility projection (issue #137): keep plans.current_wave tracking the wave the
+  // fleet is on. While more waves remain, point it at the wave about to run (select-wave re-writes
+  // the same value when it dispatches); on the final wave, pin it to the last index so a finished
+  // epic reads N/N (nextWave would be waveCount, one past the last band). Display-only.
+  const projectedCurrentWave = hasMoreWaves ? nextWave : Math.max(0, waveCount - 1);
+  // Keep the three progress fields consistent: a taskless plan (waveCount 0 — the MI `implement`
+  // step completed immediately with no waves) has no wave to be on, so current_wave and wave_label
+  // both stay NULL rather than writing current_wave=0 against a NULL label (and clobbering the NULL
+  // projection record-plan/select-wave already recorded).
+  const currentWaveProjection = waveCount > 0 ? projectedCurrentWave : null;
+  const waveLabel = waveCount > 0 ? `${projectedCurrentWave + 1}/${waveCount}` : null;
+
   // Wave-merge barrier: when another wave follows, park the plan-fanout instance at the
   // `wait-wave-merged` catch event until THIS wave's opened PRs have MERGED (not merely opened).
   // `gate_wave` is that durable marker; the poller (`pollWaveGates`) clears it and publishes
@@ -288,6 +300,8 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   try {
     await plans(app.data).update(planKey, {
       gate_wave: hasMoreWaves ? currentWave : null,
+      current_wave: currentWaveProjection,
+      wave_label: waveLabel,
       updated_at: ts,
     });
   } catch (err) {

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

@@ -25,11 +25,12 @@ interface DepRow {
   depends_on_task_id: string;
 }
 
-function fakeApp(rows: Row[], deps: DepRow[]) {
+function fakeApp(rows: Row[], deps: DepRow[], plans: Record<string, unknown>[] = []) {
   return {
+    log: { error() {}, info() {}, warn() {} },
     data: {
       table(name: string, key: string) {
-        const store = name === "plan_tasks" ? rows : deps;
+        const store = name === "plan_tasks" ? rows : name === "plans" ? plans : deps;
         return {
           find: (q: any) =>
             Promise.resolve(
@@ -60,6 +61,36 @@ async function selectWave(rows: Row[], deps: DepRow[]) {
   return out as { waveTasks: unknown[] };
 }
 
+test("select-wave projects the active wave onto plans.current_wave", async () => {
+  const rows: Row[] = [
+    { id: 1, plan_key: "owner/repo#63", task_id: "a", title: "A", prompt: "do A", status: "pending", wave: 1 },
+  ];
+  const plans: Record<string, unknown>[] = [{ plan_key: "owner/repo#63", current_wave: 0 }];
+  const out = await handler(
+    { variables: { planKey: "owner/repo#63", currentWave: 1 } } as any,
+    fakeApp(rows, [], plans),
+  );
+  assertEquals((out as { waveTasks: unknown[] }).waveTasks.length, 1);
+  assertEquals(plans[0].current_wave, 1);
+  // wave_count is derived from the levelized rows (max wave + 1) and the 1-based "X/N" label
+  // is pre-formatted for the epics-index at-a-glance column.
+  assertEquals(plans[0].wave_count, 2);
+  assertEquals(plans[0].wave_label, "2/2");
+});
+
+test("select-wave nulls all three progress fields when there are no levelized rows", async () => {
+  // No plan_tasks rows => waveCount 0. current_wave must be NULL too (not a stray index against a
+  // NULL wave_count/wave_label), matching the documented "NULL until dispatched with tasks".
+  const plans: Record<string, unknown>[] = [{ plan_key: "owner/repo#63", current_wave: 5 }];
+  await handler(
+    { variables: { planKey: "owner/repo#63", currentWave: 0 } } as any,
+    fakeApp([], [], plans),
+  );
+  assertEquals(plans[0].current_wave, null);
+  assertEquals(plans[0].wave_count, null);
+  assertEquals(plans[0].wave_label, null);
+});
+
 test("select-wave leaves dependents pending behind a waiting-for-lane dependency", async () => {
   const rows: Row[] = [
     {

package/workers/select-wave/worker.ts

@@ -15,7 +15,7 @@
 // Emitting an empty `waveTasks` is fine: the MI activity over an empty collection completes
 // immediately (the same 0-task path the flat fan-out already relied on).
 import type { AppJobHandler } from "@nanobpm/urban";
-import { planTaskDeps, planTasks } from "../../app/plan.ts";
+import { plans, planTaskDeps, planTasks } from "../../app/plan.ts";
 
 interface In extends Record<string, unknown> {
   planKey: string;
@@ -47,6 +47,28 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const statusById = new Map<string, string>();
   for (const r of rows) statusById.set(r.task_id, r.status);
 
+  // Operator-visibility projection (issue #137): mark this as the wave the fleet is now
+  // implementing, so the epics-index can show wave X/N at a glance. wave_count is derivable from
+  // the levelized rows (max wave + 1), so the "X/N" label stays correct even if a re-levelize
+  // changed the total. Best-effort + idempotent (a retry re-writes the same value) and
+  // display-only — it must never gate control flow, which stays driven by the process
+  // `currentWave`/`waveCount`/`gate_wave` state.
+  const waveCount = rows.reduce((m, r) => Math.max(m, r.wave ?? 0), -1) + 1;
+  try {
+    await plans(app.data).update(planKey, {
+      // Keep the three progress fields consistent: with no levelized rows (waveCount 0) there is
+      // no wave to implement, so current_wave is NULL too — never a stray index against NULL N.
+      current_wave: waveCount > 0 ? currentWave : null,
+      wave_count: waveCount > 0 ? waveCount : null,
+      wave_label: waveCount > 0 ? `${currentWave + 1}/${waveCount}` : null,
+      updated_at: ts,
+    });
+  } catch (err) {
+    app.log.error(`select-wave: projecting current_wave failed for ${planKey}`, {
+      err: String(err),
+    });
+  }
+
   const deps = await planTaskDeps(app.data).find({ plan_key: planKey });
   const depsByTask = new Map<string, string[]>();
   for (const d of deps) {