@nanobpm/nano-workforce 0.51.0 → 0.53.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.53.0](https://github.com/nanobpm/nano-workforce/compare/v0.52.0...v0.53.0) (2026-08-13)
+
+
+### Features
+
+* relay ring + transcript store agentic family (H3) ([#162](https://github.com/nanobpm/nano-workforce/issues/162)) ([f629526](https://github.com/nanobpm/nano-workforce/commit/f62952698fa3cfb3321e60fdce61fdb1f13ca9d6)), closes [#142](https://github.com/nanobpm/nano-workforce/issues/142) [#143](https://github.com/nanobpm/nano-workforce/issues/143) [#146](https://github.com/nanobpm/nano-workforce/issues/146) [#streams](https://github.com/nanobpm/nano-workforce/issues/streams)
+
+# [0.52.0](https://github.com/nanobpm/nano-workforce/compare/v0.51.0...v0.52.0) (2026-08-13)
+
+
+### Features
+
+* presence + registry family over app.data (H1) ([#161](https://github.com/nanobpm/nano-workforce/issues/161)) ([6666ff1](https://github.com/nanobpm/nano-workforce/commit/6666ff148d02bc0f7ae9740511fdc62bbe9c2e70)), closes [#142](https://github.com/nanobpm/nano-workforce/issues/142) [#152](https://github.com/nanobpm/nano-workforce/issues/152) [#152](https://github.com/nanobpm/nano-workforce/issues/152) [#144](https://github.com/nanobpm/nano-workforce/issues/144)
+
 # [0.51.0](https://github.com/nanobpm/nano-workforce/compare/v0.50.0...v0.51.0) (2026-08-13)
 
 

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

@@ -0,0 +1,341 @@
+// Unit tests for the agentic presence & registry family (ADR 0056, H1 / #144).
+//
+// Two layers:
+//   1. PresenceRegistry over an in-memory SQLite DataLayer — snapshot grouping, liveness, the
+//      jobKeys seam, the canonical supply rows, reconcile, and the register/heartbeat/deregister/
+//      TTL lifecycle.
+//   2. The `family` module end-to-end against a REAL AgenticHub driven by an in-memory transport:
+//      a REGISTER frame creates a durable row; HEARTBEAT keeps it; DEREGISTER and disconnect remove
+//      it; teardown stops cleanly; a mount with no DataLayer is a safe no-op.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { AgenticHub } from "@nanobpm/agentic/channel";
+import type {
+  Authenticator,
+  ChannelConnection,
+  ChannelTransport,
+} from "@nanobpm/agentic/channel";
+import { encodeFrame, type Frame, type MessageFamily } from "@nanobpm/agentic/protocol";
+import type { SqliteDb } from "@nanobpm/agentic/presence";
+import type { DataLayer } from "@nanobpm/urban";
+import { assert, assertEquals } from "#test-assert";
+import { noopLog } from "../../../test/log.ts";
+import type { AgenticContext } from "../registry.ts";
+import {
+  createPresenceStore,
+  currentPresenceRegistry,
+  family,
+  openPresenceDb,
+  PresenceRegistry,
+} from "./presence.family.ts";
+
+// ── in-memory SQLite (the app's synchronous SqliteDb shape) ────────────────────────────────────
+
+function memSqlite(): SqliteDb {
+  const db = new DatabaseSync(":memory:");
+  return {
+    exec: (sql) => db.exec(sql),
+    run: (sql, params = []) => {
+      const r = db.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: Number(r.lastInsertRowid) };
+    },
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      db.prepare(sql).all(...(params as never[])) as T[],
+  };
+}
+
+/** A DataLayer whose default source exposes the given synchronous SqliteDb (nothing else is used). */
+function memData(db: SqliteDb): DataLayer {
+  return { source: () => ({ db }) } as unknown as DataLayer;
+}
+
+/** A mutable fake clock so TTL sweeps are deterministic. */
+function fakeClock(start = 1_000): { now(): number; advance(ms: number): void } {
+  let t = start;
+  return { now: () => t, advance: (ms) => { t += ms; } };
+}
+
+// ── PresenceRegistry over an in-memory DataLayer ───────────────────────────────────────────────
+
+test("snapshot: groups registered workers by leaf token with family/host", () => {
+  const store = createPresenceStore(memSqlite());
+  store.ensureSchema();
+  // Two workers under leaf token "leafA", one under "leafB".
+  store.register({ instance: "w2", connectionId: "c2", identity: "leafA", capability: { family: "kimi", host: "boxA2" } });
+  store.register({ instance: "w1", connectionId: "c1", identity: "leafA", capability: { family: "opus", host: "boxA1" } });
+  store.register({ instance: "w3", connectionId: "c3", identity: "leafB", capability: { family: "qwen", host: "boxB" } });
+
+  const registry = new PresenceRegistry(store, () => new Set(["c1", "c2", "c3"]));
+  const snap = registry.snapshot({ now: 2_000 });
+
+  assertEquals(snap.count, 3);
+  assertEquals(snap.leaves.map((l) => l.token), ["leafA", "leafB"], "leaves sorted by token");
+  const leafA = snap.leaves[0];
+  assertEquals(leafA.workers.map((w) => w.instance), ["w1", "w2"], "workers sorted by instance");
+  assertEquals(leafA.workers[0].family, "opus");
+  assertEquals(leafA.workers[0].host, "boxA1");
+  assertEquals(snap.leaves[1].workers[0].family, "qwen");
+  assertEquals(snap.workers.map((w) => w.instance), ["w1", "w2", "w3"], "flat list sorted");
+});
+
+test("snapshot: liveness reflects the open-connection set", () => {
+  const store = createPresenceStore(memSqlite());
+  store.ensureSchema();
+  store.register({ instance: "live", connectionId: "cLive", identity: "leaf", capability: {} });
+  store.register({ instance: "gone", connectionId: "cGone", identity: "leaf", capability: {} });
+
+  const registry = new PresenceRegistry(store, () => new Set(["cLive"]));
+  const byInstance = new Map(registry.snapshot().workers.map((w) => [w.instance, w]));
+  assertEquals(byInstance.get("live")?.live, true);
+  assertEquals(byInstance.get("gone")?.live, false);
+});
+
+test("snapshot: staleMs is measured from lastSeen and jobKeysFor seeds current jobKeys", () => {
+  const clock = fakeClock(5_000);
+  const store = createPresenceStore(memSqlite(), { clock });
+  store.ensureSchema();
+  store.register({ instance: "w1", connectionId: "c1", identity: "leaf", capability: {} });
+
+  const registry = new PresenceRegistry(store, () => new Set(["c1"]));
+  const snap = registry.snapshot({
+    now: 5_250,
+    jobKeysFor: (instance) => (instance === "w1" ? ["job-42", "job-43"] : []),
+  });
+  assertEquals(snap.workers[0].staleMs, 250);
+  assertEquals(snap.workers[0].jobKeys, ["job-42", "job-43"]);
+});
+
+test("snapshot: jobKeys default to none (presence carries no job attribution)", () => {
+  const store = createPresenceStore(memSqlite());
+  store.ensureSchema();
+  store.register({ instance: "w1", connectionId: "c1", identity: "leaf", capability: {} });
+  const registry = new PresenceRegistry(store, () => new Set(["c1"]));
+  assertEquals(registry.snapshot().workers[0].jobKeys, []);
+});
+
+test("registeredWorkers: returns the canonical {instance, capability} supply rows", () => {
+  const store = createPresenceStore(memSqlite());
+  store.ensureSchema();
+  store.register({ instance: "w1", connectionId: "c1", identity: "leaf", capability: { family: "opus", weight: 4.8, cognition: "deep" } });
+  const registry = new PresenceRegistry(store, () => new Set(["c1"]));
+  assertEquals(registry.registeredWorkers(), [
+    { instance: "w1", capability: { cognition: "deep", weight: 4.8, family: "opus" } },
+  ]);
+});
+
+test("reconcile: removes rows whose connection the hub has closed, keeps live ones", () => {
+  const store = createPresenceStore(memSqlite());
+  store.ensureSchema();
+  store.register({ instance: "keep", connectionId: "cLive", identity: "leaf", capability: {} });
+  store.register({ instance: "drop", connectionId: "cGone", identity: "leaf", capability: {} });
+
+  const registry = new PresenceRegistry(store, () => new Set(["cLive"]));
+  const removed = registry.reconcile();
+  assertEquals(removed, ["drop"]);
+  assertEquals(registry.count(), 1);
+  assertEquals(registry.snapshot().workers.map((w) => w.instance), ["keep"]);
+});
+
+test("lifecycle: register creates, heartbeat keeps live, deregister removes, TTL sweep ages out", () => {
+  const clock = fakeClock(0);
+  const store = createPresenceStore(memSqlite(), { ttlMs: 1_000, clock });
+  store.ensureSchema();
+  const registry = new PresenceRegistry(store, () => new Set(["c1", "c2"]));
+
+  store.register({ instance: "w1", connectionId: "c1", identity: "leaf", capability: {} });
+  assertEquals(registry.count(), 1);
+
+  // A heartbeat just before the TTL keeps the worker alive across the sweep.
+  clock.advance(900);
+  assert(store.heartbeat("w1", "leaf"), "heartbeat refreshes a registered instance");
+  clock.advance(900);
+  assertEquals(store.sweep().length, 0, "not stale — heartbeat kept it live");
+  assertEquals(registry.count(), 1);
+
+  // Without a further heartbeat it ages out past the TTL.
+  clock.advance(1_500);
+  assertEquals(store.sweep().map((r) => r.instance), ["w1"]);
+  assertEquals(registry.count(), 0);
+
+  // A graceful deregister removes a re-registered instance immediately.
+  store.register({ instance: "w2", connectionId: "c2", identity: "leaf", capability: {} });
+  assert(store.deregister("w2", "leaf"));
+  assertEquals(registry.count(), 0);
+});
+
+test("migration 023 provisions the exact table the store reads/writes", () => {
+  const db = memSqlite();
+  const sql = readFileSync(
+    join(fileURLToPath(new URL("../../../db/migrations/023_agentic_presence.sql", import.meta.url))),
+    "utf8",
+  );
+  db.exec(sql);
+  // A store that does NOT call ensureSchema still works against the migrated table.
+  const store = createPresenceStore(db);
+  store.register({ instance: "w1", connectionId: "c1", identity: "leaf", capability: { family: "opus", host: "box" } });
+  assertEquals(store.get("w1")?.capability.host, "box");
+});
+
+test("openPresenceDb: returns undefined when no DataLayer is mounted", () => {
+  assertEquals(openPresenceDb(undefined), undefined);
+});
+
+// ── family module against a real hub + in-memory transport ─────────────────────────────────────
+
+interface FakeConn {
+  readonly conn: ChannelConnection;
+  feed(frame: Frame): void;
+  disconnect(): void;
+}
+
+function fakeConn(id: string, identity: string): FakeConn {
+  let onMessage: ((bytes: Uint8Array) => void) | undefined;
+  let onClose: ((code?: number, reason?: string) => void) | undefined;
+  const conn: ChannelConnection = {
+    id,
+    handshake: { query: { identity }, token: "t", credential: "c" },
+    send: () => {},
+    close: (code, reason) => onClose?.(code, reason),
+    onMessage: (l) => { onMessage = l; },
+    onClose: (l) => { onClose = l; },
+  };
+  return {
+    conn,
+    feed: (frame) => onMessage?.(encodeFrame(frame)),
+    disconnect: () => onClose?.(),
+  };
+}
+
+function memTransport(): { transport: ChannelTransport; connect(conn: ChannelConnection): void } {
+  let onConnection: ((conn: ChannelConnection) => void) | undefined;
+  const transport: ChannelTransport = {
+    onConnection: (l) => { onConnection = l; },
+    address: { port: 0 },
+    close: async () => {},
+  };
+  return { transport, connect: (conn) => onConnection?.(conn) };
+}
+
+/** Authenticate every peer, deriving its identity (the leaf token) from the handshake query. */
+const authenticator: Authenticator = (req) => ({
+  ok: true,
+  grant: { identity: req.query?.identity ?? "anon" },
+});
+
+/** Flush the hub's microtasks (async auth + async frame routing) so assertions see the result. */
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+
+function registerFrame(instance: string, capability: Record<string, unknown>): Frame {
+  return { lane: "control", family: "register", seq: 1, payload: { instance, capability } };
+}
+function familyFrame(fam: MessageFamily, instance: string): Frame {
+  return { lane: "control", family: fam, seq: 1, payload: { instance } };
+}
+
+async function mountFamily(db: SqliteDb | undefined): Promise<{ hub: AgenticHub; transport: ReturnType<typeof memTransport> }> {
+  const transport = memTransport();
+  const hub = new AgenticHub({ transport: transport.transport, authenticator, sweepIntervalMs: 0 });
+  const ctx: AgenticContext = {
+    hub,
+    registry: hub.registry,
+    // The transport handle is not exercised by the presence family; the in-memory one stands in.
+    transport: transport.transport as never,
+    data: db ? memData(db) : undefined,
+    log: noopLog(),
+  };
+  await family.mount(ctx);
+  return { hub, transport };
+}
+
+test("family: mount attaches the three handlers and a REGISTER creates a durable presence row", async () => {
+  const { hub, transport } = await mountFamily(memSqlite());
+  try {
+    assertEquals(hub.router.families().sort(), ["deregister", "heartbeat", "register"]);
+
+    const peer = fakeConn("c1", "leafA");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(registerFrame("w1", { family: "opus", host: "boxA" }));
+    await flush();
+
+    const snap = currentPresenceRegistry()?.snapshot();
+    assert(snap, "registry is mounted");
+    assertEquals(snap.count, 1);
+    assertEquals(snap.leaves[0].token, "leafA");
+    assertEquals(snap.leaves[0].workers[0].family, "opus");
+    assertEquals(snap.leaves[0].workers[0].host, "boxA");
+    assertEquals(snap.leaves[0].workers[0].live, true, "connection is open");
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("family: HEARTBEAT keeps a worker and DEREGISTER removes it", async () => {
+  const { hub, transport } = await mountFamily(memSqlite());
+  try {
+    const peer = fakeConn("c1", "leaf");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(registerFrame("w1", {}));
+    await flush();
+    assertEquals(currentPresenceRegistry()?.count(), 1);
+
+    peer.feed(familyFrame("heartbeat", "w1"));
+    await flush();
+    assertEquals(currentPresenceRegistry()?.count(), 1, "heartbeat keeps the row");
+
+    peer.feed(familyFrame("deregister", "w1"));
+    await flush();
+    assertEquals(currentPresenceRegistry()?.count(), 0, "deregister removes the row");
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("family: a disconnect removes the worker via reconcile", async () => {
+  const { hub, transport } = await mountFamily(memSqlite());
+  try {
+    const peer = fakeConn("c1", "leaf");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(registerFrame("w1", {}));
+    await flush();
+    assertEquals(currentPresenceRegistry()?.count(), 1);
+
+    // Simulate the peer vanishing: the hub's own close listener drops it from the live registry.
+    peer.disconnect();
+    assertEquals(hub.connectionCount, 0, "hub no longer tracks the connection");
+
+    const removed = currentPresenceRegistry()?.reconcile();
+    assertEquals(removed, ["w1"]);
+    assertEquals(currentPresenceRegistry()?.count(), 0);
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("family: teardown stops the family and clears the current registry", async () => {
+  const { hub } = await mountFamily(memSqlite());
+  assert(currentPresenceRegistry(), "mounted");
+  family.teardown?.();
+  assertEquals(currentPresenceRegistry(), undefined, "cleared on teardown");
+  await hub.close();
+});
+
+test("family: mounting without a DataLayer is a safe no-op", async () => {
+  const { hub } = await mountFamily(undefined);
+  try {
+    assertEquals(currentPresenceRegistry(), undefined, "no registry without data");
+    // The three presence handlers are not attached when there is nothing to persist to.
+    assertEquals(hub.router.families(), []);
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});

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

@@ -0,0 +1,279 @@
+// nano-workforce — the agentic presence & registry family (ADR 0056, H1 / #144).
+//
+// A pluggable {@link AgenticFamily} that plugs into the H0 seam (`app/agentic/registry.ts`) with NO
+// edit to `main.ts`, `drainAndExit`, or any shared boot line — the loader discovers this file by its
+// `*.family.ts` suffix and the seam mounts it. It owns the channel's `register` / `heartbeat` /
+// `deregister` message families (attached through the hub's `registerFamilyHandler` seam, never a
+// shared dispatch switch) and layers a DURABLE supply registry over the app's SQLite DataLayer — the
+// same store the advisory blackboard uses; no separate database.
+//
+// What it gives the fleet:
+//   - REGISTER      → a durable presence row (instance + declared capability + connection + liveness).
+//   - HEARTBEAT     → refreshes the row's `last_seen` so a live worker stays visible.
+//   - DEREGISTER / disconnect / TTL timeout → removes the row (see the maintenance tick below).
+//   - {@link PresenceRegistry.snapshot} → the read-only SUPPLY mirror: connected workers grouped by
+//     leaf token, each with identity, family, host, liveness (and a seam for current jobKeys). This
+//     is the supply feed the enrolment epic (#152) reads and the cockpit (H5) renders.
+//
+// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+// is untouched — presence rides the agentic channel only; ADVISORY — the registry is a read-only
+// mirror and NEVER hard-locks or gates a BPMN sequence flow. Capability (cognition/weight/family/host)
+// is an ENROLMENT attribute, never a routing token.
+import {
+  attachPresenceFamily,
+  type PresenceFamilyHandle,
+  PresenceStore,
+  type PresenceStoreOptions,
+  type SqliteDb,
+} from "@nanobpm/agentic/presence";
+import type { DataLayer } from "@nanobpm/urban";
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+
+/** The message-family name this module owns (its three handlers are register/heartbeat/deregister). */
+export const PRESENCE_FAMILY = "presence";
+
+/** The maintenance tick runs at a third of the presence TTL — matching the hub/store sweep cadence. */
+const SWEEP_DIVISOR = 3;
+
+/** One worker in the supply mirror: a durable presence row projected for the cockpit/enrolment feed. */
+export interface SupplyWorker {
+  /** The worker instance id (`register.instance`). */
+  readonly instance: string;
+  /** The authenticated ADR 0028 principal — the leaf token this worker registered under. */
+  readonly identity: string;
+  /** Declared cognition (enrolment attribute), if any. */
+  readonly cognition?: string;
+  /** Declared cognition weight (enrolment attribute), if any. */
+  readonly weight?: number;
+  /** Declared family (enrolment attribute) — the diversity-SLO seat filler, if any. */
+  readonly family?: string;
+  /** Declared host (enrolment attribute) — where the worker runs, if any. */
+  readonly host?: string;
+  /** The channel connection the worker last registered on. */
+  readonly connectionId: string;
+  /** When the worker first registered, ISO-8601. */
+  readonly registeredAt: string;
+  /** Last liveness refresh (register/heartbeat), epoch ms. */
+  readonly lastSeen: number;
+  /** Whether the worker's connection is still open in the hub's live connection registry. */
+  readonly live: boolean;
+  /** How long since the last liveness refresh, in ms (0 when fresh). */
+  readonly staleMs: number;
+  /**
+   * The jobKeys this worker is currently processing. Presence carries no job attribution of its own,
+   * so this is populated from the injected {@link SnapshotOptions.jobKeysFor} resolver — the seam the
+   * relay/correlation slice (H6) wires; it is `[]` until then.
+   */
+  readonly jobKeys: readonly string[];
+}
+
+/** The supply for one leaf token: the workers registered under it. */
+export interface SupplyLeaf {
+  /** The leaf token — the ADR 0028 identity principal. (Refined to SERVE tokens when vocab #152 lands.) */
+  readonly token: string;
+  /** The workers registered under this leaf token, sorted by instance. */
+  readonly workers: readonly SupplyWorker[];
+}
+
+/** The read-only supply snapshot: the live registry grouped by leaf token, plus a flat worker list. */
+export interface PresenceSnapshot {
+  /** Supply grouped by leaf token, sorted by token. */
+  readonly leaves: readonly SupplyLeaf[];
+  /** Every registered worker, flat, sorted by instance. */
+  readonly workers: readonly SupplyWorker[];
+  /** The number of registered workers. */
+  readonly count: number;
+}
+
+/** The canonical supply-row shape the enrolment epic (#152) resolves against the vocab. */
+export interface RegisteredWorker {
+  readonly instance: string;
+  readonly capability: {
+    readonly cognition?: string;
+    readonly weight?: number;
+    readonly family?: string;
+    readonly host?: string;
+  };
+}
+
+/** Options for {@link PresenceRegistry.snapshot}. */
+export interface SnapshotOptions {
+  /** "Now" in epoch ms for the `staleMs` computation. Defaults to `Date.now()`. */
+  readonly now?: number;
+  /** Resolve the current jobKeys for a worker instance. Defaults to none (presence has no jobs). */
+  readonly jobKeysFor?: (instance: string) => readonly string[];
+}
+
+/**
+ * The durable presence registry: a read-only projection over the {@link PresenceStore}, cross-checked
+ * against the set of currently-open hub connections for liveness. It NEVER gates control flow — it is
+ * the supply mirror the enrolment epic and the cockpit read.
+ */
+export class PresenceRegistry {
+  readonly #store: PresenceStore;
+  readonly #liveConnectionIds: () => Set<string>;
+
+  constructor(store: PresenceStore, liveConnectionIds: () => Set<string>) {
+    this.#store = store;
+    this.#liveConnectionIds = liveConnectionIds;
+  }
+
+  /** The presence liveness TTL in ms. */
+  get ttlMs(): number {
+    return this.#store.ttlMs;
+  }
+
+  /** The number of registered workers. */
+  count(): number {
+    return this.#store.count();
+  }
+
+  /** The canonical supply rows (`{ instance, capability }`) the enrolment epic (#152) consumes. */
+  registeredWorkers(): RegisteredWorker[] {
+    return this.#store.list().map((row) => ({ instance: row.instance, capability: { ...row.capability } }));
+  }
+
+  /**
+   * Eagerly drop presence rows whose connection the hub has already closed (a disconnect the hub's
+   * single close listener removed from its in-memory registry). Rows also age out on the presence
+   * TTL via {@link PresenceStore.sweep}; this is the eager disconnect path. Returns the removed
+   * instance ids.
+   */
+  reconcile(): string[] {
+    const live = this.#liveConnectionIds();
+    const deadConnections = new Set<string>();
+    for (const row of this.#store.list()) {
+      if (!live.has(row.connectionId)) deadConnections.add(row.connectionId);
+    }
+    const removed: string[] = [];
+    for (const connectionId of deadConnections) {
+      removed.push(...this.#store.removeByConnection(connectionId));
+    }
+    return removed;
+  }
+
+  /** The read-only supply snapshot: connected workers grouped by leaf token, with family/host/liveness. */
+  snapshot(options: SnapshotOptions = {}): PresenceSnapshot {
+    const now = options.now ?? Date.now();
+    const jobKeysFor = options.jobKeysFor ?? (() => []);
+    const live = this.#liveConnectionIds();
+    const workers: SupplyWorker[] = this.#store.list().map((row) => ({
+      instance: row.instance,
+      identity: row.identity,
+      cognition: row.capability.cognition,
+      weight: row.capability.weight,
+      family: row.capability.family,
+      host: row.capability.host,
+      connectionId: row.connectionId,
+      registeredAt: row.registeredAt,
+      lastSeen: row.lastSeen,
+      live: live.has(row.connectionId),
+      staleMs: Math.max(0, now - row.lastSeen),
+      jobKeys: [...jobKeysFor(row.instance)],
+    }));
+
+    const byToken = new Map<string, SupplyWorker[]>();
+    for (const worker of workers) {
+      const bucket = byToken.get(worker.identity);
+      if (bucket) bucket.push(worker);
+      else byToken.set(worker.identity, [worker]);
+    }
+    const byInstance = (a: SupplyWorker, b: SupplyWorker) => a.instance.localeCompare(b.instance);
+    const leaves: SupplyLeaf[] = [...byToken.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([token, ws]) => ({ token, workers: ws.slice().sort(byInstance) }));
+
+    return { leaves, workers: workers.slice().sort(byInstance), count: workers.length };
+  }
+}
+
+/** Open the app's synchronous SQLite handle from the DataLayer, or undefined when data isn't mounted. */
+export function openPresenceDb(data: DataLayer | undefined): SqliteDb | undefined {
+  if (!data) return undefined;
+  return data.source().db;
+}
+
+/** The live registry from the most recent mount, so the cockpit/report (H5) can read the supply feed. */
+let currentRegistry: PresenceRegistry | undefined;
+
+/** The mounted presence registry (the supply feed), or undefined before mount / after teardown. */
+export function currentPresenceRegistry(): PresenceRegistry | undefined {
+  return currentRegistry;
+}
+
+interface MountState {
+  readonly registry: PresenceRegistry;
+  readonly handle: PresenceFamilyHandle;
+  readonly timer: ReturnType<typeof setInterval> | undefined;
+}
+
+let state: MountState | undefined;
+
+/** Build the presence store; exported so tests can inject a fake clock / TTL over an in-memory db. */
+export function createPresenceStore(db: SqliteDb, options?: PresenceStoreOptions): PresenceStore {
+  return new PresenceStore(db, options);
+}
+
+/**
+ * The presence family module. `mount` attaches register/heartbeat/deregister to the hub, applies the
+ * schema, and starts ONE canonical maintenance tick that both ages out on the presence TTL and drops
+ * rows for disconnected connections. `teardown` stops the tick and the presence sweep.
+ */
+export const family: AgenticFamily = {
+  name: PRESENCE_FAMILY,
+
+  mount(ctx: AgenticContext): void {
+    const db = openPresenceDb(ctx.data);
+    if (!db) {
+      ctx.log.warn("agentic presence: no data layer mounted — presence registry disabled");
+      return;
+    }
+    const store = createPresenceStore(db);
+    store.ensureSchema();
+
+    const liveConnectionIds = () => new Set(ctx.hub.registry.list().map((conn) => conn.id));
+    const registry = new PresenceRegistry(store, liveConnectionIds);
+
+    // Attach the three presence handlers via the S1 seam. Disable the package's own TTL timer
+    // (`sweepIntervalMs: 0`) so this module runs a SINGLE maintenance loop rather than two — the
+    // canonical presence-maintenance pass, not a second poller (derivation over duplication).
+    const handle = attachPresenceFamily(ctx.hub, store, {
+      sweepIntervalMs: 0,
+      onError: (err, connectionId) =>
+        ctx.log.warn("agentic presence fault", { connectionId, err: String(err) }),
+    });
+
+    const interval = Math.max(1, Math.floor(store.ttlMs / SWEEP_DIVISOR));
+    const tick = () => {
+      // TTL age-out (silent-worker liveness timeout) + eager disconnect cleanup, on one cadence.
+      handle.sweepNow();
+      try {
+        registry.reconcile();
+      } catch (err) {
+        ctx.log.warn("agentic presence reconcile failed", { err: String(err) });
+      }
+    };
+    // Run one maintenance pass eagerly at mount so the registry is correct immediately: the
+    // presence table is durable across restarts, so without this first sweep/reconcile
+    // `registeredWorkers()` / `snapshot()` could briefly surface stale rows from a previous run
+    // (all connections start closed) until the first interval tick fires.
+    tick();
+    const timer = interval > 0 ? setInterval(tick, interval) : undefined;
+    // Never keep the process alive for the presence sweep alone.
+    timer?.unref?.();
+
+    state = { registry, handle, timer };
+    currentRegistry = registry;
+    ctx.log.info("agentic presence mounted", { family: PRESENCE_FAMILY, ttlMs: store.ttlMs });
+  },
+
+  teardown(): void {
+    if (!state) return;
+    if (state.timer !== undefined) clearInterval(state.timer);
+    state.handle.stop();
+    state = undefined;
+    currentRegistry = undefined;
+  },
+};
+
+export default family;