@nanobpm/nano-workforce 0.49.0 → 0.51.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Features
+
+* **merge:** adopt @nanobpm/urban/effect matchTags for exhaustive land dispatch ([#139](https://github.com/nanobpm/nano-workforce/issues/139)) ([c251763](https://github.com/nanobpm/nano-workforce/commit/c251763a050858ea610ce45e59a34f859163c29c)), closes [nano-ide#215](https://github.com/nano-ide/issues/215)
+
 # [0.49.0](https://github.com/nanobpm/nano-workforce/compare/v0.48.2...v0.49.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;
+}