@nanobpm/nano-workforce 0.191.1 → 0.193.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.193.0](https://github.com/nanobpm/nano-workforce/compare/v0.192.0...v0.193.0) (2026-09-28)
+
+### Features
+
+* **agentic:** record harnessProtocol from the presence channel ([#821](https://github.com/nanobpm/nano-workforce/issues/821)) ([304b241](https://github.com/nanobpm/nano-workforce/commit/304b241f8b875bd9eca18da102090b0256b7ead7)), closes [#802](https://github.com/nanobpm/nano-workforce/issues/802) [jwulf/c8ctl-plugin-nano#272](https://github.com/jwulf/c8ctl-plugin-nano/issues/272) [#820](https://github.com/nanobpm/nano-workforce/issues/820)
+
+## [0.192.0](https://github.com/nanobpm/nano-workforce/compare/v0.191.1...v0.192.0) (2026-09-28)
+
+### Features
+
+* **world:** self-heal a no-advance round onto a reachable push-checkpoint ([#819](https://github.com/nanobpm/nano-workforce/issues/819)) ([891add2](https://github.com/nanobpm/nano-workforce/commit/891add2a217042dd2abaa37c8f12b1f1877c89fc)), closes [26/#28](https://github.com/26/nano-workforce/issues/28) [#818](https://github.com/nanobpm/nano-workforce/issues/818) [#818](https://github.com/nanobpm/nano-workforce/issues/818) [#818](https://github.com/nanobpm/nano-workforce/issues/818) [704/#497](https://github.com/704/nano-workforce/issues/497)
+
 ## [0.191.1](https://github.com/nanobpm/nano-workforce/compare/v0.191.0...v0.191.1) (2026-09-26)
 
 ### Bug Fixes

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

@@ -11,6 +11,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { test } from "node:test";
+import { mock } from "node:test";
 import { fileURLToPath } from "node:url";
 import { AgenticHub } from "@nanobpm/agentic/channel";
 import type {
@@ -22,6 +23,8 @@ import { encodeFrame, type Frame, type MessageFamily } from "@nanobpm/agentic/pr
 import type { SqliteDb } from "@nanobpm/agentic/presence";
 import type { DataLayer } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
+import { assessWorkers } from "../../harnessProtocol.ts";
+import { memDataFor } from "../../../test/worldDb.ts";
 import { noopLog } from "../../../test/log.ts";
 import type { AgenticContext } from "../registry.ts";
 import {
@@ -47,11 +50,6 @@ function memSqlite(): SqliteDb {
   };
 }
 
-/** 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;
@@ -275,7 +273,72 @@ 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> }> {
+/** A full in-memory DataLayer for the presence family: the synchronous `source().db` handle the
+ * presence store uses PLUS the `table()`/`open()` surface the harness-protocol registry writes
+ * through (#820), all over ONE real SQLite db with the `worker_harness_protocol` migration applied. */
+function memMountData(): DataLayer {
+  const { data, db } = memDataFor(["107_worker_harness_protocol.sql"]);
+  const sqlite: SqliteDb = {
+    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[],
+  };
+  return { ...(data as unknown as Record<string, unknown>), source: () => ({ db: sqlite }) } as unknown as DataLayer;
+}
+
+/** Wrap a DataLayer so every `harness_protocol` value written through the registry's `table` seam is
+ * appended to `writes`, in order. Lets a test observe WHICH register frames actually recorded — a
+ * concurrent rejected frame that (wrongly) records surfaces as an extra `null` write, independent of
+ * which write happens to land last. */
+function withProtocolWriteSpy(data: DataLayer): { data: DataLayer; writes: Array<number | null> } {
+  const writes: Array<number | null> = [];
+  const realTable = (data as unknown as { table: (name: string, key: string) => unknown }).table.bind(data);
+  const wrapped = {
+    ...(data as unknown as Record<string, unknown>),
+    table: (name: string, key: string) => {
+      const t = realTable(name, key) as Record<string, (...a: unknown[]) => unknown>;
+      if (name !== "worker_harness_protocol") return t;
+      const note = (v: unknown) => writes.push(typeof v === "number" ? v : null);
+      return {
+        ...t,
+        insert: (row: Record<string, unknown>) => { note(row.harness_protocol); return t.insert(row); },
+        update: (k: unknown, patch: Record<string, unknown>) => { note(patch.harness_protocol); return t.update(k, patch); },
+      };
+    },
+  };
+  return { data: wrapped as unknown as DataLayer, writes };
+}
+
+/** Wrap a DataLayer so the registry's `update` of `worker_harness_protocol` to a specific protocol
+ * value is deferred by one MACROTASK (`setTimeout(0)`). The in-memory gateway resolves its reads/writes
+ * on microtasks, so a macrotask deterministically lands AFTER a concurrent frame's whole write —
+ * letting a test force an OLDER accepted re-register's write to complete last, the exact out-of-order
+ * hazard the per-instance serialization guards against. */
+function withDelayedProtocolUpdate(data: DataLayer, delayValue: number): DataLayer {
+  const realTable = (data as unknown as { table: (name: string, key: string) => unknown }).table.bind(data);
+  return {
+    ...(data as unknown as Record<string, unknown>),
+    table: (name: string, key: string) => {
+      const t = realTable(name, key) as Record<string, (...a: unknown[]) => unknown>;
+      if (name !== "worker_harness_protocol") return t;
+      return {
+        ...t,
+        update: async (k: unknown, patch: Record<string, unknown>) => {
+          if (Number(patch.harness_protocol) === delayValue) {
+            await new Promise<void>((r) => setImmediate(r));
+          }
+          return t.update(k, patch);
+        },
+      };
+    },
+  } as unknown as DataLayer;
+}
+
+async function mountFamily(data: DataLayer | undefined): Promise<{ hub: AgenticHub; transport: ReturnType<typeof memTransport> }> {
   const transport = memTransport();
   const hub = new AgenticHub({ transport: transport.transport, authenticator, sweepIntervalMs: 0 });
   const ctx: AgenticContext = {
@@ -283,7 +346,7 @@ async function mountFamily(db: SqliteDb | undefined): Promise<{ hub: AgenticHub;
     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,
+    data,
     log: noopLog(),
   };
   await family.mount(ctx);
@@ -291,7 +354,7 @@ async function mountFamily(db: SqliteDb | undefined): Promise<{ hub: AgenticHub;
 }
 
 test("family: mount attaches the three handlers and a REGISTER creates a durable presence row", async () => {
-  const { hub, transport } = await mountFamily(memSqlite());
+  const { hub, transport } = await mountFamily(memMountData());
   try {
     assertEquals(hub.router.families().sort(), ["deregister", "heartbeat", "register"]);
 
@@ -315,7 +378,7 @@ test("family: mount attaches the three handlers and a REGISTER creates a durable
 });
 
 test("family: HEARTBEAT keeps a worker and DEREGISTER removes it", async () => {
-  const { hub, transport } = await mountFamily(memSqlite());
+  const { hub, transport } = await mountFamily(memMountData());
   try {
     const peer = fakeConn("c1", "leaf");
     transport.connect(peer.conn);
@@ -338,7 +401,7 @@ test("family: HEARTBEAT keeps a worker and DEREGISTER removes it", async () => {
 });
 
 test("family: a disconnect removes the worker via reconcile", async () => {
-  const { hub, transport } = await mountFamily(memSqlite());
+  const { hub, transport } = await mountFamily(memMountData());
   try {
     const peer = fakeConn("c1", "leaf");
     transport.connect(peer.conn);
@@ -361,7 +424,7 @@ test("family: a disconnect removes the worker via reconcile", async () => {
 });
 
 test("family: teardown stops the family and clears the current registry", async () => {
-  const { hub } = await mountFamily(memSqlite());
+  const { hub } = await mountFamily(memMountData());
   assert(currentPresenceRegistry(), "mounted");
   family.teardown?.();
   assertEquals(currentPresenceRegistry(), undefined, "cleared on teardown");
@@ -379,3 +442,244 @@ test("family: mounting without a DataLayer is a safe no-op", async () => {
     await hub.close();
   }
 });
+
+// ── harness-protocol recording over the presence channel (issue #820) ──────────────────────────
+//
+// The #802 staleness gate only ever read the HTTP-enrol recorder, so a presence-only c8ctl-nano
+// fleet reported `harnessStale: true` permanently. These tests prove the presence REGISTER path now
+// feeds the ONE canonical `worker_harness_protocol` recorder the supply assessment joins.
+
+test("family: a REGISTER advertising harnessProtocol records it → the worker is assessed healthy", async () => {
+  const data = memMountData();
+  const { hub, transport } = await mountFamily(data);
+  try {
+    const peer = fakeConn("c1", "leafA");
+    transport.connect(peer.conn);
+    await flush();
+    // A presence-channel worker advertising the protocol on its enrolment capability (#820).
+    peer.feed(registerFrame("w1", { family: "opus", host: "boxA", harnessProtocol: 1 }));
+    await flush();
+
+    // Recorded into the ONE registry, keyed by instance, and joined by the shared supply assessment
+    // (default min protocol 1) → not stale.
+    const assessment = await assessWorkers(data, ["w1"], {});
+    assertEquals(assessment.get("w1")?.harnessProtocol, 1, "advertised protocol recorded");
+    assertEquals(assessment.get("w1")?.stale, false, "advertising min protocol clears the #802 stale flag");
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("family: a REGISTER advertising NO harnessProtocol stays stale (no #802 regression)", async () => {
+  const data = memMountData();
+  const { hub, transport } = await mountFamily(data);
+  try {
+    const peer = fakeConn("c1", "leafA");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(registerFrame("w1", { family: "opus", host: "boxA" }));
+    await flush();
+
+    const assessment = await assessWorkers(data, ["w1"], {});
+    assertEquals(assessment.get("w1")?.harnessProtocol, undefined, "no version advertised");
+    assertEquals(assessment.get("w1")?.stale, true, "absent version is stale — the #802 signal is preserved");
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("family: a below-minimum harnessProtocol is assessed stale against a raised minimum", async () => {
+  const data = memMountData();
+  const { hub, transport } = await mountFamily(data);
+  try {
+    const peer = fakeConn("c1", "leafA");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(registerFrame("w1", { harnessProtocol: 1 }));
+    await flush();
+
+    const assessment = await assessWorkers(data, ["w1"], { NANO_AGENTIC_MIN_HARNESS_PROTOCOL: "2" });
+    assertEquals(assessment.get("w1")?.harnessProtocol, 1, "advertised protocol recorded");
+    assertEquals(assessment.get("w1")?.stale, true, "below the raised minimum is stale");
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("family: a rejected takeover REGISTER cannot overwrite another peer's recorded protocol", async () => {
+  const data = memMountData();
+  const { hub, transport } = await mountFamily(data);
+  try {
+    // Owner registers instance w1 with a healthy protocol.
+    const owner = fakeConn("c1", "owner");
+    transport.connect(owner.conn);
+    await flush();
+    owner.feed(registerFrame("w1", { harnessProtocol: 1 }));
+    await flush();
+    assertEquals((await assessWorkers(data, ["w1"], {})).get("w1")?.stale, false, "owner recorded healthy");
+
+    // A different identity tries to take over w1 advertising no version — the presence store rejects
+    // the ownership takeover, so the recording must NOT clear the owner's healthy protocol.
+    const attacker = fakeConn("c2", "attacker");
+    transport.connect(attacker.conn);
+    await flush();
+    attacker.feed(registerFrame("w1", {}));
+    await flush();
+
+    const assessment = await assessWorkers(data, ["w1"], {});
+    assertEquals(assessment.get("w1")?.harnessProtocol, 1, "owner's recorded protocol survives a rejected takeover");
+    assertEquals(assessment.get("w1")?.stale, false, "no foreign peer can flip a worker stale");
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("family: a rejected re-register from the SAME connection cannot clear its own recorded protocol", async () => {
+  const data = memMountData();
+  const { hub, transport } = await mountFamily(data);
+  try {
+    // The worker registers healthily on its connection.
+    const peer = fakeConn("c1", "leafA");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(registerFrame("w1", { harnessProtocol: 1 }));
+    await flush();
+    assertEquals((await assessWorkers(data, ["w1"], {})).get("w1")?.stale, false, "recorded healthy");
+
+    // The SAME connection now sends a MALFORMED re-register (a non-object capability). The package
+    // handler rejects it and leaves the prior row in place — so a bare "this connection owns the row"
+    // check would still pass and clobber the healthy protocol with the rejected frame's absent value.
+    // The before/after acceptance check must skip a register that never took effect.
+    const malformed: Frame = { lane: "control", family: "register", seq: 1, payload: { instance: "w1", capability: "garbage" } };
+    peer.feed(malformed);
+    await flush();
+
+    const assessment = await assessWorkers(data, ["w1"], {});
+    assertEquals(assessment.get("w1")?.harnessProtocol, 1, "rejected re-register does not clear the recorded protocol");
+    assertEquals(assessment.get("w1")?.stale, false, "a rejected frame cannot flip a live worker stale");
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("family: two ACCEPTED same-connection re-registers in one clock tick both record their protocol", async () => {
+  // `lastSeen` is a millisecond timestamp, so two accepted REGISTERs on the same connection that
+  // arrive within one `Date.now()` tick share an identical `lastSeen`. An acceptance check that
+  // inferred "took effect" from a before/after `lastSeen` change would read the second (valid)
+  // re-register as a no-op and never record its protocol — a same-connection protocol upgrade would
+  // silently keep the old value. Freeze the clock so both registers land on the SAME tick and prove
+  // the upgrade is still recorded. (Reproduces the round-3 review finding; red under the old
+  // lastSeen-comparison code, green with the explicit accepted-register signal.)
+  mock.timers.enable({ apis: ["Date"], now: 1_700_000_000_000 });
+  const data = memMountData();
+  const { hub, transport } = await mountFamily(data);
+  try {
+    const peer = fakeConn("c1", "leafA");
+    transport.connect(peer.conn);
+    await flush();
+
+    // First accepted register: protocol 1.
+    peer.feed(registerFrame("w1", { harnessProtocol: 1 }));
+    await flush();
+    assertEquals((await assessWorkers(data, ["w1"], {})).get("w1")?.harnessProtocol, 1, "first protocol recorded");
+
+    // Second accepted re-register from the SAME connection, upgrading to protocol 2 — WITHOUT
+    // advancing the frozen clock, so its `lastSeen` is byte-identical to the first register's.
+    peer.feed(registerFrame("w1", { harnessProtocol: 2 }));
+    await flush();
+
+    const assessment = await assessWorkers(data, ["w1"], {});
+    assertEquals(assessment.get("w1")?.harnessProtocol, 2, "same-tick accepted re-register records its upgraded protocol");
+  } finally {
+    family.teardown?.();
+    await hub.close();
+    mock.timers.reset();
+  }
+});
+
+test("family: a rejected REGISTER concurrent with an accepted one for the same instance records only the accepted protocol", async () => {
+  // The recording wrapper `await`s the package handler, so two REGISTER frames for the SAME instance
+  // can be in flight at once (e.g. a foreign takeover on one connection racing a genuine re-register
+  // on the owner's). A shared per-instance "accepted generation" counter mis-attributes here: the
+  // rejected frame snapshots the counter, parks on its await while the concurrent ACCEPTED frame
+  // advances it, then resumes to see it changed and records its OWN absent protocol — a spurious
+  // `null` write that can clear a healthy value. The acceptance signal must be bound per-invocation
+  // (AsyncLocalStorage), so a concurrent frame can never flip THIS frame's flag. Assert it directly:
+  // during the overlapping pair, the ONLY value recorded is the accepted frame's — no clearing `null`
+  // write from the rejected frame. (Red under the shared-counter code, which writes `[null, 2]`;
+  // green with the per-invocation binding, which writes `[2]`.)
+  const { data, writes } = withProtocolWriteSpy(memMountData());
+  const { hub, transport } = await mountFamily(data);
+  try {
+    const owner = fakeConn("c1", "owner");
+    const attacker = fakeConn("c2", "attacker");
+    transport.connect(owner.conn);
+    transport.connect(attacker.conn);
+    await flush();
+
+    // Owner registers w1 healthily (protocol 1).
+    owner.feed(registerFrame("w1", { harnessProtocol: 1 }));
+    await flush();
+    assertEquals(writes, [1], "initial register records protocol 1");
+    writes.length = 0;
+
+    // Overlapping pair, fed WITHOUT a flush between so both are in flight across the await: a foreign
+    // takeover (rejected by ownership, no protocol) and the owner's accepted re-register to protocol 2.
+    attacker.feed(registerFrame("w1", {}));
+    owner.feed(registerFrame("w1", { harnessProtocol: 2 }));
+    await flush();
+    await flush();
+
+    // Only the accepted frame recorded; the rejected frame contributed no clearing `null` write.
+    assertEquals(writes, [2], "only the accepted re-register records; the rejected frame records nothing");
+    assertEquals((await assessWorkers(data, ["w1"], {})).get("w1")?.harnessProtocol, 2, "recorded protocol is the accepted upgrade");
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("family: two overlapping ACCEPTED re-registers record the NEWEST protocol even if the older write lands last", async () => {
+  // Two ACCEPTED re-registers for the same instance can be in flight at once (a reconnect race on the
+  // owner). `recordEnrolment` is async (findOne → update), so if the OLDER frame's write resumes AFTER
+  // the newer frame's, the older protocol overwrites the newer one — leaving the supply assessment
+  // stale until the next register. The recording must serialize per instance and honour acceptance
+  // order so the NEWEST accepted protocol always wins. Force the hazard deterministically: delay the
+  // older frame's (protocol 2) update by one macrotask so, unguarded, it lands after the newer
+  // (protocol 3) write. (Red under the un-serialized code, which persists the stale 2; green with the
+  // per-instance serialization + acceptance-sequence guard, which persists 3.)
+  const data = withDelayedProtocolUpdate(memMountData(), 2);
+  const { hub, transport } = await mountFamily(data);
+  try {
+    const owner = fakeConn("c1", "owner");
+    transport.connect(owner.conn);
+    await flush();
+
+    // Initial accepted register: protocol 1 (an insert, so the later updates are the ones that race).
+    owner.feed(registerFrame("w1", { harnessProtocol: 1 }));
+    await flush();
+    assertEquals((await assessWorkers(data, ["w1"], {})).get("w1")?.harnessProtocol, 1, "initial protocol recorded");
+
+    // Overlapping accepted re-registers, fed WITHOUT a flush between so both are in flight across the
+    // await: protocol 2 (older) then protocol 3 (newer). The newest accepted protocol must win.
+    owner.feed(registerFrame("w1", { harnessProtocol: 2 }));
+    owner.feed(registerFrame("w1", { harnessProtocol: 3 }));
+    await flush();
+    await flush();
+    await flush();
+
+    assertEquals(
+      (await assessWorkers(data, ["w1"], {})).get("w1")?.harnessProtocol,
+      3,
+      "the newest accepted re-register wins even when the older frame's write completes last",
+    );
+  } finally {
+    family.teardown?.();
+    await hub.close();
+  }
+});

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

@@ -19,19 +19,29 @@
 // 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 { AsyncLocalStorage } from "node:async_hooks";
+import type { AgenticHub, FamilyHandler, HubConnection } from "@nanobpm/agentic/channel";
 import {
   attachPresenceFamily,
   type PresenceFamilyHandle,
+  type PresenceRow,
   PresenceStore,
   type PresenceStoreOptions,
+  type RegisterInput,
   type SqliteDb,
 } from "@nanobpm/agentic/presence";
+import type { Frame, MessageFamily } from "@nanobpm/agentic/protocol";
 import type { DataLayer } from "@nanobpm/urban";
+import { HarnessProtocolRegistry } from "../../harnessProtocol.ts";
 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 presence REGISTER message family — the frame that carries the enrolment capability. */
+const REGISTER_FAMILY: MessageFamily = "register";
+
 /** The maintenance tick runs at a third of the presence TTL — matching the hub/store sweep cadence. */
 const SWEEP_DIVISOR = 3;
 
@@ -262,6 +272,170 @@ export function createPresenceStore(db: SqliteDb, options?: PresenceStoreOptions
   return new PresenceStore(db, options);
 }
 
+/** Read a property off an unknown value without an unsafe `as` cast (mirrors the relay/loader helper). */
+function readProp(value: unknown, key: string): unknown {
+  if (!value || typeof value !== "object") return undefined;
+  return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+}
+
+/** Read an optional advertised harness protocol off a presence REGISTER capability (issue #820).
+ *
+ * The wire capability the package validates is `{cognition, weight, family, host}` and its handler
+ * DROPS any other field, so the harness-protocol version a c8ctl-nano worker advertises over the
+ * presence channel (jwulf/c8ctl-plugin-nano#272) would never reach the ONE `worker_harness_protocol`
+ * recorder that the #802 staleness gate reads — the gate is inert for the presence-only fleet. This
+ * lifts the advertised version out of the register capability so it can be recorded. It is an
+ * ADR 0056 §7 enrolment attribute (never a routing token): a non-numeric / absent value reads back as
+ * `undefined` → the recorder stores NULL → the worker is assessed STALE (absent-version-is-stale, the
+ * #802 signature, preserved). */
+function readHarnessProtocol(payload: unknown): number | undefined {
+  const value = readProp(readProp(payload, "capability"), "harnessProtocol");
+  return typeof value === "number" ? value : undefined;
+}
+
+/**
+ * Wrap `hub` so that the presence REGISTER handler the package installs ALSO records the advertised
+ * harness protocol into the ONE canonical {@link HarnessProtocolRegistry} (issue #820) — the same
+ * table the HTTP `enrolAgenticWorker` door writes and `assessWorkers` reads (derivation over
+ * duplication, not a second store). Every other family passes through untouched.
+ *
+ * The record is gated on the register having actually TAKEN EFFECT — NOT merely on who owns the row
+ * afterwards. A bare "is the row now owned by this connection?" check is insufficient: a rejected or
+ * malformed RE-register from the connection that ALREADY owns the instance leaves the prior row in
+ * place, so that check still passes and would record the rejected frame's protocol (often `undefined`)
+ * — silently clearing a healthy protocol without any successful enrolment. The package accepts a
+ * register by calling {@link PresenceStore.register} exactly once and rejects it (a malformed payload,
+ * or an ownership takeover of an instance bound to a different identity) by dropping the frame WITHOUT
+ * touching the store. So we wrap `store.register` to flip an acceptance flag bound — via
+ * {@link AsyncLocalStorage} — to the exact recording invocation whose handler triggered it, and record
+ * only when THIS frame's flag is set: an explicit, per-invocation acceptance signal, not an inferred
+ * one.
+ *
+ * The binding must be per-invocation, NOT a shared per-instance marker: the recording wrapper `await`s
+ * the package handler, so two REGISTER frames for the same instance can be in flight at once. A shared
+ * "accepted generation" counter compared before/after the await would MIS-ATTRIBUTE — a rejected frame
+ * that snapshots the counter, parks on its await while a concurrent ACCEPTED frame for the same
+ * instance advances the counter, then resumes to see it changed and records its own absent/invalid
+ * protocol, clearing a healthy value. AsyncLocalStorage carries each frame's flag through its own await
+ * chain, so a concurrent frame runs in a DISTINCT context and can never flip this frame's flag. It also
+ * holds NO per-instance state, so nothing accumulates for deregistered / TTL-swept / ephemeral
+ * instances (an earlier per-instance `Map` leaked an entry per distinct instance forever). (An even
+ * earlier before/after `lastSeen` comparison could also FALSE-NEGATIVE two accepted same-connection
+ * re-registers within one `Date.now()` tick — identical millisecond timestamps read as "no change".)
+ * That skips every register the package dropped, so neither a foreign peer nor a self-inflicted bad
+ * frame can rewrite a worker's recorded protocol. Two ACCEPTED re-registers for one instance can also
+ * be in flight at once (a reconnect race), and the record write is async; the writes are SERIALIZED
+ * per instance and stamped with the monotonic acceptance sequence, so a stale (older) frame resuming
+ * last is skipped rather than overwriting the newer protocol — the newest accepted protocol always
+ * wins. Recording is best-effort: a registry write hiccup is
+ * logged and swallowed, exactly like the presence sweep, and never fails the register.
+ */
+function withHarnessProtocolRecording(
+  hub: AgenticHub,
+  store: PresenceStore,
+  data: DataLayer,
+  log: AgenticContext["log"],
+): AgenticHub {
+  const registry = new HarnessProtocolRegistry(data);
+  // An acceptance flag bound to the CURRENT recording invocation (AsyncLocalStorage, not a shared
+  // per-instance counter): the package handler calls store.register exactly on an accepted frame, so
+  // flipping THIS invocation's flag inside the wrapped register makes acceptance observable without a
+  // before/after comparison that could either collide within one Date.now() tick or be cross-attributed
+  // to a concurrent frame for the same instance across the await. It also keeps no per-instance state,
+  // so nothing leaks for deregistered / TTL-swept instances.
+  const acceptance = new AsyncLocalStorage<{ accepted: boolean; seq: number }>();
+  let acceptSeq = 0;
+  const registerInner = store.register.bind(store);
+  store.register = (input: RegisterInput): PresenceRow => {
+    const row = registerInner(input);
+    const active = acceptance.getStore();
+    // Stamp a monotonic acceptance SEQUENCE at the synchronous register call: it reflects the true
+    // order in which the store accepted overlapping re-registers, which the async record write below
+    // must preserve.
+    if (active) {
+      active.accepted = true;
+      active.seq = ++acceptSeq;
+    }
+    return row;
+  };
+  // Per-instance serialized write chains. Two ACCEPTED re-registers for one instance can be in flight
+  // at once (a reconnect race on the owner), and `recordEnrolment` is async (findOne → update), so
+  // their writes could otherwise interleave and land out of order — the OLDER frame resuming last and
+  // overwriting the NEWER protocol, leaving the supply assessment stale until the next register.
+  // Serialize the writes per instance AND skip any write whose acceptance sequence is stale (a newer
+  // accepted register already applied), so the newest accepted protocol always wins regardless of
+  // completion timing. The entry is dropped once its chain drains, so — like the per-invocation marker
+  // — nothing accumulates for deregistered / TTL-swept / ephemeral instances.
+  const writeChains = new Map<string, { tail: Promise<void>; lastSeq: number; pending: number }>();
+  const recordInOrder = (instance: string, seq: number, protocol: number | undefined): Promise<void> => {
+    let chain = writeChains.get(instance);
+    if (chain === undefined) {
+      chain = { tail: Promise.resolve(), lastSeq: 0, pending: 0 };
+      writeChains.set(instance, chain);
+    }
+    const c = chain;
+    c.pending++;
+    const run = c.tail.then(async () => {
+      // A newer accepted register (higher seq) already applied — this frame's write is stale, so skip
+      // it rather than clobber the fresher protocol with an out-of-order value.
+      if (seq <= c.lastSeq) return;
+      c.lastSeq = seq;
+      await registry.recordEnrolment(instance, protocol);
+    });
+    // Keep the chain live even if one write rejects (a rejection must not wedge later writes), and drop
+    // the per-instance entry once the last queued write drains.
+    c.tail = run
+      .then(
+        () => {},
+        () => {},
+      )
+      .finally(() => {
+        if (--c.pending === 0 && writeChains.get(instance) === c) writeChains.delete(instance);
+      });
+    return run;
+  };
+  return new Proxy(hub, {
+    get(target, prop, receiver) {
+      if (prop !== "registerFamilyHandler") {
+        const value = Reflect.get(target, prop, receiver);
+        return typeof value === "function" ? value.bind(target) : value;
+      }
+      return (family: MessageFamily, handler: FamilyHandler<HubConnection>) => {
+        if (family !== REGISTER_FAMILY) {
+          target.registerFamilyHandler(family, handler);
+          return;
+        }
+        const recording: FamilyHandler<HubConnection> = async (frame: Frame, conn: HubConnection) => {
+          const instance = readInstance(frame.payload);
+          // Run the package handler inside a fresh acceptance context. store.register — called by the
+          // handler exactly when it ACCEPTS this frame — flips THIS marker; a REJECTED frame (malformed
+          // or an ownership takeover the handler drops without touching the store) leaves it false. The
+          // marker travels with this frame's own async chain, so a concurrent frame for the same
+          // instance runs in a distinct context and can never flip it across the await.
+          const marker = { accepted: false, seq: 0 };
+          await acceptance.run(marker, () => handler(frame, conn));
+          if (instance === undefined) return;
+          // Record only when the package accepted THIS frame's register. A rejected re-register leaves
+          // the marker false, so it records nothing and cannot clear a healthy protocol.
+          if (!marker.accepted) return;
+          try {
+            await recordInOrder(instance, marker.seq, readHarnessProtocol(frame.payload));
+          } catch (err) {
+            log.warn("agentic presence: harness-protocol record failed", { instance, err: String(err) });
+          }
+        };
+        target.registerFamilyHandler(family, recording);
+      };
+    },
+  });
+}
+
+/** The `register.instance` off a presence payload, or undefined when absent/blank. */
+function readInstance(payload: unknown): string | undefined {
+  const value = readProp(payload, "instance");
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
 /**
  * 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
@@ -271,8 +445,9 @@ export const family: AgenticFamily = {
   name: PRESENCE_FAMILY,
 
   mount(ctx: AgenticContext): void {
-    const db = openPresenceDb(ctx.data);
-    if (!db) {
+    const data = ctx.data;
+    const db = openPresenceDb(data);
+    if (!db || !data) {
       ctx.log.warn("agentic presence: no data layer mounted — presence registry disabled");
       return;
     }
@@ -284,12 +459,18 @@ export const family: AgenticFamily = {
 
     // 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) }),
-    });
+    // canonical presence-maintenance pass, not a second poller (derivation over duplication). The hub
+    // is wrapped so the REGISTER handler ALSO records the advertised harness protocol into the ONE
+    // canonical registry (issue #820) — the presence-channel path to the #802 staleness gate.
+    const handle = attachPresenceFamily(
+      withHarnessProtocolRecording(ctx.hub, store, data, ctx.log),
+      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 = () => {