@nanobpm/nano-workforce 0.48.2 → 0.49.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.49.0](https://github.com/nanobpm/nano-workforce/compare/v0.48.2...v0.49.0) (2026-08-12)
+
+
+### Features
+
+* **ui:** per-epic operator workspace with live wave progress ([#138](https://github.com/nanobpm/nano-workforce/issues/138)) ([127888d](https://github.com/nanobpm/nano-workforce/commit/127888d5d2b66e1e9d1c85d015cbd65f3696216f)), closes [#137](https://github.com/nanobpm/nano-workforce/issues/137) [nanobpm/nano-workforce#137](https://github.com/nanobpm/nano-workforce/issues/137) [nanobpm/nano-ide#213](https://github.com/nanobpm/nano-ide/issues/213) [nanobpm/nano-ide#214](https://github.com/nanobpm/nano-ide/issues/214)
+
 ## [0.48.2](https://github.com/nanobpm/nano-workforce/compare/v0.48.1...v0.48.2) (2026-08-12)
 
 

package/app/plan.ts

@@ -55,6 +55,18 @@ export interface Plan {
   // Wave-merge barrier (007_wave_gate.sql): the wave index whose PRs the plan is currently
   // waiting to see MERGED before dispatching the next wave, or null when not parked at the barrier.
   gate_wave: number | null;
+  // Operator-visibility wave progress (022_plan_wave_progress.sql, #137): denormalised so the
+  // epics-index can show wave X/N at a glance. `wave_count` is the total waves (N); `current_wave`
+  // is the 0-based index of the wave the fleet is actively implementing (advanced by select-wave,
+  // pinned to wave_count-1 on completion). Display-only — never gates control flow. NULL until the
+  // plan is dispatched with tasks.
+  wave_count: number | null;
+  current_wave: number | null;
+  // Pre-formatted 1-based "X/N" progress string for the epics-index at-a-glance column
+  // (022_plan_wave_progress.sql, #137). The dataGrid has no per-cell templating (nano-ide#214),
+  // so this is projected alongside the numeric columns by the same worker writes. NULL until
+  // dispatched with tasks.
+  wave_label: string | null;
   // Per-plan capability token for the coordination blackboard (009_plan_blackboard.sql, #51).
   // Minted at plan start; baked into the blackboard URL handed to implementer agents. NULL for
   // plans created before the blackboard shipped.

package/db/migrations/022_plan_wave_progress.sql

@@ -0,0 +1,24 @@
+-- Operator visibility: at-a-glance wave X/N on the Epic Coordination view (issue #137).
+--
+-- `plan_tasks.wave` (005_plan_deps.sql) holds each task's 0-based wave, but the `plans`
+-- row itself carries no progress summary — so the epics-index grid had no way to show how
+-- far through its waves an epic is without joining/aggregating per row. Urban's datasource
+-- cannot read a SQL VIEW (gateway.ts schema() whitelists only type='table'), so following
+-- the codebase's existing convention (denormalised, worker-maintained pointers on `plans`
+-- like open_task_id / open_plan_round / gate_wave) we project two flat columns:
+--
+--   • wave_count   — total number of waves (N). Written by `record-plan` alongside
+--                    task_count, from the `waveCount` it already computes (app/waves.ts).
+--   • current_wave — the 0-based index of the wave the fleet is ACTIVELY implementing
+--                    (live). Initialised to 0 by `record-plan` at dispatch, advanced by
+--                    `select-wave` at the start of each wave, and pinned to wave_count-1 on
+--                    completion so a finished epic reads N/N. Display-only: it must never
+--                    gate control flow (that stays driven by the currentWave/waveCount/
+--                    gate_wave process state). NULL until the plan is dispatched with tasks.
+--   • wave_label   — the human "X/N" progress string (1-based), e.g. "2/3". The dataGrid
+--                    renders raw field values with no per-cell templating, so this pre-formats
+--                    (current_wave+1)/wave_count for the epics-index at-a-glance column. Kept in
+--                    lockstep with the two numeric columns by the same worker writes.
+ALTER TABLE plans ADD COLUMN wave_count INTEGER;
+ALTER TABLE plans ADD COLUMN current_wave INTEGER;
+ALTER TABLE plans ADD COLUMN wave_label TEXT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.48.2",
+  "version": "0.49.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -46,7 +46,7 @@
     "lint:fix": "biome check --write app operations workers pages components scripts e2e main.ts"
   },
   "dependencies": {
-    "@nanobpm/urban": "^0.43.0"
+    "@nanobpm/urban": "^0.44.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",

package/pages/epic-detail.page.json

@@ -0,0 +1,314 @@
+{
+  "schemaVersion": "1.0",
+  "title": "Epic",
+  "nodes": [
+    {
+      "type": "nav",
+      "id": "nav",
+      "props": {
+        "variant": "bar",
+        "sticky": true,
+        "title": "Nano Workforce",
+        "items": [
+          { "label": "Convergence", "page": "home" },
+          { "label": "Epics", "page": "epic" }
+        ]
+      }
+    },
+    {
+      "type": "text",
+      "id": "title",
+      "props": { "text": "Epic {{param}}", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "subtitle",
+      "props": {
+        "text": "This epic's plan, review trace, wave state, conflict graph, coordination notes, and trial-merge results. Sections start collapsed and remember your choice.",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "epic-plan",
+      "props": {
+        "title": "Plan",
+        "rowKey": "plan_key",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plans",
+          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "filter": [{ "field": "plan_key", "eqParam": true }]
+        },
+        "columns": [
+          { "field": "plan_key", "header": "Issue", "linkField": "issue_url" },
+          { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "wave_label", "header": "Wave" },
+          { "field": "task_count", "header": "Tasks" },
+          { "field": "open_task_id", "header": "Open escalation" },
+          { "field": "open_plan_round", "header": "Plan escalation round" },
+          { "field": "updated_at", "header": "Updated" }
+        ],
+        "rowActions": [
+          {
+            "label": "Proceed with plan",
+            "confirm": "Dispatch the current unapproved plan as a human override?",
+            "showWhenField": "open_plan_escalation_id",
+            "action": {
+              "path": "/app/api/actions/message",
+              "body": {
+                "name": "plan-escalation-answered",
+                "correlationKey": "{{row.plan_key}}",
+                "variables": { "directive": "proceed", "note": "Proceed override from the epic page." }
+              }
+            }
+          }
+        ],
+        "detail": {
+          "linkField": "issue_url",
+          "fields": [
+            { "field": "repo", "label": "Repository" },
+            { "field": "issue_number", "label": "Issue number" },
+            { "field": "base_branch", "label": "Base branch (blank = repo default)" },
+            { "field": "outcome", "label": "Outcome" },
+            { "field": "open_plan_findings", "label": "Open plan-review findings" },
+            { "field": "open_task_question", "label": "Open escalation question" }
+          ],
+          "form": {
+            "showWhenField": "open_plan_escalation_id",
+            "title": "Answer the open plan-review escalation",
+            "promptField": "open_plan_findings",
+            "inputKey": "note",
+            "inputLabel": "Revision directive note for the planner",
+            "submitLabel": "Revise plan",
+            "action": {
+              "path": "/app/api/actions/message",
+              "body": {
+                "name": "plan-escalation-answered",
+                "correlationKey": "{{row.plan_key}}",
+                "variables": { "directive": "revise", "note": "{{form.note}}" }
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "wave-state",
+      "props": {
+        "title": "Wave state",
+        "rowKey": "id",
+        "refreshMs": 5000,
+        "collapsible": true,
+        "defaultCollapsed": true,
+        "groupBy": "wave",
+        "groupLabel": "Wave",
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_tasks",
+          "orderBy": { "field": "wave", "dir": "asc" },
+          "filter": [
+            { "field": "plan_key", "eqParam": true },
+            { "field": "status", "in": ["pending", "opened", "escalated", "waiting-for-lane", "blocked"] }
+          ]
+        },
+        "tabs": [
+          {
+            "label": "Active",
+            "filter": [
+              { "field": "plan_key", "eqParam": true },
+              { "field": "status", "in": ["pending", "opened", "escalated", "waiting-for-lane", "blocked"] }
+            ]
+          },
+          {
+            "label": "Skipped",
+            "filter": [
+              { "field": "plan_key", "eqParam": true },
+              { "field": "status", "in": ["skipped"] }
+            ]
+          },
+          {
+            "label": "All",
+            "filter": [{ "field": "plan_key", "eqParam": true }]
+          }
+        ],
+        "columns": [
+          { "field": "wave", "header": "Wave" },
+          { "field": "task_id", "header": "Task" },
+          { "field": "title", "header": "Title" },
+          { "field": "status", "header": "Status" },
+          { "field": "pr_key", "header": "PR" },
+          { "field": "summary", "header": "Summary" },
+          { "field": "updated_at", "header": "Updated" }
+        ],
+        "detail": {
+          "fields": [
+            { "field": "open_question", "label": "Open question" },
+            { "field": "answer", "label": "Answer" },
+            { "field": "draft_pr_key", "label": "Draft PR" },
+            { "field": "prompt", "label": "Prompt" }
+          ]
+        }
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "plan-reviews",
+      "props": {
+        "title": "Plan review trace",
+        "refreshMs": 5000,
+        "collapsible": true,
+        "defaultCollapsed": true,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_reviews",
+          "orderBy": { "field": "round", "dir": "asc" },
+          "filter": [{ "field": "plan_key", "eqParam": true }]
+        },
+        "columns": [
+          { "field": "round", "header": "Round" },
+          { "field": "epoch", "header": "Epoch" },
+          { "field": "approved", "header": "Approved? (1/0)" },
+          { "field": "findings", "header": "Reviewer findings" },
+          { "field": "created_at", "header": "Recorded" }
+        ]
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "plan-review-escalations",
+      "props": {
+        "title": "Plan-review escalations",
+        "rowKey": "id",
+        "refreshMs": 5000,
+        "collapsible": true,
+        "defaultCollapsed": true,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_review_escalations",
+          "orderBy": { "field": "id", "dir": "desc" },
+          "filter": [{ "field": "plan_key", "eqParam": true }]
+        },
+        "columns": [
+          { "field": "epoch", "header": "Epoch" },
+          { "field": "round", "header": "Round" },
+          { "field": "findings", "header": "Findings" },
+          { "field": "status", "header": "Status" },
+          { "field": "directive", "header": "Directive" },
+          { "field": "note", "header": "Human note" },
+          { "field": "asked_at", "header": "Asked" },
+          { "field": "answered_at", "header": "Answered" }
+        ]
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "merge-exclusions",
+      "props": {
+        "title": "Conflict graph / who blocks whom",
+        "rowKey": "id",
+        "refreshMs": 5000,
+        "collapsible": true,
+        "defaultCollapsed": true,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_merge_exclusions",
+          "orderBy": { "field": "id", "dir": "asc" },
+          "filter": [{ "field": "plan_key", "eqParam": true }]
+        },
+        "columns": [
+          { "field": "task_a", "header": "Task A" },
+          { "field": "task_b", "header": "Task B" },
+          { "field": "files", "header": "Shared files" },
+          { "field": "source", "header": "Source" },
+          { "field": "updated_at", "header": "Updated" }
+        ]
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "coordination-notes",
+      "props": {
+        "title": "Coordination notes",
+        "rowKey": "id",
+        "refreshMs": 5000,
+        "collapsible": true,
+        "defaultCollapsed": true,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_blackboard",
+          "orderBy": { "field": "id", "dir": "asc" },
+          "filter": [{ "field": "plan_key", "eqParam": true }]
+        },
+        "columns": [
+          { "field": "wave", "header": "Wave" },
+          { "field": "author_task", "header": "Agent" },
+          { "field": "kind", "header": "Kind" },
+          { "field": "files", "header": "Files" },
+          { "field": "body", "header": "Note" },
+          { "field": "created_at", "header": "Posted" }
+        ]
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "trial-merge-results",
+      "props": {
+        "title": "Trial-merge results",
+        "rowKey": "id",
+        "refreshMs": 5000,
+        "collapsible": true,
+        "defaultCollapsed": true,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_trial_merges",
+          "orderBy": { "field": "created_at", "dir": "desc" },
+          "filter": [
+            { "field": "plan_key", "eqParam": true },
+            { "field": "result", "in": ["merge-conflict", "suite-failed"] },
+            { "field": "resolved", "in": [0] }
+          ]
+        },
+        "tabs": [
+          {
+            "label": "Needs attention",
+            "filter": [
+              { "field": "plan_key", "eqParam": true },
+              { "field": "result", "in": ["merge-conflict", "suite-failed"] },
+              { "field": "resolved", "in": [0] }
+            ]
+          },
+          {
+            "label": "Clean",
+            "filter": [
+              { "field": "plan_key", "eqParam": true },
+              { "field": "result", "in": ["clean"] }
+            ]
+          },
+          {
+            "label": "All",
+            "filter": [{ "field": "plan_key", "eqParam": true }]
+          }
+        ],
+        "columns": [
+          { "field": "wave", "header": "Wave" },
+          { "field": "result", "header": "Result" },
+          { "field": "heads", "header": "Heads" },
+          { "field": "conflicts", "header": "Conflicts" },
+          { "field": "failing", "header": "Failing" },
+          { "field": "summary", "header": "Summary" },
+          { "field": "created_at", "header": "Recorded" }
+        ]
+      }
+    }
+  ]
+}

package/pages/epic.page.json

@@ -7,10 +7,11 @@
       "id": "nav",
       "props": {
         "variant": "bar",
+        "sticky": true,
         "title": "Nano Workforce",
         "items": [
           { "label": "Convergence", "page": "home" },
-          { "label": "Epic", "page": "epic" }
+          { "label": "Epics", "page": "epic" }
         ]
       }
     },
@@ -23,7 +24,7 @@
       "type": "text",
       "id": "subtitle",
       "props": {
-        "text": "Hand an issue to the fleet to plan and implement it, then track each plan's review trace, wave state, merge-exclusion graph, coordination notes, and trial-merge gate results.",
+        "text": "Hand an issue to the fleet to plan and implement it, then open an epic to track its review trace, wave state, merge-exclusion graph, coordination notes, and trial-merge gate results.",
         "variant": "sub"
       }
     },
@@ -44,7 +45,7 @@
       "type": "dataGrid",
       "id": "epic-plans",
       "props": {
-        "title": "Plans",
+        "title": "Epics",
         "rowKey": "plan_key",
         "refreshMs": 5000,
         "data": {
@@ -66,241 +67,13 @@
           { "label": "All", "filter": [] }
         ],
         "columns": [
-          { "field": "plan_key", "header": "Issue", "linkField": "issue_url" },
+          { "field": "plan_key", "header": "Epic", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "wave_label", "header": "Wave" },
           { "field": "task_count", "header": "Tasks" },
-          { "field": "open_task_id", "header": "Open escalation" },
-          { "field": "open_plan_round", "header": "Plan escalation round" },
+          { "field": "open_plan_findings", "header": "Attention", "badge": { "tone": "danger", "label": "!" } },
+          { "field": "issue_number", "header": "Issue", "linkField": "issue_url" },
           { "field": "updated_at", "header": "Updated" }
-        ],
-        "rowActions": [
-          {
-            "label": "Proceed with plan",
-            "confirm": "Dispatch the current unapproved plan as a human override?",
-            "showWhenField": "open_plan_escalation_id",
-            "action": {
-              "path": "/app/api/actions/message",
-              "body": {
-                "name": "plan-escalation-answered",
-                "correlationKey": "{{row.plan_key}}",
-                "variables": { "directive": "proceed", "note": "Proceed override from the plans page." }
-              }
-            }
-          }
-        ],
-        "detail": {
-          "linkField": "issue_url",
-          "fields": [
-            { "field": "repo", "label": "Repository" },
-            { "field": "issue_number", "label": "Issue number" },
-            { "field": "base_branch", "label": "Base branch (blank = repo default)" },
-            { "field": "outcome", "label": "Outcome" },
-            { "field": "open_plan_findings", "label": "Open plan-review findings" },
-            { "field": "open_task_question", "label": "Open escalation question" }
-          ],
-          "form": {
-            "showWhenField": "open_plan_escalation_id",
-            "title": "Answer the open plan-review escalation",
-            "promptField": "open_plan_findings",
-            "inputKey": "note",
-            "inputLabel": "Revision directive note for the planner",
-            "submitLabel": "Revise plan",
-            "action": {
-              "path": "/app/api/actions/message",
-              "body": {
-                "name": "plan-escalation-answered",
-                "correlationKey": "{{row.plan_key}}",
-                "variables": { "directive": "revise", "note": "{{form.note}}" }
-              }
-            }
-          }
-        }
-      }
-    },
-    {
-      "type": "dataGrid",
-      "id": "plan-reviews",
-      "props": {
-        "title": "Plan review trace",
-        "refreshMs": 5000,
-        "data": {
-          "kind": "datasource",
-          "source": "app",
-          "table": "plan_reviews",
-          "orderBy": { "field": "round", "dir": "asc" }
-        },
-        "columns": [
-          { "field": "plan_key", "header": "Plan" },
-          { "field": "round", "header": "Round" },
-          { "field": "epoch", "header": "Epoch" },
-          { "field": "approved", "header": "Approved? (1/0)" },
-          { "field": "findings", "header": "Reviewer findings" },
-          { "field": "created_at", "header": "Recorded" }
-        ]
-      }
-    },
-    {
-      "type": "dataGrid",
-      "id": "plan-review-escalations",
-      "props": {
-        "title": "Plan-review escalations",
-        "rowKey": "id",
-        "refreshMs": 5000,
-        "data": {
-          "kind": "datasource",
-          "source": "app",
-          "table": "plan_review_escalations",
-          "orderBy": { "field": "id", "dir": "desc" }
-        },
-        "columns": [
-          { "field": "plan_key", "header": "Plan" },
-          { "field": "epoch", "header": "Epoch" },
-          { "field": "round", "header": "Round" },
-          { "field": "findings", "header": "Findings" },
-          { "field": "status", "header": "Status" },
-          { "field": "directive", "header": "Directive" },
-          { "field": "note", "header": "Human note" },
-          { "field": "asked_at", "header": "Asked" },
-          { "field": "answered_at", "header": "Answered" }
-        ]
-      }
-    },
-    {
-      "type": "dataGrid",
-      "id": "wave-state",
-      "props": {
-        "title": "Wave state",
-        "rowKey": "id",
-        "refreshMs": 5000,
-        "data": {
-          "kind": "datasource",
-          "source": "app",
-          "table": "plan_tasks",
-          "orderBy": { "field": "wave", "dir": "asc" },
-          "filter": [
-            { "field": "status", "in": ["pending", "opened", "escalated", "waiting-for-lane", "blocked"] }
-          ]
-        },
-        "tabs": [
-          {
-            "label": "Active",
-            "filter": [
-              { "field": "status", "in": ["pending", "opened", "escalated", "waiting-for-lane", "blocked"] }
-            ]
-          },
-          {
-            "label": "Skipped",
-            "filter": [{ "field": "status", "in": ["skipped"] }]
-          },
-          { "label": "All", "filter": [] }
-        ],
-        "columns": [
-          { "field": "plan_key", "header": "Plan" },
-          { "field": "wave", "header": "Wave" },
-          { "field": "task_id", "header": "Task" },
-          { "field": "title", "header": "Title" },
-          { "field": "status", "header": "Status" },
-          { "field": "pr_key", "header": "PR" },
-          { "field": "summary", "header": "Summary" },
-          { "field": "updated_at", "header": "Updated" }
-        ],
-        "detail": {
-          "fields": [
-            { "field": "open_question", "label": "Open question" },
-            { "field": "answer", "label": "Answer" },
-            { "field": "draft_pr_key", "label": "Draft PR" },
-            { "field": "prompt", "label": "Prompt" }
-          ]
-        }
-      }
-    },
-    {
-      "type": "dataGrid",
-      "id": "merge-exclusions",
-      "props": {
-        "title": "Conflict graph / who blocks whom",
-        "rowKey": "id",
-        "refreshMs": 5000,
-        "data": {
-          "kind": "datasource",
-          "source": "app",
-          "table": "plan_merge_exclusions",
-          "orderBy": { "field": "id", "dir": "asc" }
-        },
-        "columns": [
-          { "field": "plan_key", "header": "Plan" },
-          { "field": "task_a", "header": "Task A" },
-          { "field": "task_b", "header": "Task B" },
-          { "field": "files", "header": "Shared files" },
-          { "field": "source", "header": "Source" },
-          { "field": "updated_at", "header": "Updated" }
-        ]
-      }
-    },
-    {
-      "type": "dataGrid",
-      "id": "coordination-notes",
-      "props": {
-        "title": "Coordination notes",
-        "rowKey": "id",
-        "refreshMs": 5000,
-        "data": {
-          "kind": "datasource",
-          "source": "app",
-          "table": "plan_blackboard",
-          "orderBy": { "field": "id", "dir": "asc" }
-        },
-        "columns": [
-          { "field": "plan_key", "header": "Plan" },
-          { "field": "wave", "header": "Wave" },
-          { "field": "author_task", "header": "Agent" },
-          { "field": "kind", "header": "Kind" },
-          { "field": "files", "header": "Files" },
-          { "field": "body", "header": "Note" },
-          { "field": "created_at", "header": "Posted" }
-        ]
-      }
-    },
-    {
-      "type": "dataGrid",
-      "id": "trial-merge-results",
-      "props": {
-        "title": "Trial-merge results",
-        "rowKey": "id",
-        "refreshMs": 5000,
-        "data": {
-          "kind": "datasource",
-          "source": "app",
-          "table": "plan_trial_merges",
-          "orderBy": { "field": "created_at", "dir": "desc" },
-          "filter": [
-            { "field": "result", "in": ["merge-conflict", "suite-failed"] },
-            { "field": "resolved", "in": [0] }
-          ]
-        },
-        "tabs": [
-          {
-            "label": "Needs attention",
-            "filter": [
-              { "field": "result", "in": ["merge-conflict", "suite-failed"] },
-              { "field": "resolved", "in": [0] }
-            ]
-          },
-          {
-            "label": "Clean",
-            "filter": [{ "field": "result", "in": ["clean"] }]
-          },
-          { "label": "All", "filter": [] }
-        ],
-        "columns": [
-          { "field": "plan_key", "header": "Plan" },
-          { "field": "wave", "header": "Wave" },
-          { "field": "result", "header": "Result" },
-          { "field": "heads", "header": "Heads" },
-          { "field": "conflicts", "header": "Conflicts" },
-          { "field": "failing", "header": "Failing" },
-          { "field": "summary", "header": "Summary" },
-          { "field": "created_at", "header": "Recorded" }
         ]
       }
     }