@nanobpm/nano-workforce 0.85.3 → 0.87.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.87.0](https://github.com/nanobpm/nano-workforce/compare/v0.86.0...v0.87.0) (2026-08-18)
+
+
+### Features
+
+* **agentic:** frictionless zero-config cockpit — LOCAL mode accepts a tokenless upgrade ([#283](https://github.com/nanobpm/nano-workforce/issues/283)) ([b23dfbb](https://github.com/nanobpm/nano-workforce/commit/b23dfbb018241e4719c6ea664f6428d094069aa6)), closes [#278](https://github.com/nanobpm/nano-workforce/issues/278) [#224](https://github.com/nanobpm/nano-workforce/issues/224) [#282](https://github.com/nanobpm/nano-workforce/issues/282)
+
+# [0.86.0](https://github.com/nanobpm/nano-workforce/compare/v0.85.3...v0.86.0) (2026-08-18)
+
+
+### Features
+
+* **agentic:** enrolment hub — crew vocab, capability→SERVE & demand×supply board ([#152](https://github.com/nanobpm/nano-workforce/issues/152)) ([#281](https://github.com/nanobpm/nano-workforce/issues/281)) ([baf74e7](https://github.com/nanobpm/nano-workforce/commit/baf74e736a53af55883a78dcf1f84cc1d6c140c7)), closes [#145](https://github.com/nanobpm/nano-workforce/issues/145) [red/#blue](https://github.com/nanobpm/nano-workforce/issues/blue) [#153](https://github.com/nanobpm/nano-workforce/issues/153) [#red](https://github.com/nanobpm/nano-workforce/issues/red) [#blue](https://github.com/nanobpm/nano-workforce/issues/blue) [#145](https://github.com/nanobpm/nano-workforce/issues/145) [#153](https://github.com/nanobpm/nano-workforce/issues/153) [#board-root](https://github.com/nanobpm/nano-workforce/issues/board-root)
+
 ## [0.85.3](https://github.com/nanobpm/nano-workforce/compare/v0.85.2...v0.85.3) (2026-08-18)
 
 

package/app/agentic/channel.test.ts

@@ -294,6 +294,77 @@ test("LOCAL mode still rejects a wrong token (4401)", async (t) => {
   assertEquals(channel.hub.connectionCount, 0);
 });
 
+// --- Frictionless zero-config: LOCAL mode accepts a TOKENLESS upgrade (#282) ---
+// The well-known LOCAL token is public, so requiring the client to echo it is pure friction: a
+// genuinely zero-config cockpit (no `?token=`) must attach on the trusted LAN. LOCAL mode therefore
+// treats a missing token as presenting the well-known token.
+
+test("LOCAL mode (secure:false): a TOKENLESS upgrade opens (zero-config, #282)", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log: noopLog(),
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  // No query at all — the browser cockpit's zero-config default (`defaultRelayUrl` sends no token).
+  const ws = await connect(port, "");
+  assertEquals(ws.readyState, WebSocket.OPEN);
+  assertEquals(channel.hub.connectionCount, 1);
+  ws.close();
+});
+
+test("SECURE mode still REJECTS a tokenless upgrade (4401) — substitution is LOCAL-only (#282)", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: SECRET,
+    secure: true,
+    data: undefined,
+    log: noopLog(),
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const closedCode = await rejectionCode(port, "");
+  assertEquals(closedCode, 4401);
+  assertEquals(channel.hub.connectionCount, 0);
+});
+
+test("LOCAL mode with a CUSTOM token still REJECTS a tokenless upgrade (no bypass, #282)", async (t) => {
+  const { server, port } = await startHttp();
+  // A caller opting into a non-default token in LOCAL mode (secure:false + a custom secret) is NOT
+  // the frictionless well-known-token posture — the tokenless substitution must NOT apply, so a
+  // client cannot bypass the custom token by omitting `?token=`.
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "custom-local-token",
+    secure: false,
+    data: undefined,
+    log: noopLog(),
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const closedCode = await rejectionCode(port, "");
+  assertEquals(closedCode, 4401);
+  assertEquals(channel.hub.connectionCount, 0);
+  // The custom token itself still upgrades.
+  const ws = await connect(port, "?token=custom-local-token");
+  assertEquals(ws.readyState, WebSocket.OPEN);
+  ws.close();
+});
+
 /** A capturing `Logger`: records every `(level, msg)` pair the sink receives. */
 function capturingLog(): { log: ReturnType<typeof noopLog>; records: Array<{ level: string; msg: string }> } {
   const records: Array<{ level: string; msg: string }> = [];

package/app/agentic/channel.ts

@@ -15,6 +15,7 @@
 // is untouched; advisory semantics preserved (a family never gates a BPMN sequence flow).
 import type { Server } from "node:http";
 import type { AddressInfo } from "node:net";
+import type { HandshakeRequest } from "@nanobpm/agentic/channel";
 import {
   AgenticHub,
   sharedSecretAuthenticator,
@@ -133,7 +134,22 @@ export async function mountAgenticChannel(
   // credential is intentionally NOT required — nano-workforce never verified it (accept-any), so it
   // was pure configuration friction; a real ADR 0028 capability check can reintroduce it later by
   // passing a verifier.
-  const authenticator = sharedSecretAuthenticator({ secret, requireCredential: false });
+  const baseAuthenticator = sharedSecretAuthenticator({ secret, requireCredential: false });
+  // LOCAL mode is frictionless-first (#282): the well-known token is PUBLIC, so requiring a client to
+  // echo it adds no security — only friction. A genuinely zero-config cockpit (`defaultRelayUrl`
+  // sends no `?token=`) must attach on the trusted LAN, so a TOKENLESS upgrade is treated as
+  // presenting the well-known token. This substitution is scoped to the DEFAULT LOCAL posture only
+  // (`secret === LOCAL_AGENTIC_TOKEN`): a caller that opts into a CUSTOM token in LOCAL mode
+  // (`secure:false` + a non-default `secret`) still requires that token — a tokenless client can't
+  // bypass it. SECURE mode is likewise unaffected: it keeps demanding the real secret, so a tokenless
+  // (or wrong) upgrade is still rejected (4401).
+  const substituteWellKnownToken = !secure && secret === LOCAL_AGENTIC_TOKEN;
+  const authenticator = substituteWellKnownToken
+    ? (req: HandshakeRequest) =>
+        req.token === undefined && req.query?.token === undefined
+          ? baseAuthenticator({ ...req, token: secret })
+          : baseAuthenticator(req)
+    : baseAuthenticator;
   const hub = new AgenticHub({
     transport,
     // A valid identity token upgrades (4401 on mismatch). SECURE mode's token is the real secret;

package/app/agentic/vocab/README.md

@@ -0,0 +1,37 @@
+# `app/agentic/vocab/` — the enrolment hub (epic #152 / N1 #145)
+
+The app-tier **enrolment / token-resolution** side of the agentic plane (ADR 0059 revised + ADR 0056
+§8–10). It **consumes** `@nanobpm/agentic` (`/vocab`, `/demand`, `/protocol`) — it never
+re-implements the wire types (AGENTS.md: derivation over duplication).
+
+## What N1 lands
+
+- **`crew-vocab.ts`** — `CREW_VOCAB`, the nwf crew vocabulary artifact (the ONE capability→token map),
+  authored in the package's `VocabDocument` schema, plus the memoised `crewResolver()`. Tokens:
+  `planning.spar` (#red/#blue, strict distinct-family), `planning.finalize`, `qa.review`/`qa.lint`,
+  `implementation.senior`/`.junior`/`.reviewer`, `ci.runner`, `decide`.
+- **`enrol.ts`** — `resolveEnrolment(capability)`: the server side of REGISTER → SERVE. A declared
+  enrolment capability resolves to a deterministic SERVE token set, the vocab version, and the
+  liveness lease TTL. Idempotent per (app, worker) — the same capability always yields the same SERVE.
+- **`publish.ts`** — the `GET /agentic/vocab` view (`{ networks, requirements, version }`).
+- **`demand-report.ts`** — the demand×supply report behind `GET /agentic/registry`: deployed DEMAND
+  (the models' `taskDefinition` leaves, read from the engine's C8 v2 REST API) diffed against live
+  SUPPLY (the H1 presence registry resolved through the crew vocab), per network, with the
+  **missing-agent-type** reds and the **diversity SLO** (ADR 0056 §10). Degrades to a supply-only
+  report (`demandUnavailable: true`) when the engine can't be read.
+
+## Endpoints (mounted under `/app/api`, ADR 0058/0059)
+
+- `GET  /app/api/agentic/vocab`    → `getAgenticVocab`    — the published crew vocab artifact.
+- `POST /app/api/agentic/enrol`    → `enrolAgenticWorker` — `{ capability, host }` → `{ serve, demandVersion, leaseTtl }`.
+- `GET  /app/api/agentic/registry` → `getAgenticRegistry` — the demand×supply report.
+
+The **N2 board** (`pages/board/`, App View — ADR 0057) renders the report: the matrix by network,
+missing-agent-type reds, and the diversity-SLO lights.
+
+## Invariants (ADR 0056)
+
+App-tier only, never the engine; the C8 REST read is an ordinary read over a **separate** connection
+(the engine and the C8 job protocol stay frozen). **Advisory** — the report is a read-only mirror and
+never hard-locks or gates a BPMN sequence flow; there is no server-side matchmaking/placement.
+Capability (cognition/weight/family/host) is an **enrolment** attribute, never a routing token.

package/app/agentic/vocab/crew-vocab.test.ts

@@ -0,0 +1,86 @@
+// Tests for the crew vocabulary artifact (epic #152 / N1 #145). Assert the artifact is a valid vocab
+// document, ships the crew's leaf tokens, resolves a declared capability to its SERVE set, and grades
+// the diversity SLO — the ADR 0056 §10 red/blue spar acceptance.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { correlateRegistry } from "@nanobpm/agentic/vocab";
+import type { Capability } from "@nanobpm/agentic/protocol";
+import { CREW_VOCAB, CREW_VOCAB_VERSION, crewResolver } from "./crew-vocab.ts";
+
+const frontierPlanner: Capability = { cognition: "planning", weight: 5, family: "frontier", host: "h1" };
+const kimiPlanner: Capability = { cognition: "planning", weight: 5, family: "kimi", host: "h2" };
+
+test("the crew vocab is a valid artifact the resolver accepts", () => {
+  const resolver = crewResolver();
+  assertEquals(resolver.version, CREW_VOCAB_VERSION);
+  // Same singleton is memoised.
+  assert(crewResolver() === resolver);
+});
+
+test("it ships the crew's leaf tokens", () => {
+  const tokens = crewResolver().tokens();
+  for (const expected of [
+    "planning.spar",
+    "planning.finalize",
+    "qa.review",
+    "qa.lint",
+    "implementation.senior",
+    "implementation.junior",
+    "implementation.reviewer",
+    "ci.runner",
+    "decide",
+  ]) {
+    assert(tokens.includes(expected), `expected token ${expected}`);
+  }
+});
+
+test("the spar role carries two distinct-family named seats", () => {
+  const spar = crewResolver().roleForToken("planning.spar");
+  assert(spar !== undefined);
+  assertEquals(spar.seats, ["red", "blue"]);
+  assertEquals(spar.seatsDistinctFamily, true);
+});
+
+test("a frontier and a kimi/qwen planning worker both resolve planning.spar", () => {
+  const frontier = crewResolver().resolve(frontierPlanner);
+  const kimi = crewResolver().resolve(kimiPlanner);
+  assert(frontier.tokens.includes("planning.spar"), "frontier serves planning.spar");
+  assert(kimi.tokens.includes("planning.spar"), "kimi serves planning.spar");
+  // Deterministic / idempotent: the same capability always yields the same SERVE.
+  assertEquals(crewResolver().resolve(frontierPlanner).tokens, frontier.tokens);
+});
+
+test("a capability that satisfies no requires gate resolves to an empty SERVE set", () => {
+  const stranger: Capability = { cognition: "marketing", family: "frontier" };
+  assertEquals(crewResolver().resolve(stranger).tokens, []);
+});
+
+test("diversity SLO is green for distinct-family spar seats, red for a same-family collision", () => {
+  const resolver = crewResolver();
+  const distinct = correlateRegistry(resolver, [
+    { instance: "a", capability: frontierPlanner },
+    { instance: "b", capability: kimiPlanner },
+  ]);
+  assertEquals(distinct.status, "green");
+
+  const sameFamily = correlateRegistry(resolver, [
+    { instance: "a", capability: frontierPlanner },
+    { instance: "b", capability: { ...kimiPlanner, family: "frontier" } },
+  ]);
+  const spar = sameFamily.roles.find((r) => r.token === "planning.spar");
+  assert(spar !== undefined);
+  // A same-family collision on the STRICT (seatsDistinctFamily) spar role is an SLO violation (RED).
+  assertEquals(spar.status, "red");
+  assertEquals(sameFamily.status, "red");
+});
+
+test("CREW_VOCAB is deep-frozen so a consumer cannot mutate the shared artifact", () => {
+  assert(Object.isFrozen(CREW_VOCAB));
+  // Object.freeze is shallow — assert the nested structures are frozen too, so the "no consumer can
+  // mutate the shared artifact" invariant holds all the way down.
+  assert(Object.isFrozen(CREW_VOCAB.networks));
+  assert(Object.isFrozen(CREW_VOCAB.networks.planning));
+  assert(Object.isFrozen(CREW_VOCAB.networks.planning.roles));
+  assert(Object.isFrozen(CREW_VOCAB.networks.planning.roles.spar));
+  assert(Object.isFrozen(CREW_VOCAB.networks.planning.roles.spar.seats));
+});

package/app/agentic/vocab/crew-vocab.ts

@@ -0,0 +1,147 @@
+// nano-workforce — the crew vocabulary artifact (enrolment epic #152 / N1 #145, ADR 0059 revised +
+// ADR 0056 §8–9).
+//
+// This is nwf's app-tier CORE vocabulary: the ONE authoritative capability→token map the app applies
+// over the agentic channel (REGISTER → SERVE) and publishes at `GET /agentic/vocab`. It is authored
+// in the SAME schema `@nanobpm/agentic/vocab` validates (`VocabDocument`) — we CONSUME the resolver,
+// merge, diversity and demand machinery; we never re-implement the wire types (AGENTS.md: derivation
+// over duplication).
+//
+// The crew (the agentic-SDLC networks nwf drives):
+//   - planning.spar   — the red/blue planning spar. Two named seats (#red / #blue), STRICT
+//                       distinct-family: the diversity SLO is RED if both spar seats are one family
+//                       (ADR 0056 §10). A frontier planner and a kimi/qwen planner seat #red vs #blue.
+//   - planning.finalize — the single planner who folds the spar into one plan.
+//   - qa.review       — the red/blue QA review (STRICT distinct-family, two seats).
+//   - qa.lint         — the single lint pass.
+//   - implementation.senior / .junior / .reviewer — the build crew (reviewer is red/blue).
+//   - ci.runner       — the CI runner.
+//   - decide          — the bare decision role.
+//
+// Capability (cognition / weight / family / host) is an ENROLMENT attribute, never a routing token
+// (ADR 0056 invariant 3): each role's `requires` gate — not the token — decides WHO may fill it.
+
+import type { VocabDocument } from "@nanobpm/agentic/protocol";
+import { CORE_VOCAB_VERSION, VocabResolver } from "@nanobpm/agentic/vocab";
+
+/**
+ * The crew vocabulary version. Bumped when the artifact's shape changes so a worker (and the
+ * demand×supply report's `demandVersion`) can detect a vocab it doesn't recognise. Seeded from the
+ * package's core-vocab version so the two move together.
+ */
+export const CREW_VOCAB_VERSION = CORE_VOCAB_VERSION;
+
+/**
+ * Recursively freezes an object graph. `Object.freeze()` is shallow, so a plain freeze on the vocab
+ * artifact still leaves nested `networks` / `roles` / `seats` structures mutable — contradicting the
+ * "no consumer can mutate the shared artifact" invariant. Deep-freezing every nested object and array
+ * makes the whole document genuinely immutable.
+ */
+function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const nested of Object.values(value)) {
+      deepFreeze(nested);
+    }
+  }
+  return value;
+}
+
+/**
+ * The nwf crew vocabulary document. Authored in the `@nanobpm/agentic` `VocabDocument` schema so the
+ * package resolver/merge/diversity all apply unchanged. Deep-frozen so no consumer can mutate the
+ * shared artifact — including its nested `networks` / `roles` / `seats` structures (a shallow
+ * `Object.freeze` would leave those mutable). Authors extend it with `mergeVocab`, which returns a
+ * fresh document.
+ */
+export const CREW_VOCAB: VocabDocument = deepFreeze({
+  version: CREW_VOCAB_VERSION,
+  networks: {
+    planning: {
+      roles: {
+        // The red/blue planning spar: two adversarial planners of DISTINCT families (frontier vs
+        // kimi/qwen). Strict distinct-family so a single-family spar is an SLO violation (RED).
+        spar: {
+          requires: ["cognition=planning"],
+          weight: 5,
+          seats: ["red", "blue"],
+          seatsDistinctFamily: true,
+        },
+        // Folds the spar into one plan — a single senior planner seat.
+        finalize: {
+          requires: ["cognition=planning", "weight>=4"],
+          weight: 5,
+          seats: 1,
+        },
+      },
+    },
+    qa: {
+      roles: {
+        // The red/blue QA review — two seats, strict distinct-family (same rationale as the spar).
+        review: {
+          requires: ["cognition=qa"],
+          weight: 3,
+          seats: ["red", "blue"],
+          seatsDistinctFamily: true,
+        },
+        // The single lint pass.
+        lint: {
+          requires: ["cognition=qa"],
+          weight: 2,
+          seats: 1,
+        },
+      },
+    },
+    implementation: {
+      roles: {
+        senior: {
+          requires: ["cognition=implementation", "weight>=4"],
+          weight: 5,
+          seats: 1,
+        },
+        junior: {
+          requires: ["cognition=implementation"],
+          weight: 2,
+          seats: 3,
+        },
+        // The red/blue implementation review.
+        reviewer: {
+          requires: ["cognition=implementation"],
+          weight: 4,
+          seats: ["red", "blue"],
+          seatsDistinctFamily: true,
+        },
+      },
+    },
+    ci: {
+      roles: {
+        runner: {
+          requires: ["cognition=ci"],
+          weight: 1,
+          seats: 1,
+        },
+      },
+    },
+    // A bare role (no network segment): its token is just `decide`.
+    decide: {
+      roles: {
+        decide: {
+          requires: ["cognition=decide"],
+          weight: 5,
+          seats: 1,
+        },
+      },
+    },
+  },
+});
+
+// One shared resolver over the frozen artifact. The document is re-validated (and every `requires`
+// gate parsed) at construction, so a malformed crew vocab fails loudly the first time it is read —
+// not silently at match time. Built lazily and memoised so the validation cost is paid once.
+let resolver: VocabResolver | undefined;
+
+/** The shared crew {@link VocabResolver} — resolve a declared capability to its SERVE token set. */
+export function crewResolver(): VocabResolver {
+  if (!resolver) resolver = new VocabResolver(CREW_VOCAB);
+  return resolver;
+}

package/app/agentic/vocab/demand-report.test.ts

@@ -0,0 +1,97 @@
+// Tests for the demand×supply report (epic #152 / N1 #145). The report is a pure fold over injected
+// demand (deployed taskDefinition leaves) + supply (registry rows) resolved through the crew vocab,
+// so it needs no live engine or presence store here.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { TaskDefinitionLeaf } from "@nanobpm/agentic/demand";
+import type { RegisteredWorker } from "@nanobpm/agentic/vocab";
+import { CREW_VOCAB_VERSION } from "./crew-vocab.ts";
+import { buildRegistryReport, engineRestAddress, toWireReport } from "./demand-report.ts";
+
+const NOW = new Date(0);
+const leaf = (taskType: string): TaskDefinitionLeaf => ({ taskType, process: "p", elementId: taskType });
+
+const plannerFrontier: RegisteredWorker = { instance: "w-front", capability: { cognition: "planning", weight: 5, family: "frontier" } };
+const plannerKimi: RegisteredWorker = { instance: "w-kimi", capability: { cognition: "planning", weight: 5, family: "kimi" } };
+
+test("flags a demanded leaf with no supplier as missing (red) and a supplied leaf as satisfied", () => {
+  const report = buildRegistryReport({
+    taskDefinitions: [leaf("planning.spar"), leaf("ci.runner")],
+    workers: [plannerFrontier],
+    now: NOW,
+  });
+  assert(report.missing.includes("ci.runner"), "ci.runner has no supplier");
+  assertEquals(report.status, "red");
+  const planning = report.networks.find((n) => n.network === "planning");
+  assert(planning !== undefined);
+  const spar = planning.tokens.find((t) => t.token === "planning.spar");
+  assert(spar !== undefined);
+  assertEquals(spar.satisfied, true);
+  assertEquals(spar.supply, 1);
+  assertEquals(spar.instances, ["w-front"]);
+  assertEquals(report.version, CREW_VOCAB_VERSION);
+  assertEquals(report.generatedAt, NOW.toISOString());
+  assertEquals(report.demandUnavailable, false);
+});
+
+test("a deployed type that is not a valid routing token is surfaced as nonAgentic, not missing", () => {
+  const report = buildRegistryReport({ taskDefinitions: [leaf("weird token!")], workers: [], now: NOW });
+  assert(report.nonAgentic.includes("weird token!"));
+  assertEquals(report.missing, []);
+});
+
+test("the diversity SLO reads the correlated supply — green for distinct-family spar seats", () => {
+  const report = buildRegistryReport({
+    taskDefinitions: [leaf("planning.spar")],
+    workers: [plannerFrontier, plannerKimi],
+    now: NOW,
+  });
+  assertEquals(report.diversity.status, "green");
+});
+
+test("when the engine demand read is unavailable the report is supply-only, flagged demandUnavailable", () => {
+  const report = buildRegistryReport({ taskDefinitions: undefined, workers: [plannerFrontier], now: NOW });
+  assertEquals(report.demandUnavailable, true);
+  assertEquals(report.networks, []);
+  assertEquals(report.missing, []);
+});
+
+test("toWireReport rebuilds the report into the mutable wire shape structurally", () => {
+  const report = buildRegistryReport({ taskDefinitions: [leaf("planning.spar")], workers: [plannerFrontier], now: NOW });
+  const wire = toWireReport(report);
+  assertEquals(wire.version, report.version);
+  assertEquals(wire.status, report.status);
+  assertEquals(wire.networks[0].tokens[0].token, "planning.spar");
+  assert(Array.isArray(wire.missing));
+});
+
+test("engineRestAddress derives a /v2 REST base by default", () => {
+  const address = engineRestAddress();
+  assert(address.startsWith("http"), "an http(s) base");
+});
+
+test("engineRestAddress strips trailing slashes from an explicit CAMUNDA_REST_ADDRESS", () => {
+  const prev = process.env.CAMUNDA_REST_ADDRESS;
+  try {
+    process.env.CAMUNDA_REST_ADDRESS = "http://engine.example:8080/v2///";
+    assertEquals(engineRestAddress(), "http://engine.example:8080/v2");
+  } finally {
+    if (prev === undefined) delete process.env.CAMUNDA_REST_ADDRESS;
+    else process.env.CAMUNDA_REST_ADDRESS = prev;
+  }
+});
+
+test("engineRestAddress strips trailing slashes from the derived NANOBPMN_BASE_URL base", () => {
+  const prevExplicit = process.env.CAMUNDA_REST_ADDRESS;
+  const prevBase = process.env.NANOBPMN_BASE_URL;
+  try {
+    delete process.env.CAMUNDA_REST_ADDRESS;
+    process.env.NANOBPMN_BASE_URL = "http://engine.example:8080//";
+    assertEquals(engineRestAddress(), "http://engine.example:8080/v2");
+  } finally {
+    if (prevExplicit === undefined) delete process.env.CAMUNDA_REST_ADDRESS;
+    else process.env.CAMUNDA_REST_ADDRESS = prevExplicit;
+    if (prevBase === undefined) delete process.env.NANOBPMN_BASE_URL;
+    else process.env.NANOBPMN_BASE_URL = prevBase;
+  }
+});

package/app/agentic/vocab/demand-report.ts

@@ -0,0 +1,155 @@
+// nano-workforce — the demand×supply report (epic #152 / N1 #145, ADR 0056 §8–10, ADR 0059 revised).
+//
+// The read-only mirror behind `GET /agentic/registry`. It diffs DEMAND — the routing tokens the
+// deployed BPMN models ask for (`zeebe:taskDefinition` leaves, read from the engine's C8 v2 REST API
+// via `@nanobpm/agentic/demand`) — against SUPPLY — the live workers on the H1 presence registry
+// (#144), resolved through the crew vocab — to surface, per network: the demand×supply rows, the
+// MISSING agent types (demanded leaf with no supplier → RED), and the diversity SLO over the
+// correlated registry (ADR 0056 §10).
+//
+// Invariants (ADR 0056): app-tier only, advisory, NEVER a matchmaker — it reports what is demanded /
+// supplied / missing and never places work or holds a seat's job. The C8 REST read is an ordinary
+// read over a SEPARATE connection; the engine and the C8 job protocol stay frozen.
+import {
+  computeDemandSupply,
+  type DemandSupplyReport,
+  httpC8RestReader,
+  readDeployedTaskDefinitions,
+  type TaskDefinitionLeaf,
+} from "@nanobpm/agentic/demand";
+import type { RegisteredWorker } from "@nanobpm/agentic/vocab";
+import type { Logger } from "@nanobpm/urban";
+import type { RegistryReport as WireRegistryReport } from "../../../nano-generated/api-io.d.ts";
+import { envVar } from "../../version.ts";
+import { currentPresenceRegistry } from "../families/presence.family.ts";
+import { CREW_VOCAB_VERSION, crewResolver } from "./crew-vocab.ts";
+
+/** The full registry report: the package's demand×supply model plus this app's version/provenance. */
+export interface RegistryReport extends DemandSupplyReport {
+  /** The crew-vocab version the report was resolved against. */
+  readonly version: number;
+  /** When the report was computed, ISO-8601. */
+  readonly generatedAt: string;
+  /**
+   * True when the demand side (deployed task definitions) could NOT be read from the engine, so the
+   * report reflects supply only (empty demand). Surfaced — not hidden — so the board can flag that
+   * demand is unavailable rather than silently showing "no demand".
+   */
+  readonly demandUnavailable: boolean;
+}
+
+/**
+ * Derive the engine's C8 v2 REST base the demand reader targets — the same precedence/derivation
+ * `main.ts` uses: an explicit `CAMUNDA_REST_ADDRESS` wins, else it is derived from `NANOBPMN_BASE_URL`
+ * (+ `/v2`), defaulting to `http://localhost:8080/v2`. Read through the declared env schema (ADR 0004).
+ * (This reader additionally strips trailing slashes off an explicit `CAMUNDA_REST_ADDRESS`, which
+ * `main.ts` does not, so the derived base is well-formed regardless of a trailing `/`.)
+ */
+export function engineRestAddress(): string {
+  const explicit = envVar("CAMUNDA_REST_ADDRESS")?.replace(/\/+$/, "");
+  if (explicit) return explicit;
+  const base = (envVar("NANOBPMN_BASE_URL") ?? "http://localhost:8080").replace(/\/+$/, "");
+  return `${base}/v2`;
+}
+
+/** The live supply rows (`{ instance, capability }`) from the H1 presence registry, or none when unmounted. */
+export function supplyWorkers(): RegisteredWorker[] {
+  return currentPresenceRegistry()?.registeredWorkers() ?? [];
+}
+
+/**
+ * Read the deployed demand corpus (the models' `taskDefinition` leaves) from the engine over the C8
+ * REST API. Returns `undefined` when the read fails so the caller can degrade to a supply-only
+ * report rather than surface a hard error — the report is advisory and must never gate control flow.
+ */
+export async function readDemand(log?: Logger): Promise<TaskDefinitionLeaf[] | undefined> {
+  try {
+    const reader = httpC8RestReader({ restAddress: engineRestAddress(), token: envVar("CAMUNDA_TOKEN") ?? undefined });
+    return await readDeployedTaskDefinitions(reader);
+  } catch (err) {
+    log?.warn("agentic registry: engine demand read failed — reporting supply only", { err: String(err) });
+    return undefined;
+  }
+}
+
+/** Inputs for {@link buildRegistryReport} (injectable so tests need no live engine or presence store). */
+export interface BuildRegistryInput {
+  /** The deployed demand leaves, or `undefined` when the engine read failed (supply-only report). */
+  readonly taskDefinitions: readonly TaskDefinitionLeaf[] | undefined;
+  /** The live supply rows. */
+  readonly workers: readonly RegisteredWorker[];
+  /** "Now" for `generatedAt`. Defaults to a fresh timestamp. */
+  readonly now?: Date;
+}
+
+/**
+ * Compute the registry report from demand + supply. Pure and deterministic (every list the package
+ * emits is sorted), so it is safe to render straight into the board and diff frame-to-frame.
+ */
+export function buildRegistryReport(input: BuildRegistryInput): RegistryReport {
+  const demandUnavailable = input.taskDefinitions === undefined;
+  const report = computeDemandSupply({
+    taskDefinitions: input.taskDefinitions ?? [],
+    workers: input.workers,
+    resolver: crewResolver(),
+  });
+  return {
+    ...report,
+    version: CREW_VOCAB_VERSION,
+    generatedAt: (input.now ?? new Date()).toISOString(),
+    demandUnavailable,
+  };
+}
+
+/**
+ * Project the (deeply-readonly) package report onto the mutable wire shape the OpenAPI response type
+ * expects. A structural rebuild — never a cast — so a drift between the package model and the wire
+ * schema is caught by the compiler here rather than silently coerced.
+ */
+export function toWireReport(report: RegistryReport): WireRegistryReport {
+  return {
+    version: report.version,
+    generatedAt: report.generatedAt,
+    demandUnavailable: report.demandUnavailable,
+    networks: report.networks.map((network) => ({
+      network: network.network,
+      tokens: network.tokens.map((token) => ({
+        token: token.token,
+        supply: token.supply,
+        instances: [...token.instances],
+        satisfied: token.satisfied,
+      })),
+      missing: [...network.missing],
+    })),
+    missing: [...report.missing],
+    nonAgentic: [...report.nonAgentic],
+    diversity: {
+      status: report.diversity.status,
+      roles: report.diversity.roles.map((role) => ({
+        token: role.token,
+        seatsDistinctFamily: role.seatsDistinctFamily,
+        assignments: role.assignments.map((seat) => {
+          const out: WireRegistryReport["diversity"]["roles"][number]["assignments"][number] = {
+            seat: seat.seat,
+            family: seat.family,
+          };
+          if (seat.instance !== undefined) out.instance = seat.instance;
+          return out;
+        }),
+        collidingFamilies: [...role.collidingFamilies],
+        status: role.status,
+      })),
+    },
+    status: report.status,
+  };
+}
+
+/**
+ * The composition path the `getAgenticRegistry` operation calls: read demand from the engine, read
+ * supply from the presence registry, and build the report. Never throws for an engine outage — it
+ * degrades to a supply-only report.
+ */
+export async function computeRegistryReport(log?: Logger): Promise<RegistryReport> {
+  const taskDefinitions = await readDemand(log);
+  return buildRegistryReport({ taskDefinitions, workers: supplyWorkers() });
+}