@nanobpm/nano-workforce 0.50.0 → 0.51.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.51.0](https://github.com/nanobpm/nano-workforce/compare/v0.50.0...v0.51.0) (2026-08-13)
+
+
+### Features
+
+* mount agentic channel hub + family-registration seam (H0) ([#154](https://github.com/nanobpm/nano-workforce/issues/154)) ([96a679e](https://github.com/nanobpm/nano-workforce/commit/96a679e0843c76bf93940f09eef1c6c642a4ebed)), closes [#142](https://github.com/nanobpm/nano-workforce/issues/142) [#143](https://github.com/nanobpm/nano-workforce/issues/143) [#isMounted](https://github.com/nanobpm/nano-workforce/issues/isMounted)
+
 # [0.50.0](https://github.com/nanobpm/nano-workforce/compare/v0.49.0...v0.50.0) (2026-08-12)
 
 

package/app/agentic/README.md

@@ -0,0 +1,57 @@
+# `app/agentic/` — the app-tier agentic channel (ADR 0056)
+
+This directory hosts the **agentic visibility plane** for nano-workforce (epic #142). H0 (#143)
+owns the keystone wiring; siblings H1/H3/H4 extend it **without touching the boot script**.
+
+## What H0 lands
+
+- **`channel.ts`** — `mountAgenticChannel(...)`. Stands up the `@nanobpm/agentic` WebSocket channel
+  + `AgenticHub` on the app's **own** HTTP server (`app.httpServer`, same port as the pages and
+  `/app/api/hooks/*` — no sidecar port), authenticates upgrades on `/agentic` (ADR 0028 identity
+  token + a required capability credential, mirroring the blackboard hook's `?token=…` pattern), and
+  mounts every discovered family. Returns a handle whose `teardown()` reverses everything.
+- **`registry.ts`** — the `AgenticFamilyRegistry` seam + the `AgenticFamily` / `AgenticContext`
+  contracts. Mounts families on boot, tears them down in **reverse** order on shutdown.
+- **`loader.ts`** — auto-discovers `*.family.ts` modules under `families/`. There is **no central
+  registration list** to append to, so siblings never collide on a shared file.
+- **`families/`** — the discovery directory. Drop a family module here; `families/example.family.ts`
+  is the copyable no-op template.
+
+`main.ts` calls `mountAgenticChannel(...)` once after `runFromEnv`, and its `teardown()` once inside
+the existing `drainAndExit`. **That is the only edit to `main.ts` / `drainAndExit` for the whole
+epic.**
+
+## How a sibling slice extends the channel (H1 / H3 / H4)
+
+1. Copy `families/example.family.ts` to `families/<slice>.family.ts` and implement `mount(ctx)`
+   (and optionally `teardown()`). `ctx` carries the reusable handles: `hub`, `registry`,
+   `transport`, `data` (the app SQLite `DataLayer`), and `log`.
+2. Own a message family via `ctx.hub.registerFamilyHandler("<family>", handler)` — the router
+   refuses a duplicate, so two slices can't both claim one family.
+3. **Do not** edit `main.ts`, `drainAndExit`, `channel.ts`, `registry.ts`, or `loader.ts`. You add
+   exactly one new file.
+
+## Reserved migration prefixes
+
+Forward-only, additive (expand-only). The highest committed prefix when the epic began is `022`, so
+H0 pre-allocates distinct prefixes to stop two siblings independently grabbing "the next" number:
+
+| Slice            | Reserved migration file                     |
+| ---------------- | ------------------------------------------- |
+| H1 presence #144 | `db/migrations/023_agentic_presence.sql`    |
+| H3 transcript #146 | `db/migrations/024_agentic_transcript.sql` |
+| H4 blackboard #147 | `db/migrations/025_agentic_blackboard.sql` (only if a schema change is needed) |
+
+H0 itself needs no migration.
+
+## Configuration
+
+- `NANO_AGENTIC_SECRET` (falls back to `NANO_PR_WEBHOOK_SECRET`) — the shared identity secret peers
+  present as `?token=…`. When neither is set, the channel is **not mounted** (logged), so the app
+  never exposes an unauthenticated upgrade.
+
+## Invariants (ADR 0056)
+
+- **App-tier only** — never the engine. The Camunda-8 job protocol (worker⇄engine) is untouched;
+  the agentic channel is the only new conversation.
+- **Advisory** — a family never hard-locks or gates a BPMN sequence flow.

package/app/agentic/channel.test.ts

@@ -0,0 +1,244 @@
+// Integration tests for the agentic channel mount (ADR 0056, H0 / #143).
+//
+// Exercises the acceptance surface against a locally-constructed `node:http` server: a valid WS
+// client upgrades on `/agentic`, an invalid one is rejected, normal HTTP routes keep working, the
+// hub is visible via `inspect()`, families mount/tear-down through the seam, and shutdown is clean.
+import { type AddressInfo, createServer, type Server } from "node:http";
+import { test } from "node:test";
+import { WebSocket } from "ws";
+import { assert, assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import { type AgenticChannelHandle, mountAgenticChannel } from "./channel.ts";
+import { type AgenticContext, AgenticFamilyRegistry } from "./registry.ts";
+
+const SECRET = "test-agentic-secret";
+
+/** Start a bare HTTP server with one health route, on an ephemeral port. */
+async function startHttp(): Promise<{ server: Server; port: number }> {
+  const server = createServer((req, res) => {
+    if (req.url === "/health") {
+      res.writeHead(200, { "content-type": "text/plain" });
+      res.end("ok");
+      return;
+    }
+    res.writeHead(404);
+    res.end();
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const port = (server.address() as AddressInfo).port;
+  return { server, port };
+}
+
+/** Close an HTTP server and resolve only once it has stopped listening (server.close() is async). */
+function closeServer(server: Server): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    server.close((err) => (err ? reject(err) : resolve()));
+  });
+}
+
+/** Open a ws client and resolve on open. Rejects (with the close code) if it closes before opening. */
+function connect(port: number, query: string): Promise<WebSocket> {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}/agentic${query}`);
+  return new Promise<WebSocket>((resolve, reject) => {
+    let opened = false;
+    ws.on("open", () => {
+      opened = true;
+      resolve(ws);
+    });
+    ws.on("error", () => {
+      /* the close frame carries the reason; swallow the paired error event */
+    });
+    ws.on("close", (code, reason) => {
+      if (!opened) reject(new Error(`closed ${code}: ${reason.toString()}`));
+    });
+  });
+}
+
+/**
+ * The application close code an authenticator rejection delivers. The hub authenticates AFTER the
+ * WebSocket upgrade completes, so a rejected peer momentarily opens and is then closed with the app
+ * code (4401/4403) — this waits for that close and returns the code.
+ */
+/** How long rejectionCode waits for the close frame before failing (generous for slow CI). */
+const REJECTION_TIMEOUT_MS = 2000;
+
+function rejectionCode(port: number, query: string): Promise<number> {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}/agentic${query}`);
+  return new Promise<number>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error("connection neither closed nor timed out")),
+      REJECTION_TIMEOUT_MS,
+    );
+    timer.unref?.();
+    ws.on("error", () => {
+      /* swallow the paired error event; the close frame carries the code */
+    });
+    ws.on("close", (code) => {
+      clearTimeout(timer);
+      resolve(code);
+    });
+  });
+}
+
+async function mount(
+  _port: number,
+  server: Server,
+  families?: () => AgenticFamilyRegistry,
+): Promise<AgenticChannelHandle> {
+  return mountAgenticChannel({
+    server,
+    secret: SECRET,
+    data: undefined,
+    log: noopLog(),
+    families,
+  });
+}
+
+test("a valid identity token + capability credential upgrades on /agentic", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mount(port, server);
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const ws = await connect(port, `?token=${SECRET}&capability=cap-1`);
+  assertEquals(ws.readyState, WebSocket.OPEN);
+  // The hub tracked exactly this one connection.
+  assertEquals(channel.hub.connectionCount, 1);
+  ws.close();
+});
+
+test("an invalid identity token is rejected (4401)", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mount(port, server);
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const closedCode = await rejectionCode(port, "?token=wrong&capability=cap-1");
+  assertEquals(closedCode, 4401);
+  assertEquals(channel.hub.connectionCount, 0);
+});
+
+test("a missing capability credential is rejected (4403)", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mount(port, server);
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const closedCode = await rejectionCode(port, `?token=${SECRET}`);
+  assertEquals(closedCode, 4403);
+});
+
+test("normal HTTP routes keep working alongside the channel", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mount(port, server);
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const res = await fetch(`http://127.0.0.1:${port}/health`);
+  assertEquals(res.status, 200);
+  assertEquals(await res.text(), "ok");
+});
+
+test("the hub is visible via inspect() and mounts registered families", async (t) => {
+  const { server, port } = await startHttp();
+  const trace: string[] = [];
+  const families = () => {
+    const reg = new AgenticFamilyRegistry();
+    reg.register({
+      name: "probe",
+      mount(ctx: AgenticContext) {
+        trace.push("mount");
+        // Prove the real hub handle is threaded through: registering a family handler must work.
+        ctx.hub.registerFamilyHandler("register", () => {});
+      },
+      teardown() {
+        trace.push("teardown");
+      },
+    });
+    return reg;
+  };
+  const channel = await mount(port, server, families);
+  t.after(() => closeServer(server));
+
+  const snap = channel.inspect();
+  assertEquals(snap.path, "/agentic");
+  assertEquals(snap.families, ["probe"]);
+  assertEquals(trace, ["mount"]);
+  assert(channel.hub.router.has("register"), "family handler should be registered");
+
+  await channel.teardown();
+  assertEquals(trace, ["mount", "teardown"]);
+});
+
+test("teardown closes live connections and is idempotent", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mount(port, server);
+  t.after(() => closeServer(server));
+
+  const ws = await connect(port, `?token=${SECRET}&capability=cap-1`);
+  const closed = new Promise<void>((resolve) => ws.on("close", () => resolve()));
+  assertEquals(channel.hub.connectionCount, 1);
+
+  await channel.teardown();
+  await channel.teardown(); // second call is a no-op, must not throw
+  await closed;
+  assertEquals(ws.readyState, WebSocket.CLOSED);
+});
+
+test("a family mount failure tears down already-mounted families and closes the hub", async (t) => {
+  const { server, port } = await startHttp();
+  t.after(() => closeServer(server));
+  const trace: string[] = [];
+  const families = () => {
+    const reg = new AgenticFamilyRegistry();
+    reg.register({
+      name: "ok",
+      mount() {
+        trace.push("mount-ok");
+      },
+      teardown() {
+        trace.push("teardown-ok");
+      },
+    });
+    reg.register({
+      name: "boom",
+      mount() {
+        trace.push("mount-boom");
+        throw new Error("family boom failed to mount");
+      },
+    });
+    return reg;
+  };
+
+  let threw = false;
+  try {
+    await mount(port, server, families);
+  } catch {
+    threw = true;
+  }
+  assert(threw, "mountAgenticChannel must reject when a family mount throws");
+  // The already-mounted family was torn down (reverse order) — no family left half-mounted, and the
+  // hub was closed on the same path (see mountAgenticChannel's failure handler).
+  assertEquals(trace, ["mount-ok", "mount-boom", "teardown-ok"]);
+});
+
+test("a missing secret is refused (never mount an open channel)", async (t) => {
+  const { server, port } = await startHttp();
+  t.after(() => closeServer(server));
+  let threw = false;
+  try {
+    await mountAgenticChannel({ server, secret: "", data: undefined, log: noopLog() });
+  } catch {
+    threw = true;
+  }
+  assert(threw, "mountAgenticChannel must reject an empty secret");
+  assertEquals(port > 0, true);
+});

package/app/agentic/channel.ts

@@ -0,0 +1,124 @@
+// nano-workforce — mount the app-tier agentic channel hub (ADR 0056, H0 / #143).
+//
+// This is the keystone of the agentic-visibility epic (#142): it stands up the WebSocket channel +
+// hub on the app's OWN HTTP server (same port as the pages and `/app/api/hooks/*` — no sidecar
+// port), authenticates each upgrade (ADR 0028 identity token + a capability credential, mirroring
+// the `?token=…` pattern the blackboard hook uses), and mounts every registered family module
+// through the {@link AgenticFamilyRegistry} seam.
+//
+// `main.ts` calls {@link mountAgenticChannel} once after `runFromEnv` and calls the returned
+// handle's `teardown()` inside its existing `drainAndExit`. That is the ONLY place `main.ts` /
+// `drainAndExit` are edited for the whole epic — siblings extend the channel purely by dropping a
+// family module under `app/agentic/families/`.
+//
+// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+// is untouched; advisory semantics preserved (a family never gates a BPMN sequence flow).
+import type { Server } from "node:http";
+import {
+  AgenticHub,
+  sharedSecretAuthenticator,
+  WebSocketChannelTransport,
+} from "@nanobpm/agentic/channel";
+import type { DataLayer, Logger } from "@nanobpm/urban";
+import { loadAgenticFamilies } from "./loader.ts";
+import { AgenticFamilyRegistry } from "./registry.ts";
+
+/** The path the agentic channel is served on, on the app's own port. */
+export const AGENTIC_PATH = "/agentic";
+
+export interface MountAgenticChannelOptions {
+  /** The app's own `node:http` server (share its port; `app.httpServer` narrowed to `Server`). */
+  readonly server: Server;
+  /** The shared-secret ADR 0028 identity token every valid peer must present as `?token=…`. */
+  readonly secret: string;
+  /** The app's SQLite data layer, threaded to family modules (may be absent when data isn't mounted). */
+  readonly data: DataLayer | undefined;
+  /** A structured logger for lifecycle lines. */
+  readonly log: Logger;
+  /**
+   * Discover + register family modules from `app/agentic/families/`. Default: the real discovery
+   * loader. Tests inject a fixed set to keep the mount hermetic.
+   */
+  readonly families?: () => Promise<AgenticFamilyRegistry> | AgenticFamilyRegistry;
+}
+
+/** The live channel, returned to `main.ts` so it can inspect it and tear it down on shutdown. */
+export interface AgenticChannelHandle {
+  readonly hub: AgenticHub;
+  readonly transport: WebSocketChannelTransport;
+  readonly registry: AgenticFamilyRegistry;
+  /** A structured snapshot for `inspect()`/logs. */
+  inspect(): Record<string, unknown>;
+  /** Tear the families (reverse order) then the hub + transport down. Idempotent. */
+  teardown(): Promise<void>;
+}
+
+/** Build a family registry from the on-disk discovery loader (the production default). */
+async function discoverRegistry(log: Logger): Promise<AgenticFamilyRegistry> {
+  const registry = new AgenticFamilyRegistry();
+  registry.registerAll(await loadAgenticFamilies(undefined, log));
+  return registry;
+}
+
+/**
+ * Mount the agentic hub on `server`, authenticate upgrades with `secret`, and mount all discovered
+ * family modules. Returns a handle whose `teardown()` reverses everything.
+ */
+export async function mountAgenticChannel(
+  opts: MountAgenticChannelOptions,
+): Promise<AgenticChannelHandle> {
+  const { server, secret, data, log } = opts;
+  if (!secret) throw new Error("mountAgenticChannel requires a non-empty identity secret");
+
+  const transport = new WebSocketChannelTransport({ server, path: AGENTIC_PATH });
+  const hub = new AgenticHub({
+    transport,
+    // A valid identity token PLUS a required capability credential upgrades; either missing/invalid
+    // is rejected (4401 / 4403). Swap in a real ADR 0028 verifier later by passing an Authenticator.
+    authenticator: sharedSecretAuthenticator({ secret, requireCredential: true }),
+    onError: (err, connectionId) =>
+      log.warn("agentic hub error", { connectionId, err: String(err) }),
+  });
+  // Share the app's port: the transport rode the existing server, so it is already listening.
+  await transport.ready();
+
+  // If discovery or any family mount throws, the transport + hub are already live: tear down whatever
+  // mounted (in reverse) and close the hub before rethrowing, so a failed boot never strands upgrade
+  // handlers or half-open connections.
+  let registry: AgenticFamilyRegistry | undefined;
+  try {
+    registry = await (opts.families ? opts.families() : discoverRegistry(log));
+    await registry.mountAll({ hub, registry: hub.registry, transport, data, log });
+  } catch (err) {
+    await registry?.teardownAll(log);
+    await hub.close();
+    throw err;
+  }
+
+  log.info("agentic channel mounted", {
+    path: AGENTIC_PATH,
+    families: registry.names(),
+  });
+
+  let tornDown = false;
+  return {
+    hub,
+    transport,
+    registry,
+    inspect() {
+      return {
+        path: AGENTIC_PATH,
+        families: registry.names(),
+        connections: hub.connectionCount,
+        address: hub.address,
+      };
+    },
+    async teardown() {
+      if (tornDown) return;
+      tornDown = true;
+      await registry.teardownAll(log);
+      await hub.close();
+      log.info("agentic channel torn down");
+    },
+  };
+}

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

@@ -0,0 +1,35 @@
+// nano-workforce — a no-op EXAMPLE agentic family module (ADR 0056, H0 / #143).
+//
+// This is the concrete, copyable pattern H1 (#144), H3 (#146) and H4 (#147) follow. It lives in the
+// discovery directory (`app/agentic/families/`), so the loader ({@link ../loader.ts}) finds it by
+// the `*.family.ts` suffix and the H0 seam mounts + tears it down — a genuine registered sample. It
+// is a deliberate no-op (no message handler, no state), so mounting it in production is harmless.
+//
+// To add a real family slice, copy this file to `app/agentic/families/<slice>.family.ts`, rename it,
+// and implement `mount` (and optionally `teardown`). That is the WHOLE integration: you add ONE NEW
+// FILE and register NOTHING by hand — you never touch `main.ts` or `drainAndExit`.
+//
+// Reserved forward-only migration prefixes (do NOT compute "the next" number — use your reserved one):
+//   - H1 presence   → `db/migrations/023_agentic_presence.sql`
+//   - H3 transcript → `db/migrations/024_agentic_transcript.sql`
+//   - H4 blackboard → `db/migrations/025_agentic_blackboard.sql` (only if a schema change is needed)
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+
+/**
+ * A minimal, no-op family. A real slice would, inside `mount`:
+ *   - `ctx.hub.registerFamilyHandler("<family>", (frame, conn) => { … })` to own a message family,
+ *   - persist via `ctx.data` (the app's SQLite DataLayer — the same store the blackboard uses),
+ *   - attach presence via `ctx.registry.setPresence(conn.id, …)`,
+ * and release those in `teardown`.
+ */
+export const family: AgenticFamily = {
+  name: "example",
+  mount(_ctx: AgenticContext): void {
+    // No-op template. Replace with the slice's real wiring against `_ctx`.
+  },
+  teardown(): void {
+    // No-op template. Release anything `mount` acquired here.
+  },
+};
+
+export default family;

package/app/agentic/loader.test.ts

@@ -0,0 +1,79 @@
+// Unit tests for the agentic family DISCOVERY loader (ADR 0056, H0 / #143).
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import { loadAgenticFamilies } from "./loader.ts";
+
+/** A discovered family module's source: exports a named `family` with the given `name`. */
+function familyModuleSource(name: string): string {
+  return `export const family = { name: ${JSON.stringify(name)}, mount() {}, teardown() {} };\n`;
+}
+
+async function withTempDir(fn: (dir: string) => Promise<void>): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), "agentic-loader-"));
+  try {
+    await fn(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+test("discovers *.family.ts modules in sorted (deterministic) order", async () => {
+  await withTempDir(async (dir) => {
+    await writeFile(join(dir, "relay.family.ts"), familyModuleSource("relay"));
+    await writeFile(join(dir, "presence.family.ts"), familyModuleSource("presence"));
+    await writeFile(join(dir, "blackboard.family.ts"), familyModuleSource("blackboard"));
+    const families = await loadAgenticFamilies(dir, noopLog());
+    // Sorted by filename: blackboard.family.ts < presence.family.ts < relay.family.ts.
+    assertEquals(families.map((f) => f.name), ["blackboard", "presence", "relay"]);
+  });
+});
+
+test("ignores non-family files, test files, and READMEs", async () => {
+  await withTempDir(async (dir) => {
+    await writeFile(join(dir, "presence.family.ts"), familyModuleSource("presence"));
+    await writeFile(join(dir, "presence.family.test.ts"), "export const nope = 1;\n");
+    await writeFile(join(dir, "helper.ts"), "export const nope = 2;\n");
+    await writeFile(join(dir, "README.md"), "# families\n");
+    const families = await loadAgenticFamilies(dir, noopLog());
+    assertEquals(families.map((f) => f.name), ["presence"]);
+  });
+});
+
+test("a missing families directory yields no families (not an error)", async () => {
+  const families = await loadAgenticFamilies(join(tmpdir(), "does-not-exist-agentic-xyz"), noopLog());
+  assertEquals(families, []);
+});
+
+test("accepts a default export as well as a named `family` export", async () => {
+  await withTempDir(async (dir) => {
+    await writeFile(
+      join(dir, "def.family.ts"),
+      "export default { name: 'viaDefault', mount() {} };\n",
+    );
+    const families = await loadAgenticFamilies(dir, noopLog());
+    assertEquals(families.map((f) => f.name), ["viaDefault"]);
+  });
+});
+
+test("skips a module that exports no valid family, without crashing discovery", async () => {
+  await withTempDir(async (dir) => {
+    await writeFile(join(dir, "ok.family.ts"), familyModuleSource("ok"));
+    // No `family`/`default`; and a malformed one (missing mount).
+    await writeFile(join(dir, "empty.family.ts"), "export const something = 1;\n");
+    await writeFile(join(dir, "bad.family.ts"), "export const family = { name: 'bad' };\n");
+    const families = await loadAgenticFamilies(dir, noopLog());
+    assertEquals(families.map((f) => f.name), ["ok"]);
+  });
+});
+
+test("the real families/ directory discovers the copyable example no-op", async () => {
+  const families = await loadAgenticFamilies(undefined, noopLog());
+  assert(
+    families.some((f) => f.name === "example"),
+    "expected the shipped example family to be discovered",
+  );
+});

package/app/agentic/loader.ts

@@ -0,0 +1,84 @@
+// nano-workforce — the agentic family DISCOVERY loader (ADR 0056, H0 / #143).
+//
+// Siblings drop a `*.family.ts` module into `app/agentic/families/`; this loader finds it by
+// convention and imports it. There is deliberately NO central registration array for siblings to
+// append to (that would merely relocate the shared-file collision the plan review flagged): a family
+// is discovered purely by living in the conventional directory with the conventional suffix.
+//
+// A discovered module contributes its family via a default export OR a named `family` export. Any
+// `*.test.ts` file is ignored (test files never carry a family), and a module that exports no valid
+// family is skipped with a warning rather than crashing boot.
+import { readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { Logger } from "@nanobpm/urban";
+import type { AgenticFamily } from "./registry.ts";
+
+/** The conventional directory holding sibling family modules, resolved next to this loader. */
+export const FAMILIES_DIR = join(dirname(fileURLToPath(import.meta.url)), "families");
+
+/** The filename suffix a family module must carry to be discovered. */
+const FAMILY_SUFFIX = ".family.ts";
+
+/** Read a property off an unknown object without an unsafe cast. */
+function prop(obj: object, key: string): unknown {
+  return Object.hasOwn(obj, key) ? Object.getOwnPropertyDescriptor(obj, key)?.value : undefined;
+}
+
+/** A type guard proving an unknown value structurally satisfies {@link AgenticFamily}. */
+function isAgenticFamily(candidate: unknown): candidate is AgenticFamily {
+  if (!candidate || typeof candidate !== "object") return false;
+  const name = prop(candidate, "name");
+  if (typeof name !== "string" || name.trim() === "") return false;
+  if (typeof prop(candidate, "mount") !== "function") return false;
+  const teardown = prop(candidate, "teardown");
+  return teardown === undefined || typeof teardown === "function";
+}
+
+/** Structurally validate a discovered module's contribution as an {@link AgenticFamily}. */
+function asFamily(mod: unknown): AgenticFamily | undefined {
+  if (!mod || typeof mod !== "object") return undefined;
+  const candidate = prop(mod, "family") ?? prop(mod, "default");
+  return isAgenticFamily(candidate) ? candidate : undefined;
+}
+
+/**
+ * Discover every family module under `dir` (default {@link FAMILIES_DIR}), imported in a stable
+ * (sorted-by-filename) order so mount/teardown order is deterministic across hosts. A missing
+ * directory yields no families (the epic's first slice ships before any sibling exists). A module
+ * that fails to import or exports no valid family is logged and skipped, never fatal to boot.
+ */
+export async function loadAgenticFamilies(
+  dir: string = FAMILIES_DIR,
+  log?: Logger,
+): Promise<AgenticFamily[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch (err) {
+    // A missing families directory is the expected steady state before any sibling lands.
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return [];
+    throw err;
+  }
+  const files = entries
+    .filter((name) => name.endsWith(FAMILY_SUFFIX))
+    .sort();
+  const families: AgenticFamily[] = [];
+  for (const name of files) {
+    const href = pathToFileURL(join(dir, name)).href;
+    let mod: unknown;
+    try {
+      mod = await import(href);
+    } catch (err) {
+      log?.error("agentic family module failed to import", { file: name, err: String(err) });
+      continue;
+    }
+    const family = asFamily(mod);
+    if (!family) {
+      log?.warn("agentic family module exported no valid family; skipping", { file: name });
+      continue;
+    }
+    families.push(family);
+  }
+  return families;
+}

package/app/agentic/registry.test.ts

@@ -0,0 +1,160 @@
+// Unit tests for the agentic family-registration seam (ADR 0056, H0 / #143).
+import { test } from "node:test";
+import { assert, assertEquals, assertRejects, assertThrows } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import { type AgenticContext, AgenticFamilyRegistry, type AgenticFamily } from "./registry.ts";
+
+// A minimal context — the seam only threads it through to `mount`, so the tests don't need a real
+// hub. `undefined`/no-op handles are fine here; the channel test exercises the real handles.
+function fakeCtx(): AgenticContext {
+  // biome-ignore lint/suspicious/noExplicitAny: seam only forwards ctx opaquely in these tests
+  const stub: any = {};
+  return { hub: stub, registry: stub, transport: stub, data: undefined, log: noopLog() };
+}
+
+/** A family that records the order of mount/teardown calls into a shared trace. */
+function tracer(name: string, trace: string[]): AgenticFamily {
+  return {
+    name,
+    mount() {
+      trace.push(`mount:${name}`);
+    },
+    teardown() {
+      trace.push(`teardown:${name}`);
+    },
+  };
+}
+
+test("mounts families in registration order, tears them down in reverse", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.registerAll([tracer("a", trace), tracer("b", trace), tracer("c", trace)]);
+  assertEquals(reg.names(), ["a", "b", "c"]);
+
+  await reg.mountAll(fakeCtx());
+  assertEquals(trace, ["mount:a", "mount:b", "mount:c"]);
+
+  await reg.teardownAll(noopLog());
+  assertEquals(trace, ["mount:a", "mount:b", "mount:c", "teardown:c", "teardown:b", "teardown:a"]);
+});
+
+test("mountAll is idempotent — a second call never re-mounts", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register(tracer("a", trace));
+  const ctx = fakeCtx();
+  await reg.mountAll(ctx);
+  await reg.mountAll(ctx);
+  assertEquals(trace, ["mount:a"]);
+});
+
+test("teardownAll only reverses families that actually mounted, and is idempotent", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register(tracer("a", trace));
+  await reg.mountAll(fakeCtx());
+  await reg.teardownAll();
+  await reg.teardownAll();
+  assertEquals(trace, ["mount:a", "teardown:a"]);
+});
+
+test("a rejected duplicate family name protects one-family-one-slot", () => {
+  const reg = new AgenticFamilyRegistry();
+  reg.register({ name: "dup", mount() {} });
+  assertThrows(() => reg.register({ name: "dup", mount() {} }), Error, "duplicate agentic family");
+});
+
+test("registering after mount is refused", async () => {
+  const reg = new AgenticFamilyRegistry();
+  reg.register({ name: "a", mount() {} });
+  await reg.mountAll(fakeCtx());
+  assertThrows(() => reg.register({ name: "b", mount() {} }), Error, "after mount");
+});
+
+test("a family with no teardown is skipped cleanly on shutdown", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register({ name: "no-teardown", mount() {
+    trace.push("mount");
+  } });
+  await reg.mountAll(fakeCtx());
+  await reg.teardownAll();
+  assertEquals(trace, ["mount"]);
+});
+
+test("one family's teardown throw is isolated and does not strand siblings", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register(tracer("a", trace));
+  reg.register({
+    name: "boom",
+    mount() {
+      trace.push("mount:boom");
+    },
+    teardown() {
+      throw new Error("teardown boom");
+    },
+  });
+  await reg.mountAll(fakeCtx());
+  // Should not throw despite "boom" failing; "a" must still tear down.
+  await reg.teardownAll(noopLog());
+  assertEquals(trace, ["mount:a", "mount:boom", "teardown:a"]);
+});
+
+test("a mount failure only tears down what actually mounted", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register(tracer("a", trace));
+  reg.register({
+    name: "fails",
+    mount() {
+      throw new Error("mount fails");
+    },
+    teardown() {
+      trace.push("teardown:fails");
+    },
+  });
+  await assertRejects(() => reg.mountAll(fakeCtx()), Error, "mount fails");
+  await reg.teardownAll();
+  // "fails" never completed mount, so its teardown must not run; "a" did mount, so it tears down.
+  assertEquals(trace, ["mount:a", "teardown:a"]);
+});
+
+test("mountAll self-heals after a mid-mount failure — a retry re-mounts, never a stuck no-op", async () => {
+  const trace: string[] = [];
+  const reg = new AgenticFamilyRegistry();
+  reg.register(tracer("a", trace));
+  let shouldFail = true;
+  reg.register({
+    name: "flaky",
+    mount() {
+      if (shouldFail) {
+        shouldFail = false;
+        throw new Error("mount fails once");
+      }
+      trace.push("mount:flaky");
+    },
+    teardown() {
+      trace.push("teardown:flaky");
+    },
+  });
+
+  // First attempt fails mid-mount; mountAll must reverse the partial mount and reset its own state
+  // (without the caller having to call teardownAll)...
+  await assertRejects(() => reg.mountAll(fakeCtx()), Error, "mount fails once");
+  assertEquals(trace, ["mount:a", "teardown:a"]);
+
+  // ...so a retry actually re-mounts instead of being a silent no-op (the wedged-state regression).
+  await reg.mountAll(fakeCtx());
+  assertEquals(trace, ["mount:a", "teardown:a", "mount:a", "mount:flaky"]);
+
+  await reg.teardownAll();
+  assertEquals(trace, [
+    "mount:a",
+    "teardown:a",
+    "mount:a",
+    "mount:flaky",
+    "teardown:flaky",
+    "teardown:a",
+  ]);
+});

package/app/agentic/registry.ts

@@ -0,0 +1,130 @@
+// nano-workforce — the agentic-channel family-registration SEAM (ADR 0056, H0 / #143).
+//
+// This module is OWNED by H0 (the keystone slice). It is the single extension point every sibling
+// slice of the agentic-visibility epic (#142) plugs into:
+//
+//   - H1 presence  (#144) → adds `app/agentic/families/presence.family.ts`
+//   - H3 relay     (#146) → adds `app/agentic/families/relay.family.ts`
+//   - H4 blackboard(#147) → adds `app/agentic/families/blackboard.family.ts`
+//
+// A sibling adds ONE NEW FILE under `app/agentic/families/` exporting an {@link AgenticFamily} and
+// NOTHING ELSE — it never edits `main.ts`, `drainAndExit`, or any shared boot line. The loader
+// ({@link ./loader.ts}) discovers those files by convention (`*.family.ts`) and hands them to this
+// registry, so there is no central registration list for siblings to collide on either — the
+// shared-file collision the plan review flagged is designed out, not merely relocated.
+//
+// The registry mounts families on boot (in discovery order) and tears them down in REVERSE order on
+// shutdown — the mirror-image lifecycle a stack of resources needs so a later family that depends on
+// an earlier one is torn down first.
+//
+// RESERVED forward-only migration prefixes (H0 pre-allocates these so no two siblings independently
+// grab "the next" number — current highest committed prefix is 022):
+//   - `db/migrations/023_agentic_presence.sql`   → H1 (#144)
+//   - `db/migrations/024_agentic_transcript.sql` → H3 (#146)
+//   - `db/migrations/025_agentic_blackboard.sql` → H4 (#147), only if it needs a schema change
+//
+// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+// is untouched — the agentic channel is the only new conversation; advisory semantics are preserved
+// (a family NEVER hard-locks or gates a BPMN sequence flow).
+import type { AgenticHub, ConnectionRegistry, WebSocketChannelTransport } from "@nanobpm/agentic/channel";
+import type { DataLayer, Logger } from "@nanobpm/urban";
+
+/**
+ * The reusable handle the seam threads to every family module at mount time. A sibling family uses
+ * these — and only these — so it never re-mounts the transport, re-authenticates, or reaches into
+ * the boot script.
+ */
+export interface AgenticContext {
+  /** The app-tier hub: attach a family message handler via `hub.registerFamilyHandler(...)`. */
+  readonly hub: AgenticHub;
+  /** The shared connection registry with liveness (presence detail is attached here by H1). */
+  readonly registry: ConnectionRegistry;
+  /** The listening WebSocket transport bound to the app's OWN port. */
+  readonly transport: WebSocketChannelTransport;
+  /** The app's SQLite data layer — the same store the advisory blackboard uses (may be absent). */
+  readonly data: DataLayer | undefined;
+  /** A structured logger for boot/shutdown lifecycle lines. */
+  readonly log: Logger;
+}
+
+/**
+ * One pluggable family module. A sibling slice implements this and exports it (default export, or a
+ * named `family` export) from a `*.family.ts` file under `app/agentic/families/`.
+ */
+export interface AgenticFamily {
+  /** A stable, unique name (used for ordering diagnostics, `inspect()`, and teardown logging). */
+  readonly name: string;
+  /** Attach the family's behaviour to the hub/channel. May be async. */
+  mount(ctx: AgenticContext): void | Promise<void>;
+  /** Release anything `mount` acquired. Called in REVERSE registration order on shutdown. */
+  teardown?(): void | Promise<void>;
+}
+
+/**
+ * The seam itself: collects registered families, mounts them all on boot (in registration order),
+ * and tears them down in reverse on shutdown. Mounting is idempotent-guarded (each family mounts at
+ * most once) so a double `mountAll` can never double-attach a handler.
+ */
+export class AgenticFamilyRegistry {
+  readonly #families: AgenticFamily[] = [];
+  readonly #mounted: AgenticFamily[] = [];
+  #isMounted = false;
+
+  /** Register a family. Rejects a duplicate name so two slices cannot silently claim one slot. */
+  register(family: AgenticFamily): void {
+    if (this.#isMounted) {
+      throw new Error(`cannot register agentic family "${family.name}" after mount`);
+    }
+    if (this.#families.some((f) => f.name === family.name)) {
+      throw new Error(`duplicate agentic family name "${family.name}"`);
+    }
+    this.#families.push(family);
+  }
+
+  /** Register several families at once (the loader hands the discovered set here). */
+  registerAll(families: Iterable<AgenticFamily>): void {
+    for (const family of families) this.register(family);
+  }
+
+  /** The registered family names, in registration order. Surfaced in `inspect()`/logs. */
+  names(): string[] {
+    return this.#families.map((f) => f.name);
+  }
+
+  /** Mount every registered family, in registration order. A no-op if already mounted. */
+  async mountAll(ctx: AgenticContext): Promise<void> {
+    if (this.#isMounted) return;
+    this.#isMounted = true;
+    try {
+      for (const family of this.#families) {
+        await family.mount(ctx);
+        // Track post-mount so a failure mid-mount only tears down what actually mounted.
+        this.#mounted.push(family);
+      }
+    } catch (err) {
+      // A mid-mount failure must not wedge the registry at #isMounted=true (which would make every
+      // later mountAll a silent no-op). Reuse the canonical teardown to reverse the partial mount and
+      // reset the flag, leaving the registry clean and re-mountable, then rethrow to the caller.
+      await this.teardownAll(ctx.log);
+      throw err;
+    }
+  }
+
+  /**
+   * Tear every mounted family down in REVERSE mount order. Each teardown is isolated: a throw is
+   * logged (when a logger is supplied) and swallowed so one family's failure cannot strand another's
+   * cleanup. Safe to call more than once; the second call is a no-op.
+   */
+  async teardownAll(log?: Logger): Promise<void> {
+    while (this.#mounted.length > 0) {
+      const family = this.#mounted.pop();
+      if (!family?.teardown) continue;
+      try {
+        await family.teardown();
+      } catch (err) {
+        log?.error("agentic family teardown failed", { family: family.name, err: String(err) });
+      }
+    }
+    this.#isMounted = false;
+  }
+}

package/docs/adr/0001-cross-repo-epics-and-artifact-wait-gates.md

@@ -0,0 +1,151 @@
+# ADR 0001 — Cross-repo epics, release-ordered integration, and generic artifact wait-gates
+
+Status: **Proposed.**
+Date: 2026-08-13.
+
+> **Scope note.** This is a **nano-workforce-local** ADR — it governs how *this app's* agent
+> workforce decomposes and integrates epics. The platform-wide ADRs live in
+> `Magikcraft/nano-bpm/docs/adr` (referenced here by their number + repo, e.g. "nano-bpm ADR 0056").
+> nano-workforce's own decisions start their own series here at 0001.
+
+Relates to:
+nano-bpm **ADR 0051** (nano-workforce — the crew orchestrator this app implements),
+nano-bpm **ADR 0056** (the Nano agentic protocol — the first consumer/producer *pair* that forced this
+question: the hub epic https://github.com/nanobpm/nano-workforce/issues/142 and the worker epic
+https://github.com/jwulf/c8ctl-plugin-nano/issues/38 live in **different repos** yet share one
+published contract),
+the **review-ready poller** in `main.ts` (a bespoke "wait for an external condition, then correlate a
+message" loop — the seed this ADR generalizes into a first-class wait-gate),
+and nano-bpm **ADR 0059** (the app-hosted OpenAPI hook surface these gates would be signalled through).
+
+## Context
+
+nano-workforce executes an epic as a **single-repo** unit, and every load-bearing piece assumes it:
+
+- **The repo is epic-level, not task-level.** `Plan.repo` carries the repository; `PlanTask`
+  (`app/plan.ts`) has **no** `repo` field. Fan-out clones *the epic's* repo for every slice.
+- **Integration converges on one base branch in one repo.** The epic lands on a base branch; slices
+  PR into it; the merge-loop trial-merges the set and merges the epic (nano-bpm ADR 0051 machinery:
+  wave gates, base-branch guards, merge-loop reconciliation).
+- **There is no "publish" step and no "wait for the outside world" primitive.** The only wait nwf does
+  is the hand-rolled review-ready poller in `main.ts`, which polls GitHub and correlates a
+  `review-ready` message. It is not reusable and knows only about PR reviews.
+
+But real delivery in this ecosystem is **cross-repo by construction**. Shared libraries
+(`@nanobpm/urban`, `@nanobpm/agentic`) are published from one repo and consumed downstream (this app,
+c8ctl). The `urban → nano-workforce → c8ctl` chain is exactly a producer→consumer graph across repos
+with an npm publish in the middle. Building the agentic visibility plane surfaced three concrete gaps:
+(a) no per-task repo, (b) no release/publish step, (c) no wait-for-external-artifact primitive.
+
+The temptation is to answer all three at once by making nwf a cross-repo, release-orchestrating
+engine. That is a real redesign of the integration model and its highest-risk parts. Before paying for
+it, note that **most cross-repo coupling in practice is a *versioned contract*, not a merge order** —
+and a contract can be consumed *after* it is published, with no live cross-repo sequencing at all.
+
+## Decision
+
+### 1. Prefer contract-coupled per-repo epics over cross-repo epics (the default)
+
+When two sides of a feature share a **versioned contract** — a published package plus a **conformance
+corpus** both sides are held to — split the work into **one single-repo epic per repo**, each building
+against the **already-published** contract. They coordinate through the contract, never through a merge
+order. Neither epic waits on the other's code.
+
+The agentic visibility plane is exactly this and ships this way, as **two** epics:
+
+- **producer:** https://github.com/jwulf/c8ctl-plugin-nano/issues/38 (`nano work` → REGISTER/SERVE/relay);
+- **hub + cockpit:** https://github.com/nanobpm/nano-workforce/issues/142.
+
+Both consume the published `@nanobpm/agentic` and are held to `@nanobpm/agentic/protocol/conformance`.
+This keeps nwf's proven single-repo integration model **entirely intact** and is the default posture
+for any producer/consumer pair that can be expressed against a stable contract.
+
+### 2. A generic artifact-readiness wait-gate (not npm-specific)
+
+Generalize the review-ready poller into a **first-class, durable wait-gate**: a service task that
+**polls a declared readiness probe with backoff until it is satisfied or a timeout escalates**, then
+lets the flow proceed (or correlates a message). It is modeled on the engine (timer + receive), so a
+worker or hub restart **resumes** the wait rather than losing it.
+
+The probe is **declared as data, not code** — a `ReadinessProbe` descriptor with a `kind` and pluggable
+matchers, so authors add readiness sources without editing the BPMN or the worker:
+
+```jsonc
+// ReadinessProbe — the gate is agnostic to what "ready" means.
+{
+  "kind": "http",                       // http | command | npm | oci | git-ref | github-release | github-check | file
+  "target": "https://example/health",  // URL | shell command | "pkg@version" | "image:tag" | "owner/repo@ref" | path
+  "match": { "status": 200 },           // per-kind predicate (status/body, exit code/stdout, version present, digest, …)
+  "poll":  { "everyMs": 15000, "timeoutMs": 1800000, "backoff": "exponential" },
+  "onTimeout": "escalate"               // escalate (default) | fail | continue
+}
+```
+
+Invariants:
+
+- **Never npm-specific.** `npm` is *one* kind among many; `command` is the escape hatch that subsumes
+  almost anything (`gh`, `curl`, `docker manifest inspect`, a custom probe) for cases no built-in kind
+  covers. Adding a kind is a new matcher, not a schema change.
+- **Bounded.** A probe that never goes green must **time out and escalate** (mirroring the per-task
+  escalation path) — a hanging probe can never wedge a plan.
+- **Idempotent / resumable.** The gate only *reads* readiness; it holds no state a re-run could corrupt,
+  so a restarted worker simply re-probes.
+
+This is immediately useful well beyond releases: waiting on CI, a downstream deploy, an external
+system, a human approval, or a produced artifact.
+
+### 3. The shared-library bump stays a manual maintainer seam — for now
+
+A downstream version bump (e.g. `@nanobpm/urban` → this app) after an upstream release is handled by a
+maintainer **outside** the epic, until §4 lands. It is cheap, low-risk, and rare relative to the
+intra-repo work of an epic. This is the deliberate, documented seam that lets §1 stay simple: the
+*only* cross-repo dependency in the agentic plane (nano-ide `UrbanApp.httpServer`,
+https://github.com/nanobpm/nano-ide/issues/221 → an `@nanobpm/urban` release → a bump here) is a
+one-line human step, not a reason to build a cross-repo engine.
+
+### 4. Release-ordered cross-repo integration (the "release DAG") — deferred, sketched
+
+Some future work genuinely cannot decouple: a consumer needs a producer's **new** release *mid-epic*.
+For those cases only, model integration as a **DAG across independent per-repo merge trains**:
+
+```
+producer PRs → merge → publish → [artifact wait-gate §2] → consumer PRs open/build → merge
+```
+
+This replaces the single-epic-branch assumption **for those cases**, and requires, in order:
+
+1. **Per-task repo.** Add `repo` to `PlanTask`, derive it from each sub-issue (`parseIssue` already
+   yields `owner/repo`), and thread it into the `io.nanobpm.agentTask.repository` clone header. The
+   merge/review/finalize workers are *already* repo-parameterized (they take `repo` per PR and load the
+   merge protocol per repo), so this is mostly plan/task plumbing.
+2. **A release task type.** bump version → merge → **§2 wait-gate on artifact availability** → signal
+   downstream. Publish is at-least-once; the task must tolerate a re-run (mirror the idempotent
+   `scripts/publish.mjs` "skip already-published" discipline).
+3. **Cross-train ordering.** A meta-plan (or a first-class multi-repo epic) that sequences the per-repo
+   trains and their gates.
+
+This is its **own follow-up epic with its own design**. Do **not** build it speculatively — §1 removes
+the need for the foreseeable roadmap, and §2 is the reusable building block it will stand on.
+
+## Consequences
+
+- The agentic visibility plane ships **now** as two single-repo epics; nwf's integration model
+  (base-branch, trial-merge, merge-loop, wave gates) is untouched and unrisked.
+- nwf gains a durable **"wait for the world"** primitive it currently fakes with the bespoke review
+  poller; the poller can later be re-expressed as one `github-check`/`http` gate.
+- New surface to own: the `ReadinessProbe` kinds. A malformed or hanging probe is bounded by the
+  mandatory timeout+escalation, so it cannot stall a plan.
+- Shared-library bumps stay manual until §4 — an accepted cost given their frequency.
+- When §4 is eventually built, §1 + §2 mean it is *additive* (a new integration topology + a release
+  task) rather than a rewrite.
+
+## Open questions
+
+- **Probe extensibility model:** a curated registry of `kind`s vs leaning on the `command` escape hatch
+  for the long tail — and how a probe's credentials/secrets are supplied without leaking into logs.
+- **Where cross-train ordering lives (§4):** a meta-plan across existing epics, or a genuine
+  first-class multi-repo epic with per-task repos.
+- **Per-repo divergence when per-task repo lands:** merge protocol, required checks, Copilot-review
+  provisioning (not available on every repo), and push auth all differ per repo.
+- **Gate signalling:** in-flow receive task vs an out-of-band message correlated by an app-side poller
+  (the review-ready shape) — likely both, chosen per use.

package/main.ts

@@ -16,8 +16,11 @@
 // The reviewer agent (job type `senior:pr-review`) is deliberately NOT hosted here — it is an
 // EXTERNAL worker. Point a coding-agent harness at that job type (the same one that services
 // the code-first twin) so the automated review stays decoupled from the orchestration.
+import { Server } from "node:http";
 import { createNanoSdkEngineClient, runFromEnv, selectHost } from "@nanobpm/urban";
+import { type AgenticChannelHandle, mountAgenticChannel } from "./app/agentic/channel.ts";
 import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
+import { envVar } from "./app/version.ts";
 
 const PORT = Number(process.env.PR_REVIEW_PORT ?? 3000);
 const POLL_MS = Number(process.env.NANO_PR_POLL_MS ?? 60_000);
@@ -40,6 +43,30 @@ const engine = await createNanoSdkEngineClient({
 // signal handler would only stop the HTTP server, leaving the poller keeping us alive).
 const app = await runFromEnv({ engine, host, port: PORT, handleSignals: false });
 
+// Agentic visibility channel (ADR 0056, epic #142). Ride the app's OWN HTTP server so the channel
+// shares the app port (no sidecar). This is the ONLY main.ts wiring for the whole epic — sibling
+// slices (H1/H3/H4) extend it by dropping a family module under `app/agentic/families/`, never here.
+// Mount only when a shared identity secret is configured, so the app never exposes an
+// unauthenticated upgrade; `app.httpServer` is a `node:http` Server once started (undefined on hosts
+// that don't surface one, e.g. Deno).
+let agentic: AgenticChannelHandle | undefined;
+const agenticSecret = envVar("NANO_AGENTIC_SECRET") ?? envVar("NANO_PR_WEBHOOK_SECRET");
+const httpServer = app.httpServer;
+if (httpServer instanceof Server) {
+  if (agenticSecret) {
+    agentic = await mountAgenticChannel({
+      server: httpServer,
+      secret: agenticSecret,
+      data: app.data,
+      log: app.log,
+    });
+  } else {
+    app.log.warn("agentic channel not mounted: set NANO_AGENTIC_SECRET (or NANO_PR_WEBHOOK_SECRET)");
+  }
+} else if (agenticSecret) {
+  app.log.warn("agentic channel not mounted: app.httpServer is not a node:http Server on this host");
+}
+
 // Review-ready poller. Self-scheduling (not setInterval) so a slow GitHub call can never
 // overlap two passes (which could double-signal `review-ready`); the next pass is scheduled
 // only after the previous one settles.
@@ -59,6 +86,13 @@ async function drainAndExit(): Promise<void> {
   if (shuttingDown) return;
   shuttingDown = true;
   if (pollTimer) clearTimeout(pollTimer);
+  // Tear the agentic families + hub down (releases the WS clients) before the app stops its HTTP
+  // server, which the channel shares.
+  if (agentic) {
+    try {
+      await agentic.teardown();
+    } catch { /* best-effort channel shutdown */ }
+  }
   try {
     await app.stop();
   } catch { /* already stopped */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -46,7 +46,8 @@
     "lint:fix": "biome check --write app operations workers pages components scripts e2e main.ts"
   },
   "dependencies": {
-    "@nanobpm/urban": "^0.45.0"
+    "@nanobpm/agentic": "^0.1.0",
+    "@nanobpm/urban": "^0.46.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",

package/prompts/plan-review.md

@@ -40,6 +40,19 @@ decomposition **from the issues**, then test the plan against it.
   `dependsOn` it. Reject a `dependsOn` edge added purely to **serialise the landing** of otherwise
   parallel work — that is not a fix, it just needlessly serialises implementation; name the pair,
   the shared surface, and which of (a)/(b) the planner should apply.
+- **Package fragmentation (Conway artifact).** The plan gives a cohesive body of work its own
+  published unit **per task** — N tasks ⇒ N npm packages / crates / services — where one library
+  with the slices as **subpath exports / subdirectories** would serve the same consumers. This is
+  the task decomposition leaking into the artifact's module boundaries: separate packages are the
+  frictionless maximum of independence, so they get chosen by default, then have to be
+  unfragmented by hand (and each extra published unit is a publish/credentials bootstrap +
+  changelog + version cadence forever). Try to disprove that each **new** published-package
+  boundary is **consumer-driven**: is there a distinct external consumer of *it* alone, an
+  intentional independent release cadence, or a different runtime tier? If not for a given
+  package, flag it and demand the remedy: **coarsen the siblings into one package** exposing
+  subpaths, landing a **wave-0 scaffold task** (manifest with the full exports map
+  pre-declared + one empty subdirectory per slice) first if the shared manifest would otherwise be
+  a merge collision. Name the packages that lack a consumer-facing justification.
 - **Non-self-contained prompt.** A task's `prompt` can't be executed without reasoning the planner
   kept to itself.
 - **Sequencing intent violated.** If the issues state an ordering (e.g. "audit the foundation

package/prompts/plan.md

@@ -157,6 +157,41 @@ Choose (1) when the surface *is* the task; choose (2) when the surface is shared
 infrastructure several distinct tasks sit on top of. Reserve plain parallel tasks
 (no shared surface) for genuinely disjoint work.
 
+### Packaging cohesion → one library, subpaths, not a package per task
+
+The shared-surface rule above pushes toward independence, and independence has a
+seductive failure mode: giving each task its **own published unit** (npm package,
+crate, service) is the *frictionless maximum* of independence — a separate
+manifest, separate exports, separate directory mean zero shared surface and zero
+merge collision. So a plan that slices a single cohesive library into N tasks will,
+left alone, tend to emit **N packages** — one per task. That is not a design; it is
+your task decomposition leaking into the artifact's module boundaries (Conway's
+Law). It has to be unfragmented by hand later, and each extra published unit is a
+one-time publish/credentials bootstrap plus a changelog and version cadence forever.
+
+So, before you slice: **a new published unit requires a consumer-facing
+justification, not merely "this is an independent task."** A new package/crate/
+service is warranted only when at least one is true:
+
+- a **distinct external consumer** imports it on its own (something outside the
+  family depends on *it*, not on its siblings);
+- it needs an **independent release cadence** (versioned and shipped separately on
+  purpose); or
+- it is a **different runtime tier** (e.g. a browser bundle vs. a server library vs.
+  a worker client) that consumers install separately.
+
+Absent one of those, the default is **one library, with the slices as subpath
+exports / subdirectories inside it** (the shape of a package that exposes several
+surfaces — e.g. `./runtime`, `./toolkit`, `./worker` — from a single manifest). The
+slices stay independent to *write*: use the
+**wave-0 scaffold task** (option 2 above) to land the library skeleton first — its
+manifest with the **full exports map pre-declared** and an empty subdirectory per
+slice — so every sibling only **adds files inside its own subdirectory** and never
+touches the shared manifest or barrel. That buys parallel-merge independence **and**
+a cohesive published artifact at the same time. Reserve genuinely separate packages
+for the consumer-facing cases above, and say in the task prompt which consumer
+justifies the split.
+
 ## Output contract
 
 Write a JSON object of **result variables** to the file named by the