@nanobpm/nano-workforce 0.51.0 → 0.52.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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;

package/db/migrations/023_agentic_presence.sql

@@ -0,0 +1,30 @@
+-- Agentic visibility plane — presence & registry (ADR 0056, H1 / #144).
+--
+-- The durable supply mirror behind the agentic channel's presence family. A worker that opens the
+-- channel and sends `register` lands one row here (keyed by its instance id) carrying its declared
+-- enrolment capability (cognition/weight/family/host — an ENROLMENT attribute, NEVER a routing
+-- token), the connection it registered on, and its own heartbeat-refreshed `last_seen` liveness.
+-- Heartbeats refresh `last_seen`; `deregister`, an observed disconnect, or the presence-TTL sweep
+-- remove the row. This is the read-only supply feed the enrolment epic (#152) reads — it is advisory
+-- and NEVER gates a BPMN sequence flow.
+--
+-- The very same DDL is the single source of truth the runtime's `PresenceStore` applies through
+-- `ensureSchema()` (@nanobpm/agentic/presence, `PRESENCE_SCHEMA_SQL`). Keeping the two application
+-- paths (this boot migration and the store's guard) statement-for-statement identical is what stops
+-- a production/boot schema drift. Forward-only and additive: `CREATE ... IF NOT EXISTS` only.
+--
+-- This is the reserved prefix H0 pre-allocated for H1 (023) so parallel wave-1 siblings never
+-- independently grab "the next" migration number (H3 → 024_agentic_transcript, H4 → 025_agentic_blackboard).
+CREATE TABLE IF NOT EXISTS agentic_presence (
+  instance      TEXT PRIMARY KEY,
+  connection_id TEXT NOT NULL,
+  identity      TEXT NOT NULL,
+  cognition     TEXT,
+  weight        REAL,
+  family        TEXT,
+  host          TEXT,
+  registered_at TEXT NOT NULL,
+  last_seen     INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_agentic_presence_last_seen ON agentic_presence (last_seen);
+CREATE INDEX IF NOT EXISTS idx_agentic_presence_connection ON agentic_presence (connection_id);

package/docs/adr/0002-escalations-are-user-tasks-and-forms.md

@@ -0,0 +1,167 @@
+# ADR 0002 — Escalations are user tasks + forms
+
+Status: **Proposed.**
+Date: 2026-08-13.
+
+> **Scope note.** This is a **nano-workforce-local** ADR — it governs how *this app's* agent workforce
+> models human (and agent) decision points. Platform-wide ADRs live in `Magikcraft/nano-bpm/docs/adr`
+> (referenced by number + repo, e.g. "nano-bpm ADR 0026"). nano-workforce's own series continues here
+> after ADR 0001.
+
+Relates to:
+nano-bpm **ADR 0026** (Urban human surfaces + run model — the `taskInbox` surface this ADR builds on:
+a hosted task list backed by the engine's user-task search that renders a linked `.form` and posts
+completion),
+nano-bpm **ADR 0037** (execution + task listeners — the user-task lifecycle hooks this ADR leans on),
+nano-bpm **ADR 0046** (agent-as-worker vs agent-in-the-node — the duality that lets an **agent** be a
+task assignee, answering the same form a human would),
+nano-bpm **ADR 0051** (nano-workforce — the crew orchestrator whose escalations this reshapes),
+nano-bpm **ADR 0056** (the Nano agentic protocol — this ADR is the **durable** human-in-the-loop lane,
+complementary to that ADR's **ephemeral** live-steering cockpit),
+nano-workforce **ADR 0001** (this repo's ADR series),
+and the current bespoke escalation subsystem in this repo: `app/plan.ts` (`plan_escalations`,
+`plan_review_escalations`, `answerTaskEscalation`, `answerPlanEscalation`, `refreshOpenTaskEscalation`),
+`app/service.ts` (the `open_escalation_*` pointer on `pull_requests`), the `pr.persist-*-escalation`
+service workers, and the `feature-escalation-answered` / `plan-escalation-answered` resume messages in
+`resources/processes/plan-fanout.bpmn`.
+
+## Context
+
+When a fanned-out agent task cannot proceed on its own — an open question, a trial-merge conflict, a
+plan-review budget cap, a stuck PR-review loop — nano-workforce **escalates**: it parks the process and
+waits for a human decision. Today that is a hand-rolled subsystem, and the same shape recurs three times:
+
+1. **Task escalation** (`plan_escalations`, issue #25) — a fanned-out task's open question. In
+   `plan-fanout.bpmn`: an `exclusiveGateway` (`escalated?`) routes to a **service task**
+   `persist-task-escalation` (`pr.persist-task-escalation`) which writes the row + a denormalised
+   `open_task_escalation_id` pointer on the plan, then an **intermediate message-catch**
+   `wait-feature-answer` parks on `feature-escalation-answered` (correlationKey `=escalationCorrKey`).
+2. **Plan-review escalation** (`plan_review_escalations`) — a plan-review cap; a human returns a
+   `proceed | revise` directive. Same persist-service-task → message-catch shape
+   (`plan-escalation-answered`); the table is **append-only** and the review **epoch** is derived from
+   the count of answered rows.
+3. **PR review-loop escalation** (`open_escalation_*` columns on `pull_requests`, #597/#599) — a review
+   convergence that will not settle; surfaced via denormalised columns on the PR row.
+
+Answering, in every case, means: an app worker records the answer, **mirrors** it onto the task/PR row,
+**publishes the resume message**, and **re-surfaces** the next open escalation by rewriting a denormalised
+"oldest open" pointer. The "form" is a bespoke Urban page that fires when a pointer is set and prints the
+free-text `question`; the answer is a free-text string.
+
+This is a **user task + form, re-implemented by hand** — and the bug tail proves it. Every incident is a
+denormalised-pointer or free-text-contract failure: stale rows resurfacing a *dead* form after a re-plan
+(`refreshOpenTaskEscalation`), the "addressed-escalation paradox," `blank question fabricates an
+answerable escalation` (a hack to avoid an incident on an empty question), and per-run one-by-one row
+cleanup. None of these can occur under a single-source-of-truth user-task lifecycle.
+
+Crucially, **the primitives already exist**:
+
+- The engine has **native user tasks** — `UserTaskProps`, `Command::CompleteUserTask` / `UpdateUserTask`,
+  task listeners (ADR 0037), and `zeebe:assignmentDefinition` / priority / schedule parsed off the
+  `userTask` element (`engine-core/src/bpmn.rs`, `model.rs`).
+- Urban ships the **`taskInbox` surface** (ADR 0026): `GET /tasks` (list), `GET /tasks/api/tasks`
+  (`engine.searchUserTasks`), `POST /tasks/api/complete` (`engine.completeUserTask(key, variables)`),
+  rendering the linked **`.form`**. It is manifest-enabled (`surfaces.taskInbox`) and unused by nwf today.
+- Forms are `.form` assets; the Urban **form editor** (the "Delphi" authoring surface) is the tool that
+  authors them. This ADR is that editor's **first real internal customer**.
+
+## Decision
+
+**Model every decision-required escalation in nano-workforce as a native BPMN `userTask` with a linked
+`.form`, surfaced through Urban's `taskInbox`, completed with typed variables that resume the process.**
+Retire the bespoke `persist-escalation` service task → message-catch → resume-publish → denormalised-pointer
+machinery.
+
+### 1. A tiered taxonomy — not everything is a task
+
+The current code conflates three tiers; draw the line explicitly at each raise site:
+
+| Tier | Example | Mechanism |
+| --- | --- | --- |
+| **Transient** | empty-status backstop, re-request a review, a retriable step | stays **in-process** (retry / default arm) — **no task** |
+| **Advisory** | a hint, a note for the next agent | the **blackboard** (`app/blackboard.ts`) — never gates a flow |
+| **Decision-required** | proceed/revise, answer an open question, resolve a conflict, abandon | **user task + form** |
+
+Only the third tier becomes a user task. This retires the "fabricate a blank answerable escalation" hack:
+an empty question is a *non-escalation*, not a task.
+
+### 2. `serviceTask(persist) + message-catch(wait)` → one `userTask`
+
+Each `persist-*-escalation` service task and its paired intermediate message-catch collapse into a single
+`userTask` bearing a `zeebe:formDefinition` (linked `.form`) and a `zeebe:assignmentDefinition`. The engine
+owns the wait, the correlation, and the work-item state — so `escalationCorrKey`, the
+`feature-escalation-answered` / `plan-escalation-answered` messages, and the `pr.persist-*-escalation`
+workers are deleted. Completing the task carries typed variables straight back into the process.
+
+### 3. Forms are the typed escalation contract
+
+Each escalation kind gets a `.form` whose schema *is* its interface — replacing free-text question/answer:
+
+- **Task escalation** → `{ resolution: "answer" | "abandon", answer?: string }`.
+- **Plan-review escalation** → `{ directive: "proceed" | "revise", notes?: string }` — deleting the
+  hand-rolled `parsePlanEscalationDirective`; the enum + required-field validation live in the form/FEEL.
+- **Trial-merge escalation** → `{ action: "proceed" | "rebase" | "abandon", notes?: string }`.
+- **PR review-loop escalation** → `{ answer: string }` (or a kind-specific action enum).
+
+### 4. One queryable task list replaces three denormalised pointers
+
+`open_task_escalation_id`, `open_plan_escalation_id`, and the `open_escalation_*` columns on
+`pull_requests` all collapse into `engine.searchUserTasks(...)` — filterable by assignee, candidate group,
+process instance, element, age. There is **no "surfaced" field to go stale**, so the resurface / dead-form
+bug class is eliminated at the root. The plans page and any inbox read the live task search; the
+`inbox_entries` seed is the natural home for the cross-plan view.
+
+### 5. The assignee may be a human **or** an agent
+
+`zeebe:assignmentDefinition` routes a task to a specific human, a **candidate group** (e.g. the operator /
+crew leads), or — per ADR 0046 — an **agent**. An LLM worker can complete the *same* form a human would,
+via the `chat`/agent surface or a job-worker-style completer. This makes "auto-resolve with a
+slower/smarter model, else route to a human" a single lifecycle with one contract — something the bespoke
+subsystem cannot express. Agent-answered completion is still a first-class, audited task completion.
+
+### 6. SLA via a timer boundary
+
+A user task carries a due date; a **timer boundary event** provides escalation-of-the-escalation —
+reassign, notify, or auto-proceed on a default — the durable replacement for the review poller's ad-hoc
+nudge. A decision no longer hangs forever with no deadline.
+
+### 7. Audit trail from user-task history
+
+`plan_review_escalations` is append-only because the **review epoch** = count of answered plan-review
+escalations. Under this ADR the epoch is derived from **completed plan-review user tasks** (native user-task
+history / completion events), so the dedicated audit table is retired without losing the audit.
+
+## Consequences
+
+- **A whole bug class disappears.** No denormalised "surfaced" pointer ⇒ no stale/dead-form resurfacing, no
+  addressed-escalation paradox, no blank-question fabrication. The engine's single-source-of-truth
+  user-task lifecycle replaces three hand-maintained mirrors.
+- **Less code.** Delete `pr.persist-*-escalation` workers, the two resume messages + their catch events,
+  `escalationCorrKey`, `answerTaskEscalation`/`answerPlanEscalation`/`refreshOpenTaskEscalation`, the
+  denormalised columns, and the bespoke answer page — replaced by `userTask` nodes + `.form`s + the
+  existing `taskInbox` surface.
+- **Dogfoods the Delphi vision.** nwf becomes the first real consumer of the Urban form editor + user-task
+  inbox, exercising forms end to end on a live app.
+- **The third human-in-the-loop lane.** Enrolment (#152) = what work exists; visibility (#142) =
+  watch/nudge a *live* agent (ephemeral); **escalation-as-user-task** = decide *durably* when blocked. The
+  cockpit can list a worker's open escalation tasks; the two planes reinforce each other.
+- **Migration is a real refactor, not a rename.** The bespoke tables encode edge cases (epoch-from-count,
+  re-plan cleanup, trial-merge "proceed" override). The migration must preserve those semantics on the new
+  substrate and run behind tests, phased kind-by-kind.
+- **New dependency on engine user-task depth.** Assignment, candidate groups, task listeners, and timer
+  boundaries on user tasks must be exercised (some may surface gaps to file against the engine). Form
+  rendering richness is bounded by the `taskInbox`/form-editor state of the art.
+
+## Open questions
+
+- **Form-rendering fidelity.** The current `taskInbox` page is minimal (lists key/element). How rich a
+  `.form` render is needed before the answer page can be deleted — and is that the form editor's job or a
+  `taskInbox` upgrade (an nano-ide concern)?
+- **Agent-answer policy (§5).** When may an agent auto-complete vs must-route-to-human — a per-kind policy,
+  a confidence gate, or an operator toggle? How is an agent completion attributed and reversible?
+- **Assignment model.** Candidate group vs named assignee for each kind; where the operator's routing
+  preference is persisted (manifest vs app state).
+- **Cross-plan inbox surface.** Does nwf embed `taskInbox` directly, or render its own plan-aware inbox
+  page over `searchUserTasks` (matching the existing plans page), keyed through `inbox_entries`?
+- **Back-compat window.** Do in-flight escalations at migration time drain on the old path, or are they
+  re-issued as user tasks? (Prefer drain-old, issue-new, per kind.)

package/docs/adr/0003-epic-base-branch-admission.md

@@ -0,0 +1,123 @@
+# ADR 0003 — Epic base-branch admission: explicit, auto-created, and guarded
+
+Status: **Proposed.**
+Date: 2026-08-13.
+
+> **Scope note.** A **nano-workforce-local** ADR — it governs how *this app* admits an epic for
+> execution. Platform-wide ADRs live in `Magikcraft/nano-bpm/docs/adr` (referenced by number + repo).
+> Continues nano-workforce's series after ADR 0001 (ADR 0002 is planned but not yet written; see below).
+
+Relates to:
+nano-workforce **ADR 0001** (cross-repo epics + integration branches — this ADR hardens *how* an epic's
+integration branch is chosen, created, and protected),
+nano-workforce **ADR 0002** *(planned — not yet written in this repo; escalations as user tasks)*: the
+confirm / shared-base gates are human decisions that *could* later surface as user tasks; see Open questions,
+nano-bpm **ADR 0058** (the OpenAPI endpoint surface — `startPlanFanout` is a spec operation whose request
+schema this ADR changes),
+migration `019_plan_base_branch.sql` (the `plans.base_branch` column, whose example is `epic/agent-protocol`),
+and in this repo: `operations/startPlanFanout.ts` (the launch operation), `app/plan.ts`
+(`startPlan`, `normalizeBaseBranch`, `renderBaseBranchBrief`, `PLAN_TERMINAL_STATUSES`), `app/baseGuard.ts`
++ `app/github.ts` (`baseBranchLanded`, `fetchDefaultBranch`), and `resources/processes/plan-fanout.bpmn`.
+
+## Context
+
+An epic is launched through the `startPlanFanout` operation, which calls `startPlan(data, engine, parsed,
+baseBranch)`. The `base_branch` (migration 019) tells every fanned-out task agent to branch off it and open
+its PR against it (`renderBaseBranchBrief`), landing the whole epic on a long-lived integration branch that
+reaches the default branch — and any merge-to-default side effect such as auto-publishing — only when the
+integration branch is deliberately merged.
+
+Four gaps make this a footgun surface:
+
+1. **Implicit default.** `normalizeBaseBranch` maps a blank/absent value to `null`, silently meaning "target
+   the repository default branch." An operator who *meant* to name an integration branch but omitted it
+   lands every task straight onto the default branch (e.g. `main`) with **no integration buffer** — and
+   any merge-to-default side effect fires per task.
+2. **No branch creation.** Nothing creates the integration branch. `baseGuard`/`baseBranchLanded` only
+   *read* (`gh pr list`, `fetchPrBase`, `fetchDefaultBranch`). So if the named branch doesn't exist, the
+   **first task's** `git fetch origin <branch>` / `gh pr create --base <branch>` fails — a late, per-task
+   failure instead of a clean admission error.
+3. **No typo guard.** A mistyped branch name is indistinguishable from an intended new one; without
+   creation it fails late, and *with* naive creation it would silently spawn a wrong-rooted branch.
+4. **No collision guard.** Two in-flight epics can target the **same** integration branch, interleaving
+   commits and poisoning each other's base — with no warning.
+
+The pieces to fix this already exist: `fetchDefaultBranch` (default-branch identity), `PLAN_TERMINAL_STATUSES`
+(`done|failed|abandoned` → the complement is "active"), a strict `isPlausibleBranchName` allowlist, and the
+`019` example convention `epic/*`.
+
+## Decision
+
+**Every epic launch must state its base branch explicitly, and `startPlanFanout` admits it through one
+fail-fast gate** — `admitPlan(...)` — run before any task fans out, backed by a durable `ensure-base-branch`
+head step in `plan-fanout.bpmn`. The gate has four ordered rules:
+
+### 1. Required + explicit — no implicit default
+
+`baseBranch` becomes a **required** field of `StartPlanFanoutRequest`. `normalizeBaseBranch` **rejects** a
+blank/absent value (`MissingBaseBranchError` → HTTP 400) instead of returning `null`. "Land on the default
+branch" is now a **conscious, named, confirmed** choice (rule 3), never a silent fallback. The
+`base_branch == null ? default : brief` fork in the launch/prompt path is removed; `renderBaseBranchBrief`
+is always rendered. (`plans.base_branch` stays nullable in the DB **only** to grandfather pre-migration
+rows; new launches always set it.)
+
+### 2. Create-if-missing, idempotently — with an `epic/*` guard
+
+`ensureBaseBranch(repo, branch, token)`:
+- **Exists** → no-op (never reset — a reset would nuke in-flight task PRs stacked on it; a stacked epic's
+  base already exists and is left alone).
+- **Missing and matches `epic/*`** → create `refs/heads/<branch>` off the **default branch HEAD**.
+- **Missing and *not* `epic/*`** → **reject** (`BaseBranchMustExistError`): a non-`epic/*` branch must
+  already exist, so a typo can't silently spawn a wrong-rooted branch. (`epic/*` is the `019` convention.)
+
+Runs at admission (fail fast) **and** as a head `ensure-base-branch` service task in `plan-fanout.bpmn` so
+it is durable + retriable even on a re-plan.
+
+### 3. Confirm-default — naming the default branch is deliberate
+
+If the explicit target **equals the repository default** (via `fetchDefaultBranch`), admission requires an
+explicit `confirmDefaultBase: true`, else **reject** (`DefaultBaseNotConfirmedError` → 400) with a message
+spelling out the consequence ("every task lands directly on `<default>` with no integration branch; any
+merge-to-default side effect fires per task"). This is the single guardrail on the one dangerous explicit
+value.
+
+### 4. Shared-base guard — one integration branch, one epic
+
+If another plan whose `status ∉ PLAN_TERMINAL_STATUSES` (i.e. **active**) targets the **same repo + same
+base branch**, admission **rejects** (`SharedBaseError` → 409) unless `allowSharedBase: true`. **Exempt: the
+default branch** — many epics target the default concurrently and don't collide (each task PR is
+independent). The guard fires only for a **shared custom integration branch**, the genuinely dangerous case.
+
+### Recommended defaults (confirm before build)
+
+- **Hard-require flags**, not soft warnings, for rules 3 and 4: a warning in a headless submit flow is
+  ignorable; a required `confirmDefaultBase` / `allowSharedBase` is a "warn you can't skip."
+- **`epic/*` auto-create guard** (rule 2): auto-create only `epic/*`; any other non-existent name is a
+  400. Matches the `019` convention.
+
+## Consequences
+
+- **A footgun class disappears:** no silent land-on-main, no first-task-fails-on-missing-branch, no typo'd
+  wrong-rooted branch, no two-epics-one-branch interleave — all become clean admission errors.
+- **Breaking API + launch-path change.** `StartPlanFanoutRequest.baseBranch` is now required; any
+  fire-and-forget caller/CLI/epic template that omitted it will (intentionally) 400. The OpenAPI spec +
+  generated types (`nano-generated/api-io.d.ts`, controller) regenerate; the submit surface + docs update.
+- **Back-compat:** pre-migration / in-flight `base_branch = null` plans are **grandfathered** (the column
+  stays nullable; the required-ness is enforced at *admission* of new launches, not by a DB `NOT NULL`).
+- **New write permission exercised:** ref creation (already held by the token that pushes task branches).
+- **Ties into ADR 0001/0002:** this is the admission half of the integration-branch story (0001), and its
+  human gates could later be modeled as user tasks (planned ADR 0002) rather than flags — see Open questions.
+
+## Open questions
+
+- **Gates as user tasks (planned ADR 0002)?** Should `confirmDefaultBase` / shared-base become an inbox **user
+  task** ("Epic X wants to target `main` / share `epic/y` — approve?") instead of a submit-time flag? For
+  *pre-fan-out* admission a synchronous flag is simpler and fail-fast; a user task fits only if we want a
+  human in the launch loop. Deferred.
+- **Auto-create root.** Always off default HEAD — correct for a fresh integration branch. Should a stacked
+  epic be able to declare `stackOn: <branch>` so its base is auto-created off *another* epic's branch
+  rather than default? (Today: that base must pre-exist.)
+- **Convention scope.** Is `epic/*` the only auto-createable prefix, or should the app config own the
+  allowlist?
+- **Grandfathered nulls.** Leave historical `null` rows as-is, or backfill them to the (then-current)
+  default branch for a uniform read model?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.51.0",
+  "version": "0.52.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",