@nanobpm/nano-workforce 0.55.0 → 0.56.0

package/app/agentic/families/correlation.family.ts

@@ -0,0 +1,39 @@
+// nano-workforce — the jobKey ⇄ process/plan correlation family (ADR 0056, H6 / #149).
+//
+// The closing slice's family module. Like every sibling it plugs into the H0 (#143) seam
+// (`../registry.ts`) as ONE NEW FILE and never edits `main.ts`, `drainAndExit`, or any shared boot
+// line — the auto-discovery loader (`../loader.ts`) finds it by the `*.family.ts` suffix and the seam
+// mounts + tears it down.
+//
+// Unlike presence/relay it owns NO channel message family: correlation is an app-side observation
+// (jobKey ⇄ process-instance / plan), fed by the orchestrator that dispatches agentic jobs, not a new
+// wire conversation (the Camunda-8 job protocol is untouched — ADR 0056). So `mount` simply installs a
+// fresh {@link CorrelationRegistry} as the process-wide singleton the supply report (H5) reads, and
+// `teardown` clears it. The registry is the single canonical join the cockpit uses to line a worker's
+// terminal up with "that process instance / this plan".
+
+import { CorrelationRegistry, setCurrentCorrelation } from "../correlation.ts";
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+
+/** The stable family name this module registers under the seam. */
+export const CORRELATION_FAMILY = "correlation";
+
+let registry: CorrelationRegistry | undefined;
+
+/** The H6 correlation family: install the correlation registry singleton on mount, clear on teardown. */
+export const family: AgenticFamily = {
+  name: CORRELATION_FAMILY,
+
+  mount(ctx: AgenticContext): void {
+    registry = new CorrelationRegistry();
+    setCurrentCorrelation(registry);
+    ctx.log.info("agentic correlation mounted", { family: CORRELATION_FAMILY });
+  },
+
+  teardown(): void {
+    registry = undefined;
+    setCurrentCorrelation(undefined);
+  },
+};
+
+export default family;

package/docs/agentic-cockpit.md

@@ -0,0 +1,135 @@
+# The agentic visibility cockpit — operator guide
+
+> **Scope: SUPPLY side only.** This guide covers the *supply* half of the agentic
+> visibility plane (ADR 0056) — the live worker registry and the drill-into-a-worker
+> terminal. The **demand** side — the demand×supply matrix by network,
+> missing-agent-type reds, and diversity-SLO lights — is a separate concern,
+> deferred to the **enrolment epic #152**. Nothing here shows demand.
+
+## What the cockpit shows you
+
+The cockpit is a read-only, advisory window onto the fleet of agentic workers
+connected to this app. It answers two operator questions:
+
+1. **Who is here?** — every connected worker, grouped by the leaf token it
+   authenticated under, with its declared **family** and **host**, its current
+   **jobs**, the **process instance / plan** each job belongs to, and a
+   **liveness** dot (live / stale / down).
+2. **What is that worker doing right now?** — click a worker (or a specific
+   process/plan) to open its **live terminal**, streamed off the relay.
+
+It is **advisory**: it never gates, locks, or influences any BPMN sequence flow.
+Turning the cockpit off changes nothing about how work runs — it only changes
+what you can *see*.
+
+## The architecture in one breath
+
+The cockpit rides the **agentic channel** — one WebSocket the app serves on its
+*own* port at `/agentic`, alongside its pages and hooks (no sidecar port). Four
+cooperating families sit on that channel, each mounted through a single
+extension **seam** (`app/agentic/registry.ts`) so no family ever touches the boot
+script:
+
+| Family | Module | What it owns |
+| --- | --- | --- |
+| **presence** (H1) | `app/agentic/families/presence.family.ts` | The live worker registry over the app's SQLite store — REGISTER / heartbeat / disconnect. |
+| **relay** (H3) | `app/agentic/families/relay.family.ts` | The bounded replay ring + three-lane QoS scheduler + transcript store — the terminal stream. |
+| **blackboard** (H4) | `app/agentic/families/blackboard.family.ts` | The advisory coordination blackboard. |
+| **correlation** (H6) | `app/agentic/families/correlation.family.ts` | The jobKey ⇄ process-instance / plan join. |
+
+The supply report the cockpit polls is served by
+`GET /app/api/agentic/supply` (`operations/getAgenticSupply.ts`), which projects
+the presence snapshot — enriched with correlation — into the view.
+
+## Reading a worker row
+
+Each row in a leaf-token section is one connected worker:
+
+- **worker** — the worker instance id. Click it to drill into its terminal on its
+  default stream.
+- **family** — the declared agent family (e.g. `senior`, `junior`), or `—`.
+- **host** — where the worker runs, or `—`.
+- **jobs** — the jobKeys the worker is currently processing. Empty (`—`) when the
+  worker is idle *or* when nothing has correlated a job to it yet.
+- **process / plan** — the engine context for each current job: the BPMN process,
+  element, process-instance key, and plan/epic key, rendered as
+  `plan-fanout · implement-task · inst 4612 · owner/repo#142`. **Click it to open
+  that job's live terminal** (`job:<jobKey>`), not just the worker's default
+  stream.
+- **liveness** — `live` (heartbeating), `stale` (no refresh past the threshold,
+  default 15 s), or `down` (disconnected). Rendered as a coloured dot.
+
+### How jobs and process/plan get populated — the correlation seam (H6)
+
+A worker's channel frames don't carry job attribution — the relay only knows a
+*stream id*. So correlation is an explicit, advisory **registry**
+(`app/agentic/correlation.ts`) that the orchestrator populates when it dispatches
+an agentic job:
+
+```ts
+import { currentCorrelation } from "./app/agentic/correlation.ts";
+
+// When a worker instance picks up a Camunda-8 job:
+currentCorrelation()?.link("wk-a", jobKey, {
+  processInstanceKey,
+  bpmnProcessId,
+  elementId,
+  planKey, // e.g. owner/repo#142
+});
+
+// When the job finishes (or the worker disconnects):
+currentCorrelation()?.releaseJob(jobKey);      // one job
+currentCorrelation()?.releaseInstance("wk-a"); // every job the worker held
+```
+
+One `link` write is the single canonical join — it projects to **both**
+directions the cockpit needs:
+
+- `instance → jobKeys` feeds the presence snapshot's `jobKeysFor` seam, so a
+  worker's **jobs** column lights up;
+- `jobKey → context` (with the derived `job:<jobKey>` **stream**) drives the
+  **process / plan** cell and the drill-in.
+
+A jobKey belongs to at most one worker at a time — re-linking it moves it. The
+relay stream a job's terminal rides is always `job:<jobKey>` (see
+`jobStream` / `jobKeyOfStream` in `app/agentic/correlation.ts`); repointing the
+drill stream there is what lets you open the *live job's* terminal from the
+process/plan cell.
+
+If the correlation family is not mounted (or nothing has linked a job), the
+report still serves — jobs stay empty and every worker drills into its default
+instance stream. Correlation is **additive and advisory**; its absence never
+errors.
+
+## Drilling into a worker — resume-from-offset
+
+Clicking a worker (or a process/plan) opens a `TerminalSession`
+(`@nanobpm/agentic/cockpit`) subscribed to the relay stream. The session is
+**resume-from-offset**: it tracks the offset just past the last chunk it applied,
+and on every (re)connect it re-subscribes from there. This means:
+
+- A **cockpit reconnect** replays only the un-applied tail — no lost output, no
+  double-printed lines (within the ring's retained window).
+- A **hub restart** (the ring is in memory and is lost; the app's SQLite store is
+  durable) is survived the same way: the worker reconnects and replays its
+  transcript on a bumped incarnation, and your terminal resumes from its own
+  offset — receiving only what it hadn't already seen. Incarnation fencing stops
+  a stale producer from double-attaching. This exact path is pinned by the
+  end-to-end wiring test (`test/agentic-e2e.test.ts`).
+
+## Liveness and cleanup
+
+Presence rows are kept live by worker heartbeats and removed on disconnect or
+when a worker ages out past the liveness TTL. On (re)mount the presence family
+reconciles the store against live connections, so a worker that vanished while
+the app was down does not linger as a ghost row after a restart.
+
+## What you will NOT find here (and where it lives)
+
+- **Demand×supply matrix, missing-agent-type reds, diversity-SLO lights** →
+  enrolment epic **#152**. They depend on the vocab / capability→SERVE /
+  diversity-SLO machinery this epic deliberately de-scopes. This report carries
+  no demand-side fields and the renderer draws none.
+- **Engine / job-protocol changes** → none. The visibility plane is app-tier
+  only; the Camunda-8 worker⇄engine job protocol is untouched. The agentic
+  channel is the only new conversation.

package/openapi.yaml

@@ -127,7 +127,7 @@ components:
           description: Declared host (where the worker runs), if any.
         jobKeys:
           type: array
-          description: The jobKeys this worker is currently processing (empty until the H6 correlation seam lands).
+          description: The jobKeys this worker is currently processing (populated by the H6 correlation registry).
           items:
             type: string
         live:
@@ -149,6 +149,32 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/AgenticSupplyWorker"
+    AgenticJobCorrelation:
+      type: object
+      description: One current job's engine context (H6) — lines a worker's terminal up with its process
+        instance / plan. The relay stream a job's terminal is on is the jobKey-scoped stream `job:<jobKey>`.
+      required:
+        - jobKey
+        - stream
+      properties:
+        jobKey:
+          type: string
+          description: The Camunda-8 job key the worker activated.
+        stream:
+          type: string
+          description: The relay stream id the job's terminal is relayed on (`job:<jobKey>`).
+        processInstanceKey:
+          type: string
+          description: The owning process instance key, if known.
+        bpmnProcessId:
+          type: string
+          description: The BPMN process id the job belongs to, if known.
+        elementId:
+          type: string
+          description: The BPMN element id (activity/task) the job is for, if known.
+        planKey:
+          type: string
+          description: The plan / epic key this job is part of (e.g. owner/repo#142), if known.
     AgenticSupplyReport:
       type: object
       description: The SUPPLY-ONLY visibility report — the live worker list grouped by leaf. No demand-side
@@ -172,6 +198,12 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/AgenticSupplyLeaf"
+        correlations:
+          type: array
+          description: The engine context (process instance / plan) for every jobKey currently being
+            processed, so the cockpit can line each worker's terminal up with its process instance / plan (H6).
+          items:
+            $ref: "#/components/schemas/AgenticJobCorrelation"
     VersionInfo:
       type: object
       description: The running app's identity (which code is actually live).

package/operations/getAgenticSupply.test.ts

@@ -12,6 +12,8 @@ import { encodeFrame, type Frame } from "@nanobpm/agentic/protocol";
 import type { SqliteDb } from "@nanobpm/agentic/presence";
 import type { AppApi, DataLayer } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
+import { currentCorrelation } from "../app/agentic/correlation.ts";
+import { family as correlationFamily } from "../app/agentic/families/correlation.family.ts";
 import { family } from "../app/agentic/families/presence.family.ts";
 import type { AgenticContext } from "../app/agentic/registry.ts";
 import { noopLog } from "../test/log.ts";
@@ -151,3 +153,41 @@ test("shared-secret guard rejects a missing secret when configured", async () =>
     else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
   }
 });
+
+test("H6: with the correlation family mounted, jobKeys populate, stream repoints, and correlations are reported", async () => {
+  const hub = await mountPresence(memSqlite());
+  correlationFamily.mount({
+    hub,
+    registry: hub.registry,
+    transport: undefined as never,
+    data: undefined,
+    log: noopLog(),
+  });
+  const correlation = currentCorrelation();
+  assert(correlation !== undefined, "the correlation family installs the singleton");
+  correlation.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "o/r#142" });
+  try {
+    const res = (await handler(input(), app)) as {
+      status: number;
+      body: {
+        workers: Array<Record<string, unknown>>;
+        correlations: Array<Record<string, unknown>>;
+      };
+    };
+    assertEquals(res.status, 200);
+    const w = res.body.workers[0];
+    assertEquals(w.jobKeys, ["6494"], "the correlation registry feeds the jobKeys seam");
+    assertEquals(w.stream, "job:6494", "the drill stream repoints at the live job's stream");
+    assertEquals(res.body.correlations.length, 1);
+    const c = res.body.correlations[0];
+    assertEquals(c.jobKey, "6494");
+    assertEquals(c.stream, "job:6494");
+    assertEquals(c.processInstanceKey, "4612");
+    assertEquals(c.bpmnProcessId, "plan-fanout");
+    assertEquals(c.planKey, "o/r#142");
+  } finally {
+    correlationFamily.teardown?.();
+    family.teardown?.();
+    await hub.close();
+  }
+});

package/operations/getAgenticSupply.ts

@@ -3,6 +3,12 @@
 // worker list — family, host, current jobs, liveness — grouped by leaf token, sourced from the H1
 // presence registry (#144). Read-only projection; it NEVER gates control flow (advisory-only, ADR 0056).
 //
+// H6 (#149) closes the loop: the correlation registry (`app/agentic/correlation.ts`) supplies the
+// `jobKeysFor` resolver the presence snapshot exposes as a seam, so each worker's current jobKeys light
+// up; each worker's drill `stream` is repointed at its jobKey-scoped relay stream (`job:<jobKey>`); and
+// the report carries the `correlations` — the process-instance / plan context for every current job —
+// so the cockpit lines a worker's terminal up with "that process instance / this plan".
+//
 // This is the supply half of the visibility plane only. The demand×supply matrix, missing-agent-type
 // reds, and diversity-SLO lights are DE-SCOPED to the enrolment epic #152 — this report carries no
 // demand-side fields, and the cockpit renders none.
@@ -10,22 +16,24 @@
 // The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`): when
 // NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset → open.
 
+import { type CorrelationRegistry, currentCorrelation, type JobCorrelation } from "../app/agentic/correlation.ts";
 import { currentPresenceRegistry, type SupplyWorker } from "../app/agentic/families/presence.family.ts";
 import { envVar } from "../app/version.ts";
-import type { AgenticSupplyReport, AgenticSupplyWorker } from "../nano-generated/api-io.d.ts";
+import type { AgenticJobCorrelation, AgenticSupplyReport, AgenticSupplyWorker } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 // The optional shared-secret guard: when NANO_PR_WEBHOOK_SECRET is set, callers must present it via
 // the x-hook-secret header. Captured once, at module load.
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
-// The relay stream id to subscribe when drilling into a worker's terminal. Presence keys the relay by
-// worker instance; the H6 correlation slice (#149) may repoint this at a jobKey-scoped stream.
-function toWorker(w: SupplyWorker): AgenticSupplyWorker {
+// Project a presence-registry row to the wire worker. The drill `stream` defaults to the worker
+// instance (H5) but is repointed at the worker's jobKey-scoped relay stream (`job:<jobKey>`) when the
+// correlation registry knows a current job for it (H6) — so drilling in opens the LIVE job's terminal.
+function toWorker(w: SupplyWorker, correlation: CorrelationRegistry | undefined): AgenticSupplyWorker {
   const out: AgenticSupplyWorker = {
     instance: w.instance,
     identity: w.identity,
-    stream: w.instance,
+    stream: correlation?.primaryStreamFor(w.instance) ?? w.instance,
     jobKeys: [...w.jobKeys],
     live: w.live,
     staleMs: w.staleMs,
@@ -35,6 +43,17 @@ function toWorker(w: SupplyWorker): AgenticSupplyWorker {
   return out;
 }
 
+// Project a correlation-registry entry to the wire correlation. Optional fields are only set when
+// known (biome bans `undefined`-valued keys crossing the boundary).
+function toCorrelation(c: JobCorrelation): AgenticJobCorrelation {
+  const out: AgenticJobCorrelation = { jobKey: c.jobKey, stream: c.stream };
+  if (c.processInstanceKey !== undefined) out.processInstanceKey = c.processInstanceKey;
+  if (c.bpmnProcessId !== undefined) out.bpmnProcessId = c.bpmnProcessId;
+  if (c.elementId !== undefined) out.elementId = c.elementId;
+  if (c.planKey !== undefined) out.planKey = c.planKey;
+  return out;
+}
+
 export default defineOperation("getAgenticSupply", async ({ req }, app) => {
   if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
     app.log.warn("getAgenticSupply rejected: missing/invalid shared secret");
@@ -44,16 +63,20 @@ export default defineOperation("getAgenticSupply", async ({ req }, app) => {
   const registry = currentPresenceRegistry();
   if (!registry) {
     // The presence family has not mounted (or has torn down) — no supply to report, not an error.
-    const empty: AgenticSupplyReport = { count: 0, generatedAt: new Date().toISOString(), workers: [], leaves: [] };
+    const empty: AgenticSupplyReport = { count: 0, generatedAt: new Date().toISOString(), workers: [], leaves: [], correlations: [] };
     return { status: 200, body: empty };
   }
 
-  const snapshot = registry.snapshot();
+  // Thread the H6 correlation registry (if mounted) as the presence snapshot's jobKeysFor resolver so a
+  // worker's current jobKeys populate; absent → jobKeys stay empty (advisory, never an error).
+  const correlation = currentCorrelation();
+  const snapshot = registry.snapshot(correlation ? { jobKeysFor: (instance) => correlation.jobKeysFor(instance) } : {});
   const report: AgenticSupplyReport = {
     count: snapshot.count,
     generatedAt: new Date().toISOString(),
-    workers: snapshot.workers.map(toWorker),
-    leaves: snapshot.leaves.map((leaf) => ({ token: leaf.token, workers: leaf.workers.map(toWorker) })),
+    workers: snapshot.workers.map((w) => toWorker(w, correlation)),
+    leaves: snapshot.leaves.map((leaf) => ({ token: leaf.token, workers: leaf.workers.map((w) => toWorker(w, correlation)) })),
+    correlations: correlation ? correlation.snapshot().correlations.map(toCorrelation) : [],
   };
   return { status: 200, body: report };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.55.0",
+  "version": "0.56.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",

package/pages/cockpit/cockpit.css

@@ -131,6 +131,23 @@
 
 .cockpit-worker:hover { color: #58a6ff; }
 
+.cockpit-supply-process { color: var(--cockpit-muted); }
+
+.cockpit-correlation {
+  background: none;
+  border: none;
+  color: var(--cockpit-text);
+  cursor: pointer;
+  display: block;
+  font: inherit;
+  padding: 0;
+  text-align: left;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.cockpit-correlation:hover { color: #58a6ff; }
+
 .cockpit-supply-liveness { color: var(--cockpit-muted); }
 
 .cockpit-supply-empty {

package/pages/cockpit/mount.js

@@ -33,8 +33,21 @@ function liveness(worker, staleAfterMs) {
   return worker.staleMs >= staleAfterMs ? "stale" : "live";
 }
 
-function workerView(worker, staleAfterMs) {
+function correlationLabel(c) {
+  const parts = [];
+  if (c.bpmnProcessId != null) parts.push(c.bpmnProcessId);
+  if (c.elementId != null) parts.push(c.elementId);
+  if (c.processInstanceKey != null) parts.push(`inst ${c.processInstanceKey}`);
+  if (c.planKey != null) parts.push(c.planKey);
+  return parts.length > 0 ? parts.join(" \u00b7 ") : `job ${c.jobKey}`;
+}
+
+function workerView(worker, staleAfterMs, byJobKey) {
   const jobKeys = [...(worker.jobKeys ?? [])].sort((a, b) => a.localeCompare(b));
+  const correlations = jobKeys
+    .map((jobKey) => byJobKey.get(jobKey))
+    .filter((c) => c != null)
+    .map((c) => ({ jobKey: c.jobKey, stream: c.stream, label: correlationLabel(c) }));
   return {
     instance: worker.instance,
     identity: worker.identity,
@@ -43,6 +56,7 @@ function workerView(worker, staleAfterMs) {
     host: worker.host ?? "\u2014",
     jobKeys,
     jobs: jobKeys.length,
+    correlations,
     liveness: liveness(worker, staleAfterMs),
     staleMs: worker.staleMs,
   };
@@ -50,9 +64,11 @@ function workerView(worker, staleAfterMs) {
 
 function supplyView(report, staleAfterMs) {
   const byInstance = (a, b) => a.instance.localeCompare(b.instance);
+  const byJobKey = new Map();
+  for (const c of report.correlations ?? []) byJobKey.set(c.jobKey, c);
   const leaves = (report.leaves ?? [])
     .map((leaf) => {
-      const workers = leaf.workers.map((w) => workerView(w, staleAfterMs)).sort(byInstance);
+      const workers = leaf.workers.map((w) => workerView(w, staleAfterMs, byJobKey)).sort(byInstance);
       return {
         token: leaf.token,
         workers,
@@ -61,7 +77,7 @@ function supplyView(report, staleAfterMs) {
       };
     })
     .sort((a, b) => a.token.localeCompare(b.token));
-  const workers = (report.workers ?? []).map((w) => workerView(w, staleAfterMs)).sort(byInstance);
+  const workers = (report.workers ?? []).map((w) => workerView(w, staleAfterMs, byJobKey)).sort(byInstance);
   return { leaves, workers, count: workers.length, live: workers.filter((w) => w.liveness === "live").length };
 }
 
@@ -100,6 +116,21 @@ function workerRow(doc, worker, onDrill) {
   const jobsCell = el(doc, "td", "cockpit-td cockpit-supply-jobs", worker.jobs === 0 ? "\u2014" : worker.jobKeys.join(", "));
   jobsCell.setAttribute("data-jobs", String(worker.jobs));
   row.appendChild(jobsCell);
+  const processCell = el(doc, "td", "cockpit-td cockpit-supply-process");
+  processCell.setAttribute("data-correlations", String(worker.correlations.length));
+  if (worker.correlations.length === 0) {
+    processCell.textContent = "\u2014";
+  } else {
+    for (const correlation of worker.correlations) {
+      const link = el(doc, "button", "cockpit-correlation", correlation.label);
+      link.setAttribute("type", "button");
+      link.setAttribute("data-job-key", correlation.jobKey);
+      link.setAttribute("data-stream", correlation.stream);
+      if (onDrill) link.addEventListener("click", () => onDrill(correlation.stream));
+      processCell.appendChild(link);
+    }
+  }
+  row.appendChild(processCell);
   const livenessCell = el(doc, "td", "cockpit-td cockpit-supply-liveness", worker.liveness);
   livenessCell.setAttribute("data-liveness", worker.liveness);
   row.appendChild(livenessCell);
@@ -116,7 +147,7 @@ function leafSection(doc, leaf, onDrill) {
   const table = el(doc, "table", "cockpit-supply-table");
   const thead = el(doc, "thead", "cockpit-supply-thead");
   const head = el(doc, "tr", "cockpit-supply-head");
-  for (const label of ["worker", "family", "host", "jobs", "liveness"]) head.appendChild(el(doc, "th", "cockpit-th", label));
+  for (const label of ["worker", "family", "host", "jobs", "process / plan", "liveness"]) head.appendChild(el(doc, "th", "cockpit-th", label));
   thead.appendChild(head);
   table.appendChild(thead);
   const tbody = el(doc, "tbody", "cockpit-supply-tbody");