@nanobpm/nano-workforce 0.48.2 → 0.49.0

package/pages/home.page.json

@@ -9,15 +9,25 @@
         "variant": "bar",
         "title": "Nano Workforce",
         "items": [
-          { "label": "Convergence", "page": "home" },
-          { "label": "Epic", "page": "epic" }
-        ]
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          }
+        ],
+        "sticky": true
       }
     },
     {
       "type": "text",
       "id": "title",
-      "props": { "text": "PR Review Convergence", "variant": "heading" }
+      "props": {
+        "text": "PR Review Convergence",
+        "variant": "heading"
+      }
     },
     {
       "type": "text",
@@ -31,13 +41,13 @@
       "type": "button",
       "id": "agent-instructions",
       "props": {
-        "label": "🤖 Agent Instructions",
+        "label": "\ud83e\udd16 Agent Instructions",
         "variant": "ghost",
         "modal": {
           "title": "Point your agent at Nano Workforce",
           "description": "Copy this prompt and paste it into your coding agent (Copilot, Claude, etc.). It tells the agent to read this workforce's live operator guide, then help you drive and debug it.",
           "copyLabel": "Copy prompt",
-          "copyText": "You are helping me operate a running Nano Workforce instance — a durable orchestration app that drives pull requests to review convergence against an automated reviewer, merges them, and can take a whole issue and plan \u2192 implement \u2192 converge it across a fleet of coding agents.\n\nFirst, fetch and read its live operator guide. It tells you how to submit PRs and epics for convergence (including whether to go all the way to merge or stop at review consensus), how to find engine instances and relate them to PRs via the Nano/Camunda-8 REST API, how to inspect the models and prompts, and how to help me untangle escalations:\n\n    curl -sS {{appBase}}app/api/agent\n\nIf this instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), add its value as an x-hook-secret header, otherwise the request returns 401:\n\n    curl -sS -H \"x-hook-secret: <secret>\" {{appBase}}app/api/agent\n\nThen follow that guide to help me drive and debug this workforce. If you find a bug or a stuck process, the guide explains how to raise an issue or a PR against nanobpm/nano-workforce."
+          "copyText": "You are helping me operate a running Nano Workforce instance \u2014 a durable orchestration app that drives pull requests to review convergence against an automated reviewer, merges them, and can take a whole issue and plan \u2192 implement \u2192 converge it across a fleet of coding agents.\n\nFirst, fetch and read its live operator guide. It tells you how to submit PRs and epics for convergence (including whether to go all the way to merge or stop at review consensus), how to find engine instances and relate them to PRs via the Nano/Camunda-8 REST API, how to inspect the models and prompts, and how to help me untangle escalations:\n\n    curl -sS {{appBase}}app/api/agent\n\nIf this instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), add its value as an x-hook-secret header, otherwise the request returns 401:\n\n    curl -sS -H \"x-hook-secret: <secret>\" {{appBase}}app/api/agent\n\nThen follow that guide to help me drive and debug this workforce. If you find a bug or a stuck process, the guide explains how to raise an issue or a PR against nanobpm/nano-workforce."
         }
       }
     },
@@ -47,11 +57,26 @@
       "props": {
         "title": "Submit a pull request",
         "submitLabel": "Start review",
-        "action": { "path": "/app/api/actions/start/convergence-loop", "body": "{{form}}" },
+        "action": {
+          "path": "/app/api/actions/start/convergence-loop",
+          "body": "{{form}}"
+        },
         "fields": [
-          { "key": "pr", "label": "owner/repo#123 or a GitHub PR URL", "type": "text" },
-          { "key": "maxRounds", "label": "Max review rounds (blank = fleet default)", "type": "number" },
-          { "key": "convergeOnly", "label": "Converge only — stop at review consensus, do not merge", "type": "checkbox" }
+          {
+            "key": "pr",
+            "label": "owner/repo#123 or a GitHub PR URL",
+            "type": "text"
+          },
+          {
+            "key": "maxRounds",
+            "label": "Max review rounds (blank = fleet default)",
+            "type": "number"
+          },
+          {
+            "key": "convergeOnly",
+            "label": "Converge only \u2014 stop at review consensus, do not merge",
+            "type": "checkbox"
+          }
         ]
       }
     },
@@ -67,50 +92,140 @@
           "kind": "datasource",
           "source": "app",
           "table": "pull_requests",
-          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "orderBy": {
+            "field": "updated_at",
+            "dir": "desc"
+          },
           "filter": [
-            { "field": "status", "in": ["converging", "waiting_review", "escalated", "waiting_deps", "waiting_merge", "queued", "merging"] }
+            {
+              "field": "status",
+              "in": [
+                "converging",
+                "waiting_review",
+                "escalated",
+                "waiting_deps",
+                "waiting_merge",
+                "queued",
+                "merging"
+              ]
+            }
           ]
         },
         "tabs": [
           {
             "label": "Active",
             "filter": [
-              { "field": "status", "in": ["converging", "waiting_review", "escalated", "waiting_deps", "waiting_merge", "queued", "merging"] }
+              {
+                "field": "status",
+                "in": [
+                  "converging",
+                  "waiting_review",
+                  "escalated",
+                  "waiting_deps",
+                  "waiting_merge",
+                  "queued",
+                  "merging"
+                ]
+              }
             ]
           },
           {
             "label": "History",
-            "filter": [{ "field": "status", "in": ["converged", "merged", "abandoned"] }]
+            "filter": [
+              {
+                "field": "status",
+                "in": [
+                  "converged",
+                  "merged",
+                  "abandoned"
+                ]
+              }
+            ]
           }
         ],
         "columns": [
-          { "field": "pr_key", "header": "PR", "linkField": "url" },
-          { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
-          { "field": "incident_message", "header": "Incident", "badge": { "tone": "danger", "label": "1" } },
-          { "field": "current_round", "header": "Round" },
-          { "field": "active_worker", "header": "Agent" },
-          { "field": "updated_at", "header": "Updated" }
+          {
+            "field": "pr_key",
+            "header": "PR",
+            "linkField": "url"
+          },
+          {
+            "field": "status",
+            "header": "Status",
+            "link": {
+              "kind": "processExplorer",
+              "keyField": "process_key"
+            }
+          },
+          {
+            "field": "incident_message",
+            "header": "Incident",
+            "badge": {
+              "tone": "danger",
+              "label": "1"
+            }
+          },
+          {
+            "field": "current_round",
+            "header": "Round"
+          },
+          {
+            "field": "active_worker",
+            "header": "Agent"
+          },
+          {
+            "field": "updated_at",
+            "header": "Updated"
+          }
         ],
         "rowActions": [
           {
             "label": "Cancel",
             "confirm": "Cancel this PR's review run?",
             "showWhenField": "process_key",
-            "action": { "path": "/app/actions/cancel", "body": { "processInstanceKey": "{{row.process_key}}" } }
+            "action": {
+              "path": "/app/actions/cancel",
+              "body": {
+                "processInstanceKey": "{{row.process_key}}"
+              }
+            }
           }
         ],
         "detail": {
           "linkField": "url",
           "fields": [
-            { "field": "repo", "label": "Repository" },
-            { "field": "number", "label": "PR number" },
-            { "field": "active_worker", "label": "Agent (leasing worker)" },
-            { "field": "lease_until", "label": "Activation lease until" },
-            { "field": "incident_message", "label": "Incident" },
-            { "field": "incident_key", "label": "Incident key" },
-            { "field": "merged_at", "label": "Merged at" },
-            { "field": "outcome", "label": "Outcome" }
+            {
+              "field": "repo",
+              "label": "Repository"
+            },
+            {
+              "field": "number",
+              "label": "PR number"
+            },
+            {
+              "field": "active_worker",
+              "label": "Agent (leasing worker)"
+            },
+            {
+              "field": "lease_until",
+              "label": "Activation lease until"
+            },
+            {
+              "field": "incident_message",
+              "label": "Incident"
+            },
+            {
+              "field": "incident_key",
+              "label": "Incident key"
+            },
+            {
+              "field": "merged_at",
+              "label": "Merged at"
+            },
+            {
+              "field": "outcome",
+              "label": "Outcome"
+            }
           ],
           "children": [
             {
@@ -119,14 +234,33 @@
               "table": "rounds",
               "parentField": "pr_key",
               "childField": "pr_key",
-              "orderBy": { "field": "round_no", "dir": "asc" },
+              "orderBy": {
+                "field": "round_no",
+                "dir": "asc"
+              },
               "columns": [
-                { "field": "round_no", "header": "#" },
-                { "field": "status", "header": "Result" },
-                { "field": "worker", "header": "Worker" },
-                { "field": "summary", "header": "Summary" }
+                {
+                  "field": "round_no",
+                  "header": "#"
+                },
+                {
+                  "field": "status",
+                  "header": "Result"
+                },
+                {
+                  "field": "worker",
+                  "header": "Worker"
+                },
+                {
+                  "field": "summary",
+                  "header": "Summary"
+                }
               ],
-              "lazyField": { "field": "transcript", "label": "Transcript", "lazy": true }
+              "lazyField": {
+                "field": "transcript",
+                "label": "Transcript",
+                "lazy": true
+              }
             },
             {
               "title": "Escalations",
@@ -134,16 +268,41 @@
               "table": "escalations",
               "parentField": "pr_key",
               "childField": "pr_key",
-              "orderBy": { "field": "id", "dir": "asc" },
+              "orderBy": {
+                "field": "id",
+                "dir": "asc"
+              },
               "columns": [
-                { "field": "round_no", "header": "#" },
-                { "field": "kind", "header": "Kind" },
-                { "field": "worker", "header": "Worker" },
-                { "field": "question", "header": "Question" },
-                { "field": "status", "header": "Status" },
-                { "field": "answer", "header": "Answer" }
+                {
+                  "field": "round_no",
+                  "header": "#"
+                },
+                {
+                  "field": "kind",
+                  "header": "Kind"
+                },
+                {
+                  "field": "worker",
+                  "header": "Worker"
+                },
+                {
+                  "field": "question",
+                  "header": "Question"
+                },
+                {
+                  "field": "status",
+                  "header": "Status"
+                },
+                {
+                  "field": "answer",
+                  "header": "Answer"
+                }
               ],
-              "lazyField": { "field": "transcript", "label": "Agent response", "lazy": true }
+              "lazyField": {
+                "field": "transcript",
+                "label": "Agent response",
+                "lazy": true
+              }
             },
             {
               "title": "Depends on",
@@ -151,10 +310,19 @@
               "table": "pr_dependencies",
               "parentField": "pr_key",
               "childField": "pr_key",
-              "orderBy": { "field": "created_at", "dir": "asc" },
+              "orderBy": {
+                "field": "created_at",
+                "dir": "asc"
+              },
               "columns": [
-                { "field": "depends_on_key", "header": "PR that must merge first" },
-                { "field": "created_at", "header": "Declared" }
+                {
+                  "field": "depends_on_key",
+                  "header": "PR that must merge first"
+                },
+                {
+                  "field": "created_at",
+                  "header": "Declared"
+                }
               ]
             }
           ],
@@ -167,7 +335,11 @@
             "submitLabel": "Send answer",
             "action": {
               "path": "/app/api/actions/message",
-              "body": { "name": "escalation-answered", "correlationKey": "{{row.pr_key}}", "variables": "{{form}}" }
+              "body": {
+                "name": "escalation-answered",
+                "correlationKey": "{{row.pr_key}}",
+                "variables": "{{form}}"
+              }
             }
           }
         }

package/scripts/pages-contract.test.ts

@@ -207,12 +207,15 @@ test("every page datasource column exists on its table", async () => {
   }
 });
 
-test("issue #87: plan_reviews is surfaced on the epic and home pages", async () => {
+test("issue #87: plan_reviews is surfaced on the per-epic detail page", async () => {
   const refs = await loadRefs();
-  const onEpic = refs.some((r) => r.page === "epic.page.json" && r.table === "plan_reviews");
-  const onHome = refs.some((r) => r.page === "home.page.json" && r.table === "plan_reviews");
-  assert(onEpic, "epic.page.json must bind a grid to plan_reviews (plan-review trace)");
-  assert(onHome, "home.page.json plan detail must include a plan_reviews child grid");
+  // The operator-visibility redesign (issue #137) moved per-plan detail grids off the flat
+  // epic index onto the param-scoped per-epic page (#/epic-detail/<plan_key>), where the
+  // plan-review trace is filtered to a single epic. Assert the trace lives there.
+  const onEpicDetail = refs.some(
+    (r) => r.page === "epic-detail.page.json" && r.table === "plan_reviews",
+  );
+  assert(onEpicDetail, "epic-detail.page.json must bind a grid to plan_reviews (plan-review trace)");
 
   // The trace is only useful with the verdict + critique columns, so pin them. Assert against the
   // visibly displayed `columns` (not `fields`, which also holds binding refs like orderBy.field) so

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[] = [
     {