@nanobpm/nano-workforce 0.53.0 → 0.55.0

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

@@ -0,0 +1,144 @@
+// The SUPPLY-only cockpit DOM renderer (ADR 0056, H5 / #148).
+//
+// Renders a {@link SupplyView} into a host element: the live worker list grouped by leaf token, each
+// worker showing family, host, current jobs, and a liveness dot. Clicking a worker calls
+// {@link RenderOptions.onDrill} with that worker's relay stream id, which the boot layer turns into a
+// live terminal. This renders only the *volatile* part of the page (re-rendered each poll pass); the
+// drill-in terminal is owned by {@link ../supply-boot.ts} in a persistent region so it survives a
+// refresh.
+//
+// It draws a supply-only projection ON PURPOSE — NOT the packaged `renderCockpit`, which draws the
+// demand×supply matrix, the missing-agent-type reds, and the diversity-SLO light. Those are deferred
+// to enrolment epic #152 (see `./supply-view.ts`). The genuinely reusable, correctness-critical parts
+// of the cockpit — the relay client and the resume-from-offset terminal session — ARE reused from
+// `@nanobpm/agentic/cockpit` by the boot layer; only this supply projection, which the package does
+// not provide, is authored here.
+//
+// Like the packaged renderer it builds against the structural {@link ElementLike} / {@link DocumentLike}
+// subset (reused from `@nanobpm/agentic/cockpit`) rather than the global `document`, so the real DOM
+// satisfies it at runtime AND a plain in-memory fake satisfies it for DOM-free Node tests (no `as`).
+import type { DocumentLike, ElementLike } from "@nanobpm/agentic/cockpit";
+import type { Liveness, SupplyLeafView, SupplyView, SupplyWorkerView } from "./supply-view.ts";
+
+export interface RenderSupplyOptions {
+  /** Called with a worker's relay stream id when the operator drills into it. */
+  readonly onDrill?: (stream: string) => void;
+}
+
+/** Handles into the rendered tree the caller may need. */
+export interface SupplyDom {
+  /** The freshly built root the view was rendered into. */
+  readonly root: ElementLike;
+}
+
+function el(doc: DocumentLike, tag: string, className?: string, text?: string): ElementLike {
+  const node = doc.createElement(tag);
+  if (className !== undefined) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function dot(doc: DocumentLike, liveness: Liveness): ElementLike {
+  const node = el(doc, "span", "cockpit-dot");
+  node.setAttribute("data-liveness", liveness);
+  return node;
+}
+
+function workerRow(doc: DocumentLike, worker: SupplyWorkerView, options: RenderSupplyOptions): ElementLike {
+  const row = el(doc, "tr", "cockpit-supply-worker");
+  row.setAttribute("data-worker", worker.instance);
+  row.setAttribute("data-liveness", worker.liveness);
+  row.setAttribute("data-stream", worker.stream);
+
+  const nameCell = el(doc, "td", "cockpit-td cockpit-supply-name");
+  nameCell.appendChild(dot(doc, worker.liveness));
+  const button = el(doc, "button", "cockpit-worker", worker.instance);
+  button.setAttribute("type", "button");
+  button.setAttribute("data-stream", worker.stream);
+  const onDrill = options.onDrill;
+  if (onDrill !== undefined) {
+    button.addEventListener("click", () => onDrill(worker.stream));
+  }
+  nameCell.appendChild(button);
+  row.appendChild(nameCell);
+
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-supply-family", worker.family));
+  row.appendChild(el(doc, "td", "cockpit-td cockpit-supply-host", worker.host));
+
+  const jobsCell = el(doc, "td", "cockpit-td cockpit-supply-jobs", worker.jobs === 0 ? "—" : worker.jobKeys.join(", "));
+  jobsCell.setAttribute("data-jobs", String(worker.jobs));
+  row.appendChild(jobsCell);
+
+  const livenessCell = el(doc, "td", "cockpit-td cockpit-supply-liveness", worker.liveness);
+  livenessCell.setAttribute("data-liveness", worker.liveness);
+  row.appendChild(livenessCell);
+
+  return row;
+}
+
+function leafSection(doc: DocumentLike, leaf: SupplyLeafView, options: RenderSupplyOptions): ElementLike {
+  const section = el(doc, "section", "cockpit-leaf");
+  section.setAttribute("data-leaf", leaf.token);
+
+  const header = el(doc, "div", "cockpit-leaf-head");
+  header.appendChild(el(doc, "span", "cockpit-leaf-name", leaf.token));
+  header.appendChild(el(doc, "span", "cockpit-leaf-count", `${leaf.liveCount}/${leaf.total} live`));
+  section.appendChild(header);
+
+  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));
+  }
+  thead.appendChild(head);
+  table.appendChild(thead);
+
+  const tbody = el(doc, "tbody", "cockpit-supply-tbody");
+  for (const worker of leaf.workers) {
+    tbody.appendChild(workerRow(doc, worker, options));
+  }
+  table.appendChild(tbody);
+  section.appendChild(table);
+  return section;
+}
+
+/**
+ * Render `view` into `host`, replacing whatever was there. Idempotent: call it again on every refresh
+ * to reflect the latest supply snapshot.
+ */
+export function renderSupply(
+  host: ElementLike,
+  doc: DocumentLike,
+  view: SupplyView,
+  options: RenderSupplyOptions = {},
+): SupplyDom {
+  host.replaceChildren();
+  const root = el(doc, "div", "cockpit-supply");
+  root.setAttribute("data-worker-count", String(view.count));
+  root.setAttribute("data-live-count", String(view.live));
+
+  const header = el(doc, "header", "cockpit-header");
+  header.appendChild(el(doc, "h1", "cockpit-title", "Workers — supply"));
+  const summary = el(doc, "span", "cockpit-supply-summary", `${view.live}/${view.count} live`);
+  summary.setAttribute("data-summary", "supply");
+  header.appendChild(summary);
+  root.appendChild(header);
+
+  if (view.count === 0) {
+    const empty = el(doc, "div", "cockpit-supply-empty", "No workers connected.");
+    empty.setAttribute("data-empty", "true");
+    root.appendChild(empty);
+    host.appendChild(root);
+    return { root };
+  }
+
+  const list = el(doc, "div", "cockpit-supply-list");
+  for (const leaf of view.leaves) {
+    list.appendChild(leafSection(doc, leaf, options));
+  }
+  root.appendChild(list);
+
+  host.appendChild(root);
+  return { root };
+}

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

@@ -0,0 +1,76 @@
+// Unit tests for the SUPPLY cockpit view-model projection (H5 / #148).
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { type SupplyReport, supplyView } from "./supply-view.ts";
+
+function report(over: Partial<SupplyReport> = {}): SupplyReport {
+  const workers = over.workers ?? [];
+  return {
+    workers,
+    leaves: over.leaves ?? [],
+    count: over.count ?? workers.length,
+    generatedAt: over.generatedAt,
+  };
+}
+
+test("grades liveness: down when disconnected, stale past the threshold, else live", () => {
+  const view = supplyView(
+    report({
+      workers: [
+        { instance: "a", identity: "t", stream: "a", jobKeys: [], live: false, staleMs: 0 },
+        { instance: "b", identity: "t", stream: "b", jobKeys: [], live: true, staleMs: 20_000 },
+        { instance: "c", identity: "t", stream: "c", jobKeys: [], live: true, staleMs: 100 },
+      ],
+    }),
+    { staleAfterMs: 15_000 },
+  );
+  assert.equal(view.workers.find((w) => w.instance === "a")?.liveness, "down");
+  assert.equal(view.workers.find((w) => w.instance === "b")?.liveness, "stale");
+  assert.equal(view.workers.find((w) => w.instance === "c")?.liveness, "live");
+  assert.equal(view.count, 3);
+  assert.equal(view.live, 1);
+});
+
+test("defaults absent family/host to a stable dash and counts + sorts jobKeys", () => {
+  const view = supplyView(
+    report({
+      workers: [{ instance: "a", identity: "t", stream: "a", jobKeys: ["z", "a"], live: true, staleMs: 0 }],
+    }),
+  );
+  const w = view.workers[0];
+  assert.equal(w?.family, "—");
+  assert.equal(w?.host, "—");
+  assert.deepEqual(w?.jobKeys, ["a", "z"]);
+  assert.equal(w?.jobs, 2);
+});
+
+test("sorts leaves by token and workers by instance, with per-leaf live counts", () => {
+  const view = supplyView(
+    report({
+      leaves: [
+        {
+          token: "leaf-b",
+          workers: [
+            { instance: "b2", identity: "leaf-b", stream: "b2", jobKeys: [], live: true, staleMs: 0 },
+            { instance: "b1", identity: "leaf-b", stream: "b1", jobKeys: [], live: false, staleMs: 0 },
+          ],
+        },
+        {
+          token: "leaf-a",
+          workers: [{ instance: "a1", identity: "leaf-a", stream: "a1", jobKeys: [], live: true, staleMs: 0 }],
+        },
+      ],
+    }),
+  );
+  assert.deepEqual(
+    view.leaves.map((l) => l.token),
+    ["leaf-a", "leaf-b"],
+  );
+  assert.deepEqual(
+    view.leaves[1]?.workers.map((w) => w.instance),
+    ["b1", "b2"],
+  );
+  assert.equal(view.leaves[1]?.liveCount, 1);
+  assert.equal(view.leaves[1]?.total, 2);
+});

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

@@ -0,0 +1,165 @@
+// The SUPPLY-only cockpit view-model (ADR 0056, H5 / #148).
+//
+// A pure, deterministic projection of the app's SUPPLY report — the live worker registry (H1 #144)
+// carried over the agentic channel — onto the shape the supply cockpit renders: a per-leaf-token
+// list of connected workers with family, host, current jobs, and liveness.
+//
+// This is DELIBERATELY the supply half only. The DEMAND×supply matrix, the missing-agent-type reds,
+// and the diversity-SLO lights (the packaged `@nanobpm/agentic/cockpit` view/render draws those from
+// a `DemandSupplyReport`) are OUT OF SCOPE for this epic (#142) — they depend on the vocab /
+// capability→SERVE / diversity-SLO machinery deferred to the paired enrolment epic #152. So this
+// module models a supply-only report and never fabricates demand data.
+//
+// Like the packaged `cockpit/view.ts` it is framework-free and side-effect-free: the same report
+// always yields the same {@link SupplyView}, so it is safe to snapshot in a test and to render
+// identically whether the page is embedded in the console (App View, ADR 0057) or served standalone.
+
+/** A worker's coarse liveness grade, rendered as a coloured dot. */
+export type Liveness = "live" | "stale" | "down";
+
+/** One connected worker as the app's supply feed reports it (mirrors the H1 registry snapshot row). */
+export interface SupplyWorkerReport {
+  /** The worker instance id. */
+  readonly instance: string;
+  /** The authenticated ADR 0028 principal — the leaf token this worker registered under. */
+  readonly identity: string;
+  /**
+   * The relay stream to drill into for this worker's live terminal. The supply endpoint defaults it
+   * to the worker instance; the correlation slice (H6 #149) may repoint it at a jobKey-keyed stream.
+   */
+  readonly stream: string;
+  /** Declared family (enrolment attribute), if any. */
+  readonly family?: string;
+  /** Declared host (where the worker runs), if any. */
+  readonly host?: string;
+  /** The jobKeys the worker is currently processing (empty until H6 wires the resolver). */
+  readonly jobKeys: readonly string[];
+  /** Whether the worker's channel connection is still open. */
+  readonly live: boolean;
+  /** How long since the worker's last liveness refresh, in ms. */
+  readonly staleMs: number;
+}
+
+/** The supply registered under one leaf token. */
+export interface SupplyLeafReport {
+  readonly token: string;
+  readonly workers: readonly SupplyWorkerReport[];
+}
+
+/** The supply-only report the cockpit polls (no demand fields — those are enrolment epic #152). */
+export interface SupplyReport {
+  /** Supply grouped by leaf token. */
+  readonly leaves: readonly SupplyLeafReport[];
+  /** Every connected worker, flat. */
+  readonly workers: readonly SupplyWorkerReport[];
+  /** The number of connected workers. */
+  readonly count: number;
+  /** When the snapshot was taken, ISO-8601 (optional). */
+  readonly generatedAt?: string;
+}
+
+/** One worker row in the renderable supply view. */
+export interface SupplyWorkerView {
+  readonly instance: string;
+  readonly identity: string;
+  /** The relay stream to open when the operator drills into this worker. */
+  readonly stream: string;
+  /** Declared family, or `"—"` when absent (so the cell always renders something stable). */
+  readonly family: string;
+  /** Declared host, or `"—"` when absent. */
+  readonly host: string;
+  /** The worker's current jobKeys, sorted. */
+  readonly jobKeys: readonly string[];
+  /** The number of current jobs. */
+  readonly jobs: number;
+  /** The coarse liveness grade for the status dot. */
+  readonly liveness: Liveness;
+  /** How long since the last liveness refresh, in ms. */
+  readonly staleMs: number;
+}
+
+/** One leaf-token section in the renderable supply view. */
+export interface SupplyLeafView {
+  readonly token: string;
+  readonly workers: readonly SupplyWorkerView[];
+  /** Workers under this leaf currently graded `live`. */
+  readonly liveCount: number;
+  /** Total workers under this leaf. */
+  readonly total: number;
+}
+
+/** The full renderable supply view. */
+export interface SupplyView {
+  /** Supply grouped by leaf token, sorted by token. */
+  readonly leaves: readonly SupplyLeafView[];
+  /** Every worker, flat, sorted by instance. */
+  readonly workers: readonly SupplyWorkerView[];
+  /** The number of workers. */
+  readonly count: number;
+  /** The number of workers graded `live`. */
+  readonly live: number;
+}
+
+/** Options for {@link supplyView}. */
+export interface SupplyViewOptions {
+  /**
+   * A live worker whose last refresh is older than this (ms) is graded `stale` rather than `live`.
+   * A disconnected worker is always `down`. Default 15000.
+   */
+  readonly staleAfterMs?: number;
+}
+
+const DEFAULT_STALE_AFTER_MS = 15_000;
+
+function liveness(worker: SupplyWorkerReport, staleAfterMs: number): Liveness {
+  if (!worker.live) return "down";
+  return worker.staleMs >= staleAfterMs ? "stale" : "live";
+}
+
+function workerView(worker: SupplyWorkerReport, staleAfterMs: number): SupplyWorkerView {
+  const jobKeys = [...worker.jobKeys].sort((a, b) => a.localeCompare(b));
+  return {
+    instance: worker.instance,
+    identity: worker.identity,
+    stream: worker.stream,
+    family: worker.family ?? "—",
+    host: worker.host ?? "—",
+    jobKeys,
+    jobs: jobKeys.length,
+    liveness: liveness(worker, staleAfterMs),
+    staleMs: worker.staleMs,
+  };
+}
+
+const byInstance = (a: SupplyWorkerView, b: SupplyWorkerView) => a.instance.localeCompare(b.instance);
+
+/**
+ * Derive the renderable supply view from the app's supply-only report.
+ *
+ * Pure and total: it re-sorts leaves by token and workers by instance so the derived view is stable
+ * and diff-friendly regardless of the report's incoming order; no input mutates and no I/O happens.
+ */
+export function supplyView(report: SupplyReport, options: SupplyViewOptions = {}): SupplyView {
+  const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+
+  const leaves: SupplyLeafView[] = report.leaves
+    .map((leaf) => {
+      const workers = leaf.workers.map((w) => workerView(w, staleAfterMs)).sort(byInstance);
+      return {
+        token: leaf.token,
+        workers,
+        liveCount: workers.filter((w) => w.liveness === "live").length,
+        total: workers.length,
+      };
+    })
+    .sort((a, b) => a.token.localeCompare(b.token));
+
+  const workers = report.workers.map((w) => workerView(w, staleAfterMs)).sort(byInstance);
+
+  return {
+    leaves,
+    workers,
+    count: workers.length,
+    live: workers.filter((w) => w.liveness === "live").length,
+  };
+}

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

@@ -0,0 +1,189 @@
+// Tests for H4's channel-side `blackboard` family module (#147). These prove the generalized
+// agentic-channel path is a faithful bridge to the SAME per-plan board the HTTP hook serves:
+//   - a channel `append` frame writes the very rows `readBlackboard(data, planKey)` (the HTTP path)
+//     reads back — one canonical store, no drift surface;
+//   - `file-claim` conflict-of-intent is reported on the channel exactly as over HTTP;
+//   - board scope is capability-derived (the plan's blackboard token → plan_key), so a connection
+//     only ever touches the board its credential authorises;
+//   - an unknown/absent credential is rejected (advisory — the frame is dropped, never a hard-lock).
+import test from "node:test";
+import { AgenticHub, type HubConnection, sharedSecretAuthenticator } from "@nanobpm/agentic/channel";
+import type { ChannelTransport, HandshakeRequest } from "@nanobpm/agentic/channel";
+import type { Frame } from "@nanobpm/agentic/protocol";
+import { assert, assertEquals } from "#test-assert";
+import { noopLog } from "../../../test/log.ts";
+import { memBlackboardData } from "../../../test/blackboardDb.ts";
+import { readBlackboard } from "../../blackboard.ts";
+import type { AgenticContext } from "../registry.ts";
+import { family } from "./blackboard.family.ts";
+
+/** A do-nothing transport just to satisfy the hub constructor; the tests drive the router directly. */
+function fakeTransport(): ChannelTransport {
+  return {
+    onConnection() {},
+    address: null,
+    async close() {},
+  };
+}
+
+/** Build a hub + mount the blackboard family over a real in-memory DataLayer. */
+function mountFamily() {
+  const { data, db, close } = memBlackboardData();
+  const hub = new AgenticHub({
+    transport: fakeTransport(),
+    authenticator: sharedSecretAuthenticator({ secret: "s3cr3t" }),
+    sweepIntervalMs: 0,
+  });
+  const ctx: AgenticContext = {
+    hub,
+    registry: hub.registry,
+    // The blackboard family never touches the transport; a minimal stand-in is enough.
+    transport: undefined as unknown as AgenticContext["transport"],
+    data,
+    log: noopLog(),
+  };
+  family.mount(ctx);
+  return { hub, data, db, close };
+}
+
+/** A HubConnection whose sends are captured, presenting `credential` at the handshake. */
+function conn(hub: AgenticHub, credential: string | undefined, sent: Frame[]): HubConnection {
+  const handshake: HandshakeRequest = credential === undefined ? {} : { credential };
+  return {
+    id: `c-${credential ?? "anon"}`,
+    identity: "peer",
+    handshake,
+    registry: hub.registry,
+    send: (frame) => sent.push(frame),
+    close() {},
+  };
+}
+
+function seedToken(db: { run(sql: string, params?: unknown[]): unknown }, planKey: string, token: string): void {
+  db.run("INSERT INTO plans (plan_key, blackboard_token) VALUES (?, ?)", [planKey, token]);
+}
+
+function appendFrame(seq: number, payload: Record<string, unknown>): Frame {
+  return { lane: "control", family: "blackboard", seq, payload: { op: "append", ...payload } };
+}
+
+function readFrame(seq: number, since?: number): Frame {
+  return { lane: "control", family: "blackboard", seq, payload: since === undefined ? { op: "read" } : { op: "read", since } };
+}
+
+test("channel append writes the SAME board the HTTP readBlackboard path reads", async () => {
+  const { hub, data, db, close } = mountFamily();
+  try {
+    seedToken(db, "o/r#1", "tok-1");
+    const sent: Frame[] = [];
+    const c = conn(hub, "tok-1", sent);
+
+    const ran = await hub.router.route(
+      appendFrame(1, { authorTask: "gap-2", kind: "note", body: "hello board" }),
+      c,
+    );
+    assertEquals(ran, true);
+    assertEquals(sent.length, 1);
+    const reply = sent[0].payload as { op: string; inserted: boolean; id: number };
+    assertEquals(reply.op, "append");
+    assertEquals(reply.inserted, true);
+    assert(reply.id > 0);
+
+    // Parity: the HTTP-side reader sees exactly what the channel wrote, under the same plan scope.
+    const entries = await readBlackboard(data, "o/r#1");
+    assertEquals(entries.length, 1);
+    assertEquals(entries[0].author_task, "gap-2");
+    assertEquals(entries[0].body, "hello board");
+    assertEquals(entries[0].kind, "note");
+  } finally {
+    await hub.close();
+    close();
+  }
+});
+
+test("channel file-claim reports conflicts with a prior claim by another author", async () => {
+  const { hub, data, db, close } = mountFamily();
+  try {
+    seedToken(db, "o/r#1", "tok-1");
+    const sent: Frame[] = [];
+    const c = conn(hub, "tok-1", sent);
+
+    await hub.router.route(
+      appendFrame(1, { authorTask: "gap-1", kind: "file-claim", files: ["engine/state.rs"], body: "own state.rs" }),
+      c,
+    );
+    await hub.router.route(
+      appendFrame(2, { authorTask: "gap-2", kind: "file-claim", files: ["engine/state.rs"], body: "also want state.rs" }),
+      c,
+    );
+
+    const second = sent[1].payload as { conflicts: { authorTask: string; file: string }[] };
+    assertEquals(second.conflicts.length, 1);
+    assertEquals(second.conflicts[0].authorTask, "gap-1");
+    assertEquals(second.conflicts[0].file, "engine/state.rs");
+
+    // And both rows landed on the shared board.
+    const entries = await readBlackboard(data, "o/r#1");
+    assertEquals(entries.length, 2);
+  } finally {
+    await hub.close();
+    close();
+  }
+});
+
+test("channel read returns entries appended over HTTP (bidirectional bridge parity)", async () => {
+  const { hub, data, db, close } = mountFamily();
+  try {
+    seedToken(db, "o/r#1", "tok-1");
+    // Write via the HTTP-path adapter…
+    const { appendEntry } = await import("../../blackboard.ts");
+    await appendEntry(data, "o/r#1", { author_task: "gap-3", kind: "note", body: "via http" });
+
+    // …and read it back over the channel.
+    const sent: Frame[] = [];
+    const ran = await hub.router.route(readFrame(9), conn(hub, "tok-1", sent));
+    assertEquals(ran, true);
+    const reply = sent[0].payload as { op: string; entries: { authorTask: string; body: string }[] };
+    assertEquals(reply.op, "read");
+    assertEquals(reply.entries.length, 1);
+    assertEquals(reply.entries[0].authorTask, "gap-3");
+    assertEquals(reply.entries[0].body, "via http");
+  } finally {
+    await hub.close();
+    close();
+  }
+});
+
+test("an unknown credential is rejected — no board is touched, no reply sent", async () => {
+  const { hub, data, db, close } = mountFamily();
+  try {
+    seedToken(db, "o/r#1", "tok-1");
+    const sent: Frame[] = [];
+    const ran = await hub.router.route(
+      appendFrame(1, { authorTask: "gap-2", kind: "note", body: "should not land" }),
+      conn(hub, "bogus-token", sent),
+    );
+    assertEquals(ran, true); // the handler ran (and rejected) — the family owns the frame
+    assertEquals(sent.length, 0); // no reply: scope could not be resolved
+    // Nothing was written under any scope.
+    const [{ n }] = db.all<{ n: number }>("SELECT COUNT(*) AS n FROM agentic_blackboard");
+    assertEquals(n, 0);
+    assertEquals((await readBlackboard(data, "o/r#1")).length, 0);
+  } finally {
+    await hub.close();
+    close();
+  }
+});
+
+test("an absent credential is rejected too", async () => {
+  const { hub, db, close } = mountFamily();
+  try {
+    seedToken(db, "o/r#1", "tok-1");
+    const sent: Frame[] = [];
+    await hub.router.route(appendFrame(1, { kind: "note", body: "x" }), conn(hub, undefined, sent));
+    assertEquals(sent.length, 0);
+  } finally {
+    await hub.close();
+    close();
+  }
+});

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

@@ -0,0 +1,69 @@
+// nano-workforce — the agentic-channel `blackboard` family (ADR 0056, H4 / #147).
+//
+// This is H4's ONE new file plugged into the H0 (#143) family-registration seam. It mounts
+// `@nanobpm/agentic/blackboard`'s `blackboard` message family on the app-tier hub, backed by the
+// SAME `BlackboardStore` — over the SAME app SQLite DataLayer (`ctx.data.source().db`) — that the
+// legacy `/app/api/hooks/blackboard` HTTP hook now uses (see `app/blackboard.ts`). One canonical
+// store, one table (`agentic_blackboard`), reached two ways: the HTTP side-channel and the agentic
+// channel serve the identical per-plan board with no drift surface.
+//
+// Board scope parity: the family derives each connection's board `scope` from its capability
+// credential — the per-plan blackboard token — resolved back to its `plan_key` via
+// `planKeyForTokenSync`, EXACTLY as the HTTP hook resolves `?token=` to a plan. So a channel client
+// and an HTTP caller holding the same plan token read/write the very same rows. An unknown/absent
+// credential yields no scope and the frame is rejected (advisory — never a hard-lock, never gates a
+// BPMN sequence flow).
+//
+// Adds NO migration of its own: H4's reserved `db/migrations/025_agentic_blackboard.sql` (owned by
+// the app-side adapter) creates `agentic_blackboard`; `store.ensureSchema()` here is the idempotent
+// belt-and-braces the store's own contract expects.
+import { attachBlackboardFamily, BlackboardStore } from "@nanobpm/agentic/blackboard";
+import type { HubConnection } from "@nanobpm/agentic/channel";
+import { planKeyForTokenSync } from "../../blackboard.ts";
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+
+/** The capability-credential a connection presents at the handshake (the blackboard token). */
+function credentialOf(conn: HubConnection): string {
+  return (conn.handshake.credential ?? conn.handshake.query?.capability ?? "").trim();
+}
+
+let handle: { stop(): void } | undefined;
+
+/**
+ * The `blackboard` family module. `mount` attaches the family to the hub when the app has a data
+ * layer; without one (data isn't mounted) it is a no-op — the channel simply serves no blackboard,
+ * exactly as the HTTP hook would 404. `teardown` detaches it.
+ */
+export const family: AgenticFamily = {
+  name: "blackboard",
+  mount(ctx: AgenticContext): void {
+    // Stop any previously-attached family before (re)mounting, so a repeat mount() (tests or a
+    // future remount path) can't leave stale handlers attached and double-handle frames / leak
+    // resources. Done unconditionally — before the data check — so even a no-data remount detaches
+    // the prior handle instead of silently leaving it live.
+    handle?.stop();
+    handle = undefined;
+    const data = ctx.data;
+    if (!data) {
+      ctx.log.warn("agentic blackboard family: no data layer; not mounting");
+      return;
+    }
+    const db = data.source().db;
+    const store = new BlackboardStore(db);
+    store.ensureSchema();
+    handle = attachBlackboardFamily(ctx.hub, store, {
+      // Scope every board to the plan the credential's token maps to — the same plan the HTTP hook
+      // scopes to — so the two paths share one board. Returning undefined rejects the frame.
+      scopeOf: (conn) => planKeyForTokenSync(db, credentialOf(conn)),
+      onError: (err, connectionId) =>
+        ctx.log.warn("agentic blackboard family error", { connectionId, err: String(err) }),
+    });
+    ctx.log.info("agentic blackboard family mounted");
+  },
+  teardown(): void {
+    handle?.stop();
+    handle = undefined;
+  },
+};
+
+export default family;

package/app/blackboard.schema.test.ts

@@ -0,0 +1,21 @@
+// Schema-drift guard (#147). The `db/migrations/025_agentic_blackboard.sql` CREATE statements MUST be
+// the canonical `BLACKBOARD_SCHEMA_SQL` verbatim — the exact DDL `@nanobpm/agentic/blackboard`'s
+// `BlackboardStore.ensureSchema()` (and the agentic-channel family) apply. If the two ever drift, a
+// board created by a migration on one host and by `ensureSchema()` on another would disagree — this
+// test fails the build before that can ship.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+import { BLACKBOARD_SCHEMA_SQL } from "@nanobpm/agentic/blackboard";
+import { assert, assertEquals } from "#test-assert";
+
+test("migration 025 CREATE statements equal BLACKBOARD_SCHEMA_SQL verbatim", () => {
+  const path = fileURLToPath(new URL("../db/migrations/025_agentic_blackboard.sql", import.meta.url));
+  const sql = readFileSync(path, "utf8");
+  const start = sql.indexOf("CREATE TABLE IF NOT EXISTS agentic_blackboard");
+  const end = sql.indexOf("(scope, id);");
+  assert(start !== -1, "migration 025 is missing the `CREATE TABLE IF NOT EXISTS agentic_blackboard` marker");
+  assert(end !== -1, "migration 025 is missing the `(scope, id);` index marker");
+  const createBlock = sql.slice(start, end + "(scope, id);".length).trim();
+  assertEquals(createBlock, BLACKBOARD_SCHEMA_SQL.trim());
+});