@nanobpm/nano-workforce 0.54.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/openapi.yaml

@@ -99,6 +99,79 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/ActivePr"
+    AgenticSupplyWorker:
+      type: object
+      description: One connected worker in the supply mirror (H5 cockpit; sourced from the H1 presence registry).
+      required:
+        - instance
+        - identity
+        - stream
+        - jobKeys
+        - live
+        - staleMs
+      properties:
+        instance:
+          type: string
+          description: The worker instance id.
+        identity:
+          type: string
+          description: The ADR 0028 leaf token the worker registered under.
+        stream:
+          type: string
+          description: The relay stream id to subscribe when drilling into this worker's terminal.
+        family:
+          type: string
+          description: Declared family (enrolment attribute), if any.
+        host:
+          type: string
+          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).
+          items:
+            type: string
+        live:
+          type: boolean
+          description: Whether the worker's channel connection is still open.
+        staleMs:
+          type: integer
+          description: Milliseconds since the last liveness refresh (0 when fresh).
+    AgenticSupplyLeaf:
+      type: object
+      description: The supply for one leaf token — the workers registered under it.
+      required:
+        - token
+        - workers
+      properties:
+        token:
+          type: string
+        workers:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgenticSupplyWorker"
+    AgenticSupplyReport:
+      type: object
+      description: The SUPPLY-ONLY visibility report — the live worker list grouped by leaf. No demand-side
+        fields (the demand×supply matrix / diversity SLO are deferred to enrolment epic #152).
+      required:
+        - count
+        - workers
+        - leaves
+      properties:
+        count:
+          type: integer
+          description: The number of connected workers.
+        generatedAt:
+          type: string
+          description: When this snapshot was taken, ISO-8601.
+        workers:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgenticSupplyWorker"
+        leaves:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgenticSupplyLeaf"
     VersionInfo:
       type: object
       description: The running app's identity (which code is actually live).
@@ -509,6 +582,27 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /agentic/supply:
+    get:
+      operationId: getAgenticSupply
+      summary: The SUPPLY-ONLY agentic visibility report — the live worker list (family, host, current jobs,
+        liveness) grouped by leaf, sourced from the H1 presence registry. Feeds the H5 cockpit page.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The supply report.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgenticSupplyReport"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /version:
     get:
       operationId: getVersion

package/operations/getAgenticSupply.test.ts

@@ -0,0 +1,153 @@
+// Tests for GET /app/api/agentic/supply → operation `getAgenticSupply` (H5 / #148).
+//
+// Covers: the empty report when no presence family is mounted; the shared-secret guard; and the
+// end-to-end mapping of a mounted presence registry's snapshot into the supply report (stream keyed
+// by instance, family/host/jobKeys/liveness) — driven through a REAL AgenticHub + in-memory transport
+// exactly as the presence family is exercised, so the singleton the operation reads is the live one.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { AgenticHub } from "@nanobpm/agentic/channel";
+import type { Authenticator, ChannelConnection, ChannelTransport } from "@nanobpm/agentic/channel";
+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 { family } from "../app/agentic/families/presence.family.ts";
+import type { AgenticContext } from "../app/agentic/registry.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./getAgenticSupply.ts";
+
+function memSqlite(): SqliteDb {
+  const db = new DatabaseSync(":memory:");
+  return {
+    exec: (sql) => db.exec(sql),
+    run: (sql, params = []) => {
+      const r = db.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: Number(r.lastInsertRowid) };
+    },
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      db.prepare(sql).all(...(params as never[])) as T[],
+  };
+}
+
+function memData(db: SqliteDb): DataLayer {
+  return { source: () => ({ db }) } as unknown as DataLayer;
+}
+
+function memTransport(): { transport: ChannelTransport; connect(conn: ChannelConnection): void } {
+  let onConnection: ((conn: ChannelConnection) => void) | undefined;
+  const transport: ChannelTransport = {
+    onConnection: (l) => {
+      onConnection = l;
+    },
+    address: { port: 0 },
+    close: async () => {},
+  };
+  return { transport, connect: (conn) => onConnection?.(conn) };
+}
+
+function fakeConn(id: string, identity: string): { conn: ChannelConnection; feed(frame: Frame): void } {
+  let onMessage: ((bytes: Uint8Array) => void) | undefined;
+  const conn: ChannelConnection = {
+    id,
+    handshake: { query: { identity }, token: "t", credential: "c" },
+    send: () => {},
+    close: () => {},
+    onMessage: (l) => {
+      onMessage = l;
+    },
+    onClose: () => {},
+  };
+  return { conn, feed: (frame) => onMessage?.(encodeFrame(frame)) };
+}
+
+const authenticator: Authenticator = (req) => ({ ok: true, grant: { identity: req.query?.identity ?? "anon" } });
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+
+async function mountPresence(db: SqliteDb): Promise<AgenticHub> {
+  const transport = memTransport();
+  const hub = new AgenticHub({ transport: transport.transport, authenticator, sweepIntervalMs: 0 });
+  const ctx: AgenticContext = {
+    hub,
+    registry: hub.registry,
+    transport: transport.transport as never,
+    data: memData(db),
+    log: noopLog(),
+  };
+  await family.mount(ctx);
+  // Register one live worker under leaf "leafA" with declared family + host.
+  const peer = fakeConn("c1", "leafA");
+  transport.connect(peer.conn);
+  await flush();
+  peer.feed({ lane: "control", family: "register", seq: 1, payload: { instance: "wk-a", capability: { family: "opus", host: "boxA" } } });
+  await flush();
+  return hub;
+}
+
+function input(headers: Record<string, string> = {}) {
+  return {
+    req: {
+      method: "GET",
+      path: "/app/api/agentic/supply",
+      query: new URLSearchParams(),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as never,
+    params: {},
+    query: {},
+    body: undefined,
+  };
+}
+
+const app = { log: noopLog() } as unknown as AppApi;
+
+test("returns an empty supply report when no presence family is mounted", async () => {
+  family.teardown?.();
+  const res = (await handler(input(), app)) as { status: number; body: { count: number; workers: unknown[]; leaves: unknown[] } };
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 0);
+  assertEquals(res.body.workers.length, 0);
+  assertEquals(res.body.leaves.length, 0);
+});
+
+test("maps the presence snapshot into the supply report (stream, family, host, liveness)", async () => {
+  const hub = await mountPresence(memSqlite());
+  try {
+    const res = (await handler(input(), app)) as {
+      status: number;
+      body: { count: number; workers: Array<Record<string, unknown>>; leaves: Array<{ token: string; workers: unknown[] }> };
+    };
+    assertEquals(res.status, 200);
+    assertEquals(res.body.count, 1);
+    const w = res.body.workers[0];
+    assertEquals(w.instance, "wk-a");
+    assertEquals(w.identity, "leafA");
+    assertEquals(w.stream, "wk-a", "the drill stream is keyed by the worker instance");
+    assertEquals(w.family, "opus");
+    assertEquals(w.host, "boxA");
+    assertEquals(w.live, true);
+    assertEquals(w.jobKeys, []);
+    assertEquals(res.body.leaves[0]?.token, "leafA");
+    assertEquals(res.body.leaves[0]?.workers.length, 1);
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("shared-secret guard rejects a missing secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./getAgenticSupply.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const bad = (await guarded(input(), app)) as { status: number };
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(input({ "x-hook-secret": "s3cr3t" }), app)) as { status: number; body: Record<string, unknown> };
+    assertEquals(ok.status, 200);
+    assert("count" in ok.body);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});