@nanobpm/nano-workforce 0.54.0 → 0.56.0

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;
+}

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

@@ -0,0 +1,47 @@
+// Unit tests for the H6 correlation family module (ADR 0056, #149).
+//
+// The family installs the correlation-registry singleton on mount and clears it on teardown — the seam
+// through which the supply report (H5) and cockpit read a worker's process instance / plan. Unlike
+// presence/relay it owns no channel message family, so these tests exercise the mount/teardown
+// lifecycle and the singleton it manages, driven with a minimal AgenticContext.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { currentCorrelation } from "../correlation.ts";
+import type { AgenticContext } from "../registry.ts";
+import { noopLog } from "../../../test/log.ts";
+import { CORRELATION_FAMILY, family } from "./correlation.family.ts";
+
+function ctx(): AgenticContext {
+  return {
+    hub: undefined as never,
+    registry: undefined as never,
+    transport: undefined as never,
+    data: undefined,
+    log: noopLog(),
+  };
+}
+
+test("the correlation family declares its stable name", () => {
+  assertEquals(family.name, CORRELATION_FAMILY);
+  assertEquals(family.name, "correlation");
+});
+
+test("mount installs a fresh correlation registry singleton; teardown clears it", () => {
+  assertEquals(currentCorrelation(), undefined);
+  family.mount(ctx());
+  const reg = currentCorrelation();
+  assert(reg !== undefined, "mount installs the singleton");
+  reg.link("wk-a", "6494", { planKey: "o/r#142" });
+  assertEquals(reg.count(), 1);
+  family.teardown?.();
+  assertEquals(currentCorrelation(), undefined);
+});
+
+test("re-mount installs a fresh (empty) registry, not the torn-down one", () => {
+  family.mount(ctx());
+  currentCorrelation()?.link("wk-a", "1");
+  family.teardown?.();
+  family.mount(ctx());
+  assertEquals(currentCorrelation()?.count(), 0);
+  family.teardown?.();
+});

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.