@nanobpm/nano-workforce 0.55.0 → 0.57.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.57.0](https://github.com/nanobpm/nano-workforce/compare/v0.56.0...v0.57.0) (2026-08-13)
+
+
+### Features
+
+* **app-view:** show epic base branch in epics overview grid ([#159](https://github.com/nanobpm/nano-workforce/issues/159)) ([#164](https://github.com/nanobpm/nano-workforce/issues/164)) ([216cb0f](https://github.com/nanobpm/nano-workforce/commit/216cb0f515561fbaa646725593707ae6a2418246))
+
+# [0.56.0](https://github.com/nanobpm/nano-workforce/compare/v0.55.0...v0.56.0) (2026-08-13)
+
+
+### Features
+
+* correlate jobKeys to process/plan across supply report + cockpit (H6) ([#182](https://github.com/nanobpm/nano-workforce/issues/182)) ([f6e2b0d](https://github.com/nanobpm/nano-workforce/commit/f6e2b0d5f804c4c30863e5f5c66bbdc835025046)), closes [#142](https://github.com/nanobpm/nano-workforce/issues/142) [#152](https://github.com/nanobpm/nano-workforce/issues/152) [#149](https://github.com/nanobpm/nano-workforce/issues/149)
+
 # [0.55.0](https://github.com/nanobpm/nano-workforce/compare/v0.54.0...v0.55.0) (2026-08-13)
 
 

package/README.md

@@ -231,9 +231,17 @@ fleet"** form, or POST the same operation the form does:
 ```bash
 curl -sS -X POST http://localhost:3000/app/api/actions/start/plan-fanout \
   -H 'content-type: application/json' \
-  -d '{ "issue": "owner/repo#123" }'
+  -d '{ "issue": "owner/repo#123", "baseBranch": "epic/agent-protocol" }'
 ```
 
+`baseBranch` is **required** (ADR 0003) — it's the integration branch the whole fleet
+branches off and opens every PR against. A missing `epic/*` base is auto-created off the
+default branch's HEAD; a missing non-`epic/*` base is a `400` (must already exist). Two
+optional flags gate the dangerous cases: `confirmDefaultBase: true` is required to name the
+repository default branch as the base, and `allowSharedBase: true` is required when another
+active epic already targets the same custom base. See
+[ADR 0003](docs/adr/0003-epic-base-branch-admission.md) for the full admission model.
+
 ---
 
 ## Configuration

package/SPEC.md

@@ -466,8 +466,12 @@ scalar-only and cannot express the `tasks`/`results` lists, so the workers self-
 `plan_tasks` (one row per slice, tracking its `status`/`pr_key`/`summary`).
 
 **Entry points**: the epic page's "Hand an issue to the fleet" form or
-`POST /app/api/actions/start/plan-fanout` (`{ issue | url }`) — the same flat
-operation the form posts.
+`POST /app/api/actions/start/plan-fanout` (either `{ issue, baseBranch }` or
+`{ url, baseBranch }` — a `oneOf` naming the target by **exactly one** of `issue`
+(`owner/repo#123`) or `url`, plus optional `confirmDefaultBase`/`allowSharedBase`) —
+the same flat operation the form posts. `baseBranch`
+is required and admitted through the ADR 0003 gate (auto-create `epic/*`, confirm-default,
+shared-base guard).
 
 **Visibility**: the home page adds a **Plans** grid (Active: planning/dispatched;
 History: done/failed/abandoned) with a `plan_tasks` child grid showing each task's

package/app/agentGuide.ts

@@ -31,7 +31,7 @@ const RAW_GUIDE: string = (() => {
       "- `GET /status` — every PR in flight, with its engine `processKey` and any open escalation.",
       "- `GET /version` — which code is live.",
       "- `POST /actions/start/convergence-loop` — submit a PR (`{ pr, convergeOnly?, maxRounds?, dependsOn? }`).",
-      "- `POST /actions/start/plan-fanout` — submit an epic (`{ issue }`).",
+      "- `POST /actions/start/plan-fanout` — submit an epic (`{ issue, baseBranch }` or `{ url, baseBranch }`; base is required — a missing `epic/*` base is auto-created, and `confirmDefaultBase`/`allowSharedBase` gate the default-branch and shared-base cases — see ADR 0003).",
       "- `POST /actions/message` — answer an escalation (`escalation-answered`, correlate by PR key).",
       "",
       "Engine (Camunda-8 v2 REST) base for debugging: `__ENGINE__`.",

package/app/agentic/cockpit/supply-render.test.ts

@@ -74,3 +74,39 @@ test("renders an empty state when no workers are connected", () => {
   assert.equal(host.byData("empty", "true").length, 1);
   assert.equal(host.byClass("cockpit-supply-worker").length, 0);
 });
+
+test("H6: renders a process/plan cell that drills into the job's stream", () => {
+  const host = new FakeElement("body");
+  const drilled: string[] = [];
+  const correlated: SupplyReport = {
+    count: 1,
+    workers: [{ instance: "wk-a", identity: "leaf-1", stream: "job:6494", family: "senior", host: "h1", jobKeys: ["6494"], live: true, staleMs: 0 }],
+    leaves: [
+      {
+        token: "leaf-1",
+        workers: [{ instance: "wk-a", identity: "leaf-1", stream: "job:6494", family: "senior", host: "h1", jobKeys: ["6494"], live: true, staleMs: 0 }],
+      },
+    ],
+    correlations: [{ jobKey: "6494", stream: "job:6494", bpmnProcessId: "plan-fanout", processInstanceKey: "4612", planKey: "o/r#142" }],
+  };
+  renderSupply(host, doc, supplyView(correlated), { onDrill: (stream) => drilled.push(stream) });
+
+  const cell = host.byData("worker", "wk-a")[0]?.byClass("cockpit-supply-process")[0];
+  assert.ok(cell);
+  assert.equal(cell?.getAttribute("data-correlations"), "1");
+  const link = host.byClass("cockpit-correlation")[0];
+  assert.ok(link, "the correlation drill button was rendered");
+  assert.equal(link?.getAttribute("data-job-key"), "6494");
+  assert.equal(link?.getAttribute("data-stream"), "job:6494");
+  assert.equal(link?.text(), "plan-fanout · inst 4612 · o/r#142");
+  link?.dispatch("click");
+  assert.deepEqual(drilled, ["job:6494"], "drilling the process/plan cell opens the live job's stream");
+});
+
+test("H6: a worker with no correlation renders an em-dash process cell", () => {
+  const host = new FakeElement("body");
+  renderSupply(host, doc, supplyView(sample));
+  const cell = host.byData("worker", "wk-b")[0]?.byClass("cockpit-supply-process")[0];
+  assert.equal(cell?.text(), "—");
+  assert.equal(cell?.getAttribute("data-correlations"), "0");
+});

package/app/agentic/cockpit/supply-render.ts

@@ -69,6 +69,27 @@ function workerRow(doc: DocumentLike, worker: SupplyWorkerView, options: RenderS
   jobsCell.setAttribute("data-jobs", String(worker.jobs));
   row.appendChild(jobsCell);
 
+  // The process instance / plan each current job belongs to (H6). Each correlation is a drill button
+  // onto its jobKey-scoped relay stream, so the operator opens the LIVE job's terminal — not just the
+  // worker's default stream. Empty → "—" so the cell always renders something stable.
+  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 = "—";
+  } 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 !== undefined) {
+        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);
@@ -88,7 +109,7 @@ function leafSection(doc: DocumentLike, leaf: SupplyLeafView, options: RenderSup
   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"]) {
+  for (const label of ["worker", "family", "host", "jobs", "process / plan", "liveness"]) {
     head.appendChild(el(doc, "th", "cockpit-th", label));
   }
   thead.appendChild(head);

package/app/agentic/cockpit/supply-view.test.ts

@@ -11,6 +11,7 @@ function report(over: Partial<SupplyReport> = {}): SupplyReport {
     leaves: over.leaves ?? [],
     count: over.count ?? workers.length,
     generatedAt: over.generatedAt,
+    correlations: over.correlations,
   };
 }
 
@@ -74,3 +75,42 @@ test("sorts leaves by token and workers by instance, with per-leaf live counts",
   assert.equal(view.leaves[1]?.liveCount, 1);
   assert.equal(view.leaves[1]?.total, 2);
 });
+
+test("H6: resolves each worker's jobKeys into correlation views with a human label", () => {
+  const view = supplyView(
+    report({
+      workers: [{ instance: "wk-a", identity: "leaf-a", stream: "job:6494", jobKeys: ["6494"], live: true, staleMs: 0 }],
+      correlations: [
+        { jobKey: "6494", stream: "job:6494", processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "o/r#142" },
+      ],
+    }),
+  );
+  const w = view.workers[0];
+  assert.equal(w?.correlations.length, 1);
+  const c = w?.correlations[0];
+  assert.equal(c?.jobKey, "6494");
+  assert.equal(c?.stream, "job:6494");
+  assert.equal(c?.processInstanceKey, "4612");
+  assert.equal(c?.planKey, "o/r#142");
+  assert.equal(c?.label, "plan-fanout · implement-task · inst 4612 · o/r#142");
+});
+
+test("H6: a worker with no matching correlation renders an empty correlation list", () => {
+  const view = supplyView(
+    report({
+      workers: [{ instance: "wk-a", identity: "leaf-a", stream: "wk-a", jobKeys: ["nope"], live: true, staleMs: 0 }],
+      correlations: [{ jobKey: "other", stream: "job:other" }],
+    }),
+  );
+  assert.deepEqual(view.workers[0]?.correlations, []);
+});
+
+test("H6: a correlation with no engine context falls back to a job-key label", () => {
+  const view = supplyView(
+    report({
+      workers: [{ instance: "wk-a", identity: "leaf-a", stream: "job:6494", jobKeys: ["6494"], live: true, staleMs: 0 }],
+      correlations: [{ jobKey: "6494", stream: "job:6494" }],
+    }),
+  );
+  assert.equal(view.workers[0]?.correlations[0]?.label, "job 6494");
+});

package/app/agentic/cockpit/supply-view.ts

@@ -46,6 +46,25 @@ export interface SupplyLeafReport {
   readonly workers: readonly SupplyWorkerReport[];
 }
 
+/**
+ * One current job's engine context (H6 #149) — the process instance / plan a worker's terminal is
+ * lined up against. Mirrors the supply endpoint's `AgenticJobCorrelation`.
+ */
+export interface SupplyCorrelationReport {
+  /** The Camunda-8 job key. */
+  readonly jobKey: string;
+  /** The relay stream the job's terminal is on (`job:<jobKey>`). */
+  readonly stream: string;
+  /** The owning process instance key, if known. */
+  readonly processInstanceKey?: string;
+  /** The BPMN process id, if known. */
+  readonly bpmnProcessId?: string;
+  /** The BPMN element id, if known. */
+  readonly elementId?: string;
+  /** The plan / epic key, if known. */
+  readonly planKey?: string;
+}
+
 /** The supply-only report the cockpit polls (no demand fields — those are enrolment epic #152). */
 export interface SupplyReport {
   /** Supply grouped by leaf token. */
@@ -56,6 +75,26 @@ export interface SupplyReport {
   readonly count: number;
   /** When the snapshot was taken, ISO-8601 (optional). */
   readonly generatedAt?: string;
+  /** The engine context for every currently-processing job (H6), keyed by jobKey. */
+  readonly correlations?: readonly SupplyCorrelationReport[];
+}
+
+/** One current job's context as the cockpit renders it in a worker row (H6). */
+export interface JobCorrelationView {
+  /** The Camunda-8 job key. */
+  readonly jobKey: string;
+  /** The relay stream the job's terminal is on. */
+  readonly stream: string;
+  /** A single human label for the process instance / plan, e.g. `plan-fanout · inst 4612 · owner/repo#142`. */
+  readonly label: string;
+  /** The owning process instance key, if known. */
+  readonly processInstanceKey?: string;
+  /** The BPMN process id, if known. */
+  readonly bpmnProcessId?: string;
+  /** The BPMN element id, if known. */
+  readonly elementId?: string;
+  /** The plan / epic key, if known. */
+  readonly planKey?: string;
 }
 
 /** One worker row in the renderable supply view. */
@@ -72,6 +111,11 @@ export interface SupplyWorkerView {
   readonly jobKeys: readonly string[];
   /** The number of current jobs. */
   readonly jobs: number;
+  /**
+   * The engine context for each of this worker's current jobs (H6), sorted by jobKey — so the operator
+   * sees which process instance / plan the terminal belongs to. Empty when nothing correlates.
+   */
+  readonly correlations: readonly JobCorrelationView[];
   /** The coarse liveness grade for the status dot. */
   readonly liveness: Liveness;
   /** How long since the last liveness refresh, in ms. */
@@ -116,8 +160,38 @@ function liveness(worker: SupplyWorkerReport, staleAfterMs: number): Liveness {
   return worker.staleMs >= staleAfterMs ? "stale" : "live";
 }
 
-function workerView(worker: SupplyWorkerReport, staleAfterMs: number): SupplyWorkerView {
+/** A single stable human label for a job's process instance / plan (empty parts are dropped). */
+function correlationLabel(c: SupplyCorrelationReport): string {
+  const parts: string[] = [];
+  if (c.bpmnProcessId !== undefined) parts.push(c.bpmnProcessId);
+  if (c.elementId !== undefined) parts.push(c.elementId);
+  if (c.processInstanceKey !== undefined) parts.push(`inst ${c.processInstanceKey}`);
+  if (c.planKey !== undefined) parts.push(c.planKey);
+  return parts.length > 0 ? parts.join(" · ") : `job ${c.jobKey}`;
+}
+
+function correlationView(c: SupplyCorrelationReport): JobCorrelationView {
+  return {
+    jobKey: c.jobKey,
+    stream: c.stream,
+    label: correlationLabel(c),
+    ...(c.processInstanceKey !== undefined ? { processInstanceKey: c.processInstanceKey } : {}),
+    ...(c.bpmnProcessId !== undefined ? { bpmnProcessId: c.bpmnProcessId } : {}),
+    ...(c.elementId !== undefined ? { elementId: c.elementId } : {}),
+    ...(c.planKey !== undefined ? { planKey: c.planKey } : {}),
+  };
+}
+
+function workerView(
+  worker: SupplyWorkerReport,
+  staleAfterMs: number,
+  byJobKey: ReadonlyMap<string, SupplyCorrelationReport>,
+): SupplyWorkerView {
   const jobKeys = [...worker.jobKeys].sort((a, b) => a.localeCompare(b));
+  const correlations = jobKeys
+    .map((jobKey) => byJobKey.get(jobKey))
+    .filter((c): c is SupplyCorrelationReport => c !== undefined)
+    .map(correlationView);
   return {
     instance: worker.instance,
     identity: worker.identity,
@@ -126,6 +200,7 @@ function workerView(worker: SupplyWorkerReport, staleAfterMs: number): SupplyWor
     host: worker.host ?? "—",
     jobKeys,
     jobs: jobKeys.length,
+    correlations,
     liveness: liveness(worker, staleAfterMs),
     staleMs: worker.staleMs,
   };
@@ -142,9 +217,12 @@ const byInstance = (a: SupplyWorkerView, b: SupplyWorkerView) => a.instance.loca
 export function supplyView(report: SupplyReport, options: SupplyViewOptions = {}): SupplyView {
   const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
 
+  const byJobKey = new Map<string, SupplyCorrelationReport>();
+  for (const c of report.correlations ?? []) byJobKey.set(c.jobKey, c);
+
   const leaves: SupplyLeafView[] = 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,
@@ -154,7 +232,7 @@ export function supplyView(report: SupplyReport, options: SupplyViewOptions = {}
     })
     .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,

package/app/agentic/correlation.test.ts

@@ -0,0 +1,132 @@
+// Unit tests for the jobKey ⇄ process/plan correlation registry (ADR 0056, H6 / #149).
+//
+// The registry is the single canonical join the cockpit uses to line a worker's terminal up with the
+// process instance / plan it belongs to. These tests pin: the `job:<jobKey>` stream convention; the
+// two derived-from-one-write projections (instance→jobKeys and jobKey→context) staying consistent
+// across link / re-link (move) / releaseJob / releaseInstance; the presence `jobKeysFor` seam; the
+// drill `primaryStreamFor`; and the sorted snapshot.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  CorrelationRegistry,
+  currentCorrelation,
+  JOB_STREAM_PREFIX,
+  jobKeyOfStream,
+  jobStream,
+  setCurrentCorrelation,
+} from "./correlation.ts";
+
+test("jobStream / jobKeyOfStream are inverse over the job: convention", () => {
+  assert.equal(jobStream("6494"), `${JOB_STREAM_PREFIX}6494`);
+  assert.equal(jobKeyOfStream(jobStream("6494")), "6494");
+  assert.equal(jobKeyOfStream("wk-a"), undefined);
+  // A bare `job:` prefix carries no jobKey, so it maps to undefined (not "") — an empty jobKey is
+  // invalid (link() ignores it), so callers never mistake it for a valid key.
+  assert.equal(jobKeyOfStream("job:"), undefined);
+});
+
+test("link records context and both projections; resolve carries the job: stream", () => {
+  const reg = new CorrelationRegistry();
+  reg.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "o/r#142" });
+
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["6494"]);
+  const c = reg.resolve("6494");
+  assert.ok(c);
+  assert.equal(c.jobKey, "6494");
+  assert.equal(c.stream, "job:6494");
+  assert.equal(c.processInstanceKey, "4612");
+  assert.equal(c.bpmnProcessId, "plan-fanout");
+  assert.equal(c.elementId, "implement-task");
+  assert.equal(c.planKey, "o/r#142");
+  assert.equal(reg.count(), 1);
+});
+
+test("link ignores empty instance or jobKey", () => {
+  const reg = new CorrelationRegistry();
+  reg.link("", "6494");
+  reg.link("wk-a", "");
+  assert.equal(reg.count(), 0);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), []);
+});
+
+test("jobKeysFor returns the worker's jobs sorted; unknown instance is empty", () => {
+  const reg = new CorrelationRegistry();
+  reg.link("wk-a", "20");
+  reg.link("wk-a", "3");
+  reg.link("wk-a", "100");
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["100", "20", "3"]);
+  assert.deepEqual(reg.jobKeysFor("nobody"), []);
+});
+
+test("re-linking a jobKey to a new instance MOVES it (drops the stale reverse edge)", () => {
+  const reg = new CorrelationRegistry();
+  reg.link("wk-a", "6494");
+  reg.link("wk-b", "6494", { planKey: "o/r#142" });
+
+  assert.deepEqual(reg.jobKeysFor("wk-a"), []);
+  assert.deepEqual(reg.jobKeysFor("wk-b"), ["6494"]);
+  assert.equal(reg.resolve("6494")?.planKey, "o/r#142");
+  assert.equal(reg.count(), 1);
+});
+
+test("releaseJob removes one job from both projections", () => {
+  const reg = new CorrelationRegistry();
+  reg.link("wk-a", "6494");
+  reg.link("wk-a", "6495");
+  reg.releaseJob("6494");
+  assert.equal(reg.resolve("6494"), undefined);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["6495"]);
+  reg.releaseJob("nope"); // no-op
+  assert.equal(reg.count(), 1);
+});
+
+test("releaseInstance drops every job the worker held", () => {
+  const reg = new CorrelationRegistry();
+  reg.link("wk-a", "1");
+  reg.link("wk-a", "2");
+  reg.link("wk-b", "3");
+  reg.releaseInstance("wk-a");
+  assert.deepEqual(reg.jobKeysFor("wk-a"), []);
+  assert.equal(reg.resolve("1"), undefined);
+  assert.equal(reg.resolve("2"), undefined);
+  assert.equal(reg.resolve("3")?.jobKey, "3");
+  assert.equal(reg.count(), 1);
+});
+
+test("primaryStreamFor picks the lowest-sorted job's stream; undefined when none", () => {
+  const reg = new CorrelationRegistry();
+  assert.equal(reg.primaryStreamFor("wk-a"), undefined);
+  reg.link("wk-a", "50");
+  reg.link("wk-a", "10");
+  assert.equal(reg.primaryStreamFor("wk-a"), "job:10");
+});
+
+test("snapshot returns every job sorted by jobKey", () => {
+  const reg = new CorrelationRegistry();
+  reg.link("wk-a", "30");
+  reg.link("wk-b", "10");
+  reg.link("wk-c", "20");
+  const snap = reg.snapshot();
+  assert.equal(snap.count, 3);
+  assert.deepEqual(snap.correlations.map((c) => c.jobKey), ["10", "20", "30"]);
+  assert.deepEqual(snap.correlations.map((c) => c.stream), ["job:10", "job:20", "job:30"]);
+});
+
+test("link with no context leaves optional fields unset (no undefined holes)", () => {
+  const reg = new CorrelationRegistry();
+  reg.link("wk-a", "6494");
+  const c = reg.resolve("6494");
+  assert.ok(c);
+  assert.equal("processInstanceKey" in c, false);
+  assert.equal("planKey" in c, false);
+});
+
+test("currentCorrelation singleton is settable and clearable", () => {
+  assert.equal(currentCorrelation(), undefined);
+  const reg = new CorrelationRegistry();
+  setCurrentCorrelation(reg);
+  assert.equal(currentCorrelation(), reg);
+  setCurrentCorrelation(undefined);
+  assert.equal(currentCorrelation(), undefined);
+});

package/app/agentic/correlation.ts

@@ -0,0 +1,193 @@
+// nano-workforce — the jobKey ⇄ process-instance / plan correlation registry (ADR 0056, H6 / #149).
+//
+// The closing slice of the agentic-visibility epic (#142). It answers ADR 0056's open question —
+// "which process instance / plan is THIS terminal?" — by carrying the one fact neither presence (H1)
+// nor the relay (H3) holds: the association between a worker instance, the jobKeys it is currently
+// processing, and each jobKey's engine context (process instance, BPMN process, plan/epic).
+//
+// Why a separate registry (derivation over duplication): presence rows carry the worker's declared
+// enrolment capability but NO job attribution, and relay streams carry bytes but NO engine context.
+// The correlation is the single canonical join between them:
+//   - `jobKeysFor(instance)` is the resolver H1's `PresenceRegistry.snapshot({ jobKeysFor })` seam
+//     asks for, so a worker's current jobKeys light up in the supply feed / cockpit.
+//   - `resolve(jobKey)` gives the cockpit the process-instance / plan a terminal belongs to, so the
+//     drilled bytes line up with "that process instance / this plan".
+//   - the relay terminal for a job is the jobKey-scoped stream {@link jobStream} — a stable naming
+//     convention (`job:<jobKey>`) so the report can repoint a worker's drill stream at its live job
+//     without a second lookup table.
+//
+// Who populates it: the orchestrator that dispatches an agentic job to a worker (it holds the whole
+// job payload — jobKey, processInstanceKey, bpmnProcessId, and the plan/epic it belongs to) calls
+// {@link CorrelationRegistry.link} when the worker picks the job up and {@link CorrelationRegistry.releaseJob}
+// (or {@link CorrelationRegistry.releaseInstance} on disconnect) when it finishes. This is the seam
+// the end-to-end wiring test drives directly.
+//
+// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+// is untouched — correlation is an app-side observation, not a new wire type; ADVISORY — it is a
+// read-only join for visibility and NEVER hard-locks or gates a BPMN sequence flow.
+
+/** The relay-stream prefix for a jobKey-scoped terminal stream. */
+export const JOB_STREAM_PREFIX = "job:";
+
+/** The stable relay stream id a worker relays a job's terminal on: `job:<jobKey>`. */
+export function jobStream(jobKey: string): string {
+  return `${JOB_STREAM_PREFIX}${jobKey}`;
+}
+
+/**
+ * The jobKey encoded in a jobKey-scoped relay stream id, or undefined for any other stream.
+ * A bare `job:` prefix with no suffix carries no jobKey, so it maps to undefined too — keeping
+ * the "empty jobKey is invalid" invariant (`link()` ignores empty jobKeys) consistent for callers.
+ */
+export function jobKeyOfStream(stream: string): string | undefined {
+  if (!stream.startsWith(JOB_STREAM_PREFIX)) return undefined;
+  const jobKey = stream.slice(JOB_STREAM_PREFIX.length);
+  return jobKey === "" ? undefined : jobKey;
+}
+
+/** One job's engine context — the correlation a terminal is lined up against. */
+export interface JobCorrelation {
+  /** The Camunda-8 job key (the C8 job the worker activated). */
+  readonly jobKey: string;
+  /** The owning process instance key, if known. */
+  readonly processInstanceKey?: string;
+  /** The BPMN process id the job belongs to, if known. */
+  readonly bpmnProcessId?: string;
+  /** The BPMN element id (activity/task) the job is for, if known. */
+  readonly elementId?: string;
+  /** The plan / epic key this job is part of (e.g. `owner/repo#142`), if known. */
+  readonly planKey?: string;
+  /** The relay stream id the job's terminal is relayed on (`job:<jobKey>`). */
+  readonly stream: string;
+}
+
+/** The context an orchestrator supplies when a worker picks up a job (jobKey excluded — it is the key). */
+export type JobContext = Omit<JobCorrelation, "jobKey" | "stream">;
+
+/** The read-only correlation snapshot: every currently-linked job, sorted by jobKey. */
+export interface CorrelationSnapshot {
+  readonly correlations: readonly JobCorrelation[];
+  readonly count: number;
+}
+
+/**
+ * The advisory in-memory correlation registry. It holds two derived-from-one-write projections of the
+ * same `link` call: `instance → jobKeys` (the presence resolver) and `jobKey → context` (the cockpit
+ * lookup). A jobKey belongs to at most one instance at a time; re-linking it moves it (and drops the
+ * stale reverse edge) so a re-dispatched job never double-counts.
+ */
+export class CorrelationRegistry {
+  /** jobKey → the worker instance currently processing it. */
+  readonly #instanceOf = new Map<string, string>();
+  /** worker instance → the set of jobKeys it is currently processing (insertion-ordered). */
+  readonly #jobsOf = new Map<string, Set<string>>();
+  /** jobKey → its engine context. */
+  readonly #context = new Map<string, JobCorrelation>();
+
+  /**
+   * Link a worker instance to a job it is now processing, recording the job's engine context. A
+   * re-link of the same jobKey to a different instance moves it (dropping the old reverse edge); a
+   * re-link with fresh context overwrites the context (last write wins). Both args must be non-empty.
+   */
+  link(instance: string, jobKey: string, context: JobContext = {}): void {
+    if (instance === "" || jobKey === "") return;
+    const previousInstance = this.#instanceOf.get(jobKey);
+    if (previousInstance !== undefined && previousInstance !== instance) {
+      this.#jobsOf.get(previousInstance)?.delete(jobKey);
+      this.#pruneInstance(previousInstance);
+    }
+    this.#instanceOf.set(jobKey, instance);
+    const jobs = this.#jobsOf.get(instance) ?? new Set<string>();
+    jobs.add(jobKey);
+    this.#jobsOf.set(instance, jobs);
+    this.#context.set(jobKey, { jobKey, stream: jobStream(jobKey), ...stripUndefined(context) });
+  }
+
+  /** Release one job (it finished / moved on). No-op if it was never linked. */
+  releaseJob(jobKey: string): void {
+    const instance = this.#instanceOf.get(jobKey);
+    if (instance !== undefined) {
+      this.#jobsOf.get(instance)?.delete(jobKey);
+      this.#pruneInstance(instance);
+    }
+    this.#instanceOf.delete(jobKey);
+    this.#context.delete(jobKey);
+  }
+
+  /** Release every job a worker instance held (e.g. on disconnect / presence timeout). */
+  releaseInstance(instance: string): void {
+    const jobs = this.#jobsOf.get(instance);
+    if (!jobs) return;
+    for (const jobKey of jobs) {
+      this.#instanceOf.delete(jobKey);
+      this.#context.delete(jobKey);
+    }
+    this.#jobsOf.delete(instance);
+  }
+
+  /**
+   * The jobKeys a worker instance is currently processing, sorted for a stable render. This is the
+   * resolver injected into {@link PresenceRegistry.snapshot}'s `jobKeysFor` seam.
+   */
+  jobKeysFor(instance: string): string[] {
+    const jobs = this.#jobsOf.get(instance);
+    return jobs ? [...jobs].sort((a, b) => a.localeCompare(b)) : [];
+  }
+
+  /** The engine context for a jobKey, or undefined when it is not (or no longer) linked. */
+  resolve(jobKey: string): JobCorrelation | undefined {
+    return this.#context.get(jobKey);
+  }
+
+  /**
+   * The jobKey-scoped relay stream a worker's terminal should drill into: its lowest-sorted current
+   * jobKey's stream (a worker processes one job at a time in this fleet, but sorting keeps it stable
+   * if it ever holds several). Undefined when the worker has no linked job — the caller then falls
+   * back to the instance-keyed stream.
+   */
+  primaryStreamFor(instance: string): string | undefined {
+    const [first] = this.jobKeysFor(instance);
+    return first === undefined ? undefined : jobStream(first);
+  }
+
+  /** The number of currently-linked jobs. */
+  count(): number {
+    return this.#context.size;
+  }
+
+  /** The read-only correlation snapshot: every linked job, sorted by jobKey. */
+  snapshot(): CorrelationSnapshot {
+    const correlations = [...this.#context.values()].sort((a, b) => a.jobKey.localeCompare(b.jobKey));
+    return { correlations, count: correlations.length };
+  }
+
+  /** Drop a worker's reverse-edge entry once it holds no more jobs, so the map stays bounded. */
+  #pruneInstance(instance: string): void {
+    const jobs = this.#jobsOf.get(instance);
+    if (jobs && jobs.size === 0) this.#jobsOf.delete(instance);
+  }
+}
+
+/** Drop `undefined`-valued keys so the stored context never materializes an explicit `{ key: undefined }` hole. */
+function stripUndefined(context: JobContext): JobContext {
+  const { processInstanceKey, bpmnProcessId, elementId, planKey } = context;
+  return {
+    ...(processInstanceKey !== undefined ? { processInstanceKey } : {}),
+    ...(bpmnProcessId !== undefined ? { bpmnProcessId } : {}),
+    ...(elementId !== undefined ? { elementId } : {}),
+    ...(planKey !== undefined ? { planKey } : {}),
+  };
+}
+
+/** The live correlation registry from the most recent mount, so the supply report (H5) can read it. */
+let currentRegistry: CorrelationRegistry | undefined;
+
+/** The mounted correlation registry, or undefined before mount / after teardown. */
+export function currentCorrelation(): CorrelationRegistry | undefined {
+  return currentRegistry;
+}
+
+/** Install the live registry (called by the correlation family's `mount`). */
+export function setCurrentCorrelation(registry: CorrelationRegistry | undefined): void {
+  currentRegistry = registry;
+}