@nanobpm/nano-workforce 0.188.1 → 0.189.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.189.0](https://github.com/nanobpm/nano-workforce/compare/v0.188.1...v0.189.0) (2026-09-17)
+
+### Features
+
+* **agentic:** gate stale worker harnesses via persisted protocol ([#804](https://github.com/nanobpm/nano-workforce/issues/804)) ([e5ba2c3](https://github.com/nanobpm/nano-workforce/commit/e5ba2c39e0f76a2654099c54e37e0d3a97f20473)), closes [#802](https://github.com/nanobpm/nano-workforce/issues/802) [#802](https://github.com/nanobpm/nano-workforce/issues/802) [#802](https://github.com/nanobpm/nano-workforce/issues/802) [#802](https://github.com/nanobpm/nano-workforce/issues/802) [#802](https://github.com/nanobpm/nano-workforce/issues/802) [#802](https://github.com/nanobpm/nano-workforce/issues/802)
+
 ## [0.188.1](https://github.com/nanobpm/nano-workforce/compare/v0.188.0...v0.188.1) (2026-09-17)
 
 ### Bug Fixes

package/app/agentic/cockpit/mount.test.ts

@@ -111,6 +111,56 @@ test("the rendered transcript region sits directly beneath the Workers — suppl
   }
 });
 
+// #802 — the DEPLOYED browser twin (mount.js) must surface a STALE harness as a distinct badge, and
+// a healthy one with none. The typed renderer (`supply-render.ts`) has its own test, but the twin is
+// hand-maintained and previously had no non-empty supply-row coverage, so it could silently stop
+// surfacing stale harnesses while the typed test stayed green.
+test("#802: mount.js renders a stale-harness badge for a stale worker and none for a healthy one", async () => {
+  const worker = (instance: string, harnessStale: boolean, harnessProtocol?: number) => ({
+    instance,
+    identity: "senior",
+    stream: instance,
+    family: "senior",
+    host: "h1",
+    jobKeys: [],
+    live: true,
+    staleMs: 0,
+    harnessStale,
+    ...(harnessProtocol !== undefined ? { harnessProtocol } : {}),
+  });
+  const workers = [worker("wk-stale", true, 0), worker("wk-ok", false, 3)];
+  const report = { count: workers.length, workers, leaves: [{ token: "senior", workers }], correlations: [] };
+  const restore = installEnv((url) => {
+    const ok = (body: unknown) => Promise.resolve({ ok: true, status: 200, json: async () => body });
+    if (url.includes("/supply")) return ok(report);
+    if (url.includes("/agent-instances")) return ok({ count: 0, instances: [] });
+    if (url.includes("/transcripts")) return ok({ sessions: [] });
+    return Promise.resolve({ ok: false, status: 404, json: async () => ({}) });
+  });
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await handle.refresh();
+      const staleRow = document.querySelector('.cockpit-supply-worker[data-worker="wk-stale"]');
+      const okRow = document.querySelector('.cockpit-supply-worker[data-worker="wk-ok"]');
+      assert(staleRow != null && okRow != null, "both worker rows rendered");
+      const badge = staleRow?.querySelector('.cockpit-supply-harness-stale[data-harness-stale="true"]');
+      assert(badge != null, "the stale worker carries the harness-stale badge");
+      assertEquals(badge?.textContent, "stale harness (v0)", "the badge shows the advertised protocol");
+      assertEquals(
+        okRow?.querySelector(".cockpit-supply-harness-stale"),
+        null,
+        "the healthy worker carries no harness-stale badge",
+      );
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});
+
 test("live drill renders the transcript — a nwfTranscriptEvent chunk is never surfaced verbatim", async () => {
   const restore = installEnv(fetchStub());
   try {

package/app/agentic/cockpit/supply-render.test.ts

@@ -140,3 +140,23 @@ test("H6: a worker with no correlation renders an em-dash process cell", () => {
   assert.equal(cell?.text(), "—");
   assert.equal(cell?.getAttribute("data-correlations"), "0");
 });
+
+test("#802: renders a stale-harness badge for a worker below the minimum / with no advertised protocol", () => {
+  const host = new FakeElement("body");
+  const staleWorker = { instance: "wk-old", identity: "leaf-1", stream: "wk-old", family: "senior", host: "h1", jobKeys: [], live: true, staleMs: 0, harnessStale: true };
+  const okWorker = { instance: "wk-ok", identity: "leaf-1", stream: "wk-ok", family: "senior", host: "h2", jobKeys: [], live: true, staleMs: 0, harnessStale: false, harnessProtocol: 3 };
+  const report: SupplyReport = {
+    count: 2,
+    workers: [staleWorker, okWorker],
+    leaves: [{ token: "leaf-1", workers: [staleWorker, okWorker] }],
+  };
+  renderSupply(host, doc, supplyView(report));
+
+  const rowOld = host.byData("worker", "wk-old")[0];
+  assert.equal(rowOld?.getAttribute("data-harness-stale"), "true");
+  assert.equal(rowOld?.byClass("cockpit-supply-harness-stale").length, 1, "stale harness badge rendered");
+
+  const rowOk = host.byData("worker", "wk-ok")[0];
+  assert.equal(rowOk?.getAttribute("data-harness-stale"), "false");
+  assert.equal(rowOk?.byClass("cockpit-supply-harness-stale").length, 0, "no badge for a healthy harness");
+});

package/app/agentic/cockpit/supply-render.ts

@@ -51,6 +51,7 @@ function workerRow(doc: DocumentLike, worker: SupplyWorkerView, options: RenderS
   row.setAttribute("data-worker", worker.instance);
   row.setAttribute("data-liveness", worker.liveness);
   row.setAttribute("data-stream", worker.stream);
+  row.setAttribute("data-harness-stale", String(worker.harnessStale));
 
   const nameCell = el(doc, "td", "cockpit-td cockpit-supply-name");
   nameCell.appendChild(dot(doc, worker.liveness));
@@ -82,6 +83,20 @@ function workerRow(doc: DocumentLike, worker: SupplyWorkerView, options: RenderS
     }
     nameCell.appendChild(drill);
   }
+  // A stale harness silently swallows machine-readable artifacts (issue #802) — surface it as a
+  // distinct badge so the operator can drain/upgrade the worker. Separate from the liveness dot,
+  // which grades heartbeat recency, not harness capability.
+  if (worker.harnessStale) {
+    const badge = el(
+      doc,
+      "span",
+      "cockpit-supply-harness-stale",
+      worker.harnessProtocol === undefined ? "stale harness" : `stale harness (v${worker.harnessProtocol})`,
+    );
+    badge.setAttribute("data-harness-stale", "true");
+    badge.setAttribute("title", "Harness protocol below the configured minimum (or none advertised); jobs may dead-end.");
+    nameCell.appendChild(badge);
+  }
   row.appendChild(nameCell);
 
   row.appendChild(el(doc, "td", "cockpit-td cockpit-supply-family", worker.family));

package/app/agentic/cockpit/supply-view.ts

@@ -38,9 +38,16 @@ export interface SupplyWorkerReport {
   readonly live: boolean;
   /** How long since the worker's last liveness refresh, in ms. */
   readonly staleMs: number;
+  /**
+   * Whether the worker's HARNESS is stale — its advertised harness protocol is below the configured
+   * minimum, or it advertised none at all (issue #802). Distinct from {@link Liveness} `"stale"`,
+   * which grades heartbeat recency. A stale harness silently swallows machine-readable artifacts
+   * (AgentInstance / transcript / result envelope), so its jobs dead-end at human escalations.
+   */
+  readonly harnessStale?: boolean;
+  /** The harness protocol version the worker advertised at enrolment, if any (issue #802). */
+  readonly harnessProtocol?: number;
 }
-
-/** The supply registered under one leaf token. */
 export interface SupplyLeafReport {
   readonly token: string;
   readonly workers: readonly SupplyWorkerReport[];
@@ -128,6 +135,10 @@ export interface SupplyWorkerView {
   readonly liveness: Liveness;
   /** How long since the last liveness refresh, in ms. */
   readonly staleMs: number;
+  /** Whether the worker's harness protocol is stale (below minimum / absent) — issue #802. */
+  readonly harnessStale: boolean;
+  /** The advertised harness protocol version, if any (issue #802). */
+  readonly harnessProtocol?: number;
 }
 
 /** One leaf-token section in the renderable supply view. */
@@ -212,6 +223,12 @@ function workerView(
     correlations,
     liveness: liveness(worker, staleAfterMs),
     staleMs: worker.staleMs,
+    // Fail loud: a report without a harness verdict (an older/cached response) has no trustworthy
+    // protocol assessment, so keep the worker visible as STALE until the server supplies a healthy one
+    // — mirrors the server's `harness?.stale ?? true` (issue #802). Defaulting to `false` here would
+    // let a cached response hide exactly the workers this surface is meant to expose.
+    harnessStale: worker.harnessStale ?? true,
+    ...(worker.harnessProtocol !== undefined ? { harnessProtocol: worker.harnessProtocol } : {}),
   };
 }
 

package/app/agentic/vocab/demand-report.test.ts

@@ -5,8 +5,11 @@ import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { TaskDefinitionLeaf } from "@nanobpm/agentic/demand";
 import type { RegisteredWorker } from "@nanobpm/agentic/vocab";
+import { HarnessProtocolRegistry } from "../../harnessProtocol.ts";
+import { noopLog } from "../../../test/log.ts";
+import { memDataFor } from "../../../test/worldDb.ts";
 import { CREW_VOCAB_VERSION } from "./crew-vocab.ts";
-import { buildRegistryReport, engineRestAddress, toWireReport } from "./demand-report.ts";
+import { buildRegistryReport, computeRegistryReport, engineRestAddress, toWireReport } from "./demand-report.ts";
 
 const NOW = new Date(0);
 // A demanded taskDefinition leaf. `agentic` is the structural signal the engine reads from a task's
@@ -142,3 +145,65 @@ test("engineRestAddress strips trailing slashes from the derived NANOBPMN_BASE_U
     else process.env.NANOBPMN_BASE_URL = prevBase;
   }
 });
+
+test("#802: toWireReport carries staleWorkers through, omitting harnessProtocol when absent", () => {
+  const base = buildRegistryReport({ taskDefinitions: [], workers: [seniorImpl] });
+  const report = {
+    ...base,
+    staleWorkers: [
+      { instance: "wk-old", stale: true },
+      { instance: "wk-low", stale: true, harnessProtocol: 0 },
+    ],
+  };
+  const wire = toWireReport(report);
+  assertEquals(wire.staleWorkers, [
+    { instance: "wk-old", stale: true },
+    { instance: "wk-low", stale: true, harnessProtocol: 0 },
+  ]);
+});
+
+test("#802: toWireReport omits staleWorkers entirely when the report has none (supply-only build)", () => {
+  const report = buildRegistryReport({ taskDefinitions: [], workers: [seniorImpl] });
+  assertEquals("staleWorkers" in toWireReport(report), false);
+});
+
+const HARNESS_MIGRATIONS = ["107_worker_harness_protocol.sql"];
+
+test("#802: computeRegistryReport threads live workers through the registry into staleWorkers", async () => {
+  // Exercises the real assessment→staleWorkers wiring end-to-end against a mounted registry (migration
+  // 107) rather than hand-building `staleWorkers` before `toWireReport`: a regression in passing the
+  // live workers through `assessWorkersWithAvailability` would otherwise stay green.
+  const { data } = memDataFor(HARNESS_MIGRATIONS);
+  const reg = new HarnessProtocolRegistry(data);
+  await reg.recordEnrolment("w-front", 5); // healthy (>= default min 1)
+  await reg.recordEnrolment("w-kimi", 0); // below minimum → stale
+  // seniorImpl ("w-senior") never enrolled a protocol → absent → stale.
+  const report = await computeRegistryReport(noopLog(), data, [plannerFrontier, plannerKimi, seniorImpl]);
+  assertEquals(report.staleWorkers, [
+    { instance: "w-kimi", stale: true, harnessProtocol: 0 },
+    { instance: "w-senior", stale: true },
+  ]);
+  // The stale-harness condition is folded into the OVERALL status so the board's status pill (which
+  // renders only `report.status`, not `staleWorkers`) turns RED rather than staying green (issue #802).
+  assertEquals(report.status, "red");
+});
+
+test("#802: computeRegistryReport keeps status green when every enrolled harness is healthy", async () => {
+  // Guards the fold's other edge: a mounted registry with NO stale workers must NOT force `red` — the
+  // overall status stays whatever demand×supply produced (here green, empty demand / no missing).
+  const { data } = memDataFor(HARNESS_MIGRATIONS);
+  const reg = new HarnessProtocolRegistry(data);
+  await reg.recordEnrolment("w-front", 5);
+  await reg.recordEnrolment("w-senior", 5);
+  const report = await computeRegistryReport(noopLog(), data, [plannerFrontier, seniorImpl]);
+  assertEquals(report.staleWorkers, []);
+  assertEquals(report.status, "green");
+});
+
+test("#802: computeRegistryReport OMITS staleWorkers when the registry cannot be consulted", async () => {
+  // A legacy DB predating migration 107: the bounded read throws → registryAvailable=false, so the
+  // report must omit staleWorkers rather than mislabel an outage as a fleet-wide drain signal.
+  const { data } = memDataFor([]);
+  const report = await computeRegistryReport(noopLog(), data, [plannerFrontier, seniorImpl]);
+  assertEquals("staleWorkers" in report, false, "an outage omits staleWorkers, not report every worker stale");
+});

package/app/agentic/vocab/demand-report.ts

@@ -18,9 +18,10 @@ import {
   type TaskDefinitionLeaf,
 } from "@nanobpm/agentic/demand";
 import type { RegisteredWorker } from "@nanobpm/agentic/vocab";
-import type { Logger } from "@nanobpm/urban";
-import type { RegistryReport as WireRegistryReport } from "../../../nano-generated/api-io.d.ts";
+import type { DataLayer, Logger } from "@nanobpm/urban";
+import type { StaleWorker, RegistryReport as WireRegistryReport } from "../../../nano-generated/api-io.d.ts";
 import { resolveEngineAddress } from "../../enginePreflight.ts";
+import { assessWorkersWithAvailability, type HarnessAssessment } from "../../harnessProtocol.ts";
 import { envVar } from "../../version.ts";
 import { currentPresenceRegistry } from "../families/presence.family.ts";
 import { CREW_VOCAB_VERSION, crewResolver } from "./crew-vocab.ts";
@@ -38,6 +39,15 @@ export interface RegistryReport extends DemandSupplyReport {
    * demand is unavailable rather than silently showing "no demand".
    */
   readonly demandUnavailable: boolean;
+  /**
+   * The enrolled workers whose harness is STALE (issue #802) — below the configured minimum protocol,
+   * or advertising no version at all — so they may silently swallow AgentInstance / transcript /
+   * result-envelope artifacts and should be drained. Empty when every supplied worker is healthy;
+   * omitted only when the harness-protocol registry could not be consulted. When non-empty, the
+   * overall {@link DemandSupplyReport.status} is folded to `red` (a drain signal), because the board
+   * renders only `status` and does not surface this list on its own.
+   */
+  readonly staleWorkers?: readonly HarnessAssessment[];
 }
 
 /**
@@ -159,15 +169,53 @@ export function toWireReport(report: RegistryReport): WireRegistryReport {
       })),
     },
     status: report.status,
+    ...(report.staleWorkers !== undefined
+      ? {
+          staleWorkers: report.staleWorkers.map((w): StaleWorker => {
+            const out: StaleWorker = { instance: w.instance, stale: w.stale };
+            if (w.harnessProtocol !== undefined) out.harnessProtocol = w.harnessProtocol;
+            return out;
+          }),
+        }
+      : {}),
   };
 }
 
 /**
  * The composition path the `getAgenticRegistry` operation calls: read demand from the engine, read
- * supply from the presence registry, and build the report. Never throws for an engine outage — it
- * degrades to a supply-only report.
+ * supply from the presence registry, assess harness staleness (issue #802), and build the report.
+ * Never throws for an engine outage — it degrades to a supply-only report; the staleness assessment
+ * is best-effort and omitted when no data layer is mounted.
+ *
+ * `workers` defaults to the live presence feed ({@link supplyWorkers}); it is injectable so a test can
+ * drive the full assessment→`staleWorkers` wiring against a real registry without mounting the global
+ * presence family.
  */
-export async function computeRegistryReport(log?: Logger): Promise<RegistryReport> {
+export async function computeRegistryReport(
+  log?: Logger,
+  data?: DataLayer,
+  workers: readonly RegisteredWorker[] = supplyWorkers(),
+): Promise<RegistryReport> {
   const taskDefinitions = await readDemand(log);
-  return buildRegistryReport({ taskDefinitions, workers: supplyWorkers() });
+  const report = buildRegistryReport({ taskDefinitions, workers });
+  if (!data) return report;
+  const { registryAvailable, assessments } = await assessWorkersWithAvailability(
+    data,
+    workers.map((w) => w.instance),
+  );
+  // The registry could not be consulted (read outage / legacy DB): OMIT `staleWorkers` per the report
+  // contract, so an operator cannot mistake "the registry is unavailable" for "every harness is stale"
+  // and treat an outage as a fleet-wide drain signal (issue #802).
+  if (!registryAvailable) return report;
+  const staleWorkers = [...assessments.values()]
+    .filter((a) => a.stale)
+    .sort((a, b) => a.instance.localeCompare(b.instance));
+  // Fold the stale-harness condition into the OVERALL status (issue #802). The board renders only
+  // `report.status` as its overall pill and does not surface `staleWorkers`, so without this a
+  // healthy-demand report (status `green`/`amber`) would still show green while enrolled harnesses are
+  // stale — silently swallowing AgentInstance / transcript / result-envelope artifacts. A stale
+  // harness is a drain signal, so any stale worker forces the overall status to `red` (`red` is
+  // already the worst grade, so this never downgrades an existing `red`).
+  const status = staleWorkers.length > 0 ? "red" : report.status;
+  return { ...report, status, staleWorkers };
 }

package/app/contracts.ts

@@ -233,6 +233,22 @@ export const ENV_CONTRACTS = {
     semantics:
       "Feature flag for the agentic supply endpoint; a value of 0/off/false/no disables it (enabled when unset).",
   },
+  NANO_AGENTIC_MIN_HARNESS_PROTOCOL: {
+    category: "env",
+    name: "NANO_AGENTIC_MIN_HARNESS_PROTOCOL",
+    owner: "app/harnessProtocol.ts",
+    semantics:
+      "Minimum worker-harness protocol version a worker must advertise at enrolment to be considered healthy (issue #802). A worker advertising a version below this — or advertising NO version at all (absent = stale) — is flagged stale in getAgenticSupply / the registry and, under NANO_AGENTIC_STALE_HARNESS_POLICY=refuse, is refused agent-job routing. Non-integer/blank degrades to the default.",
+    default: "1",
+  },
+  NANO_AGENTIC_STALE_HARNESS_POLICY: {
+    category: "env",
+    name: "NANO_AGENTIC_STALE_HARNESS_POLICY",
+    owner: "app/harnessProtocol.ts",
+    semantics:
+      "How the app treats a stale worker harness (issue #802): 'flag' (default) only marks it stale for observability/drain; 'refuse' additionally withholds its SERVE tokens at enrol so it wins no job leases. Anything other than the exact token 'refuse' is treated as 'flag' so a typo never silently drains the fleet.",
+    default: "flag",
+  },
   NANO_WORKFORCE_GIT_SHA: {
     category: "env",
     name: "NANO_WORKFORCE_GIT_SHA",
@@ -562,6 +578,14 @@ export const TYPE_CONTRACTS = {
       "The `durable-resume` ENROLMENT GATE (issue #325, ADR 0062 Slice 5/5, the INTEGRATION slice). `durable-resume` is a worker attribute declared at enrolment (ADR 0056 §7 — capability gates enrolment, NEVER the routing token `network.role#seat`), recorded per worker instance in `worker_durable_resume` (migration 052). The enrol door (`operations/enrolAgenticWorker.ts`) records it via `recordEnrolment`; `app/service.ts` consults `fleetSupportsDurableResume` before emitting the world-restore `commitSha` (the `io.nanobpm.agentTask.repository` envelope) so a re-leased `senior:pr-review` round RESUMES only on a participating fleet and gracefully DEGRADES (redriven from scratch) otherwise. Consume this ONE module for the durable-resume gate — do not re-declare a synonym or read the flag off a second store.",
     module: "app/durableResume.ts",
   },
+  HarnessProtocolRegistry: {
+    category: "type",
+    name: "HarnessProtocolRegistry",
+    owner: "app/harnessProtocol.ts",
+    semantics:
+      "The durable registry of per-worker advertised harness protocol version (issue #802), over `worker_harness_protocol` (migration 107) through the RAD `Table<T>` surface — mirroring {@link DurableResumeRegistry}. `harness-protocol` is a worker ATTRIBUTE advertised at enrolment (ADR 0056 §7 — capability gates enrolment, NEVER the routing token `network.role#seat`), recorded per worker instance by `recordEnrolment` from the enrol door (`operations/enrolAgenticWorker.ts`); a MISSING version is first-class STALE. It is the ONE shared source consumed by enrolment (record), supply (`getAgenticSupply` staleness verdict) and registry reporting (`computeRegistryReport` → `staleWorkers`, which folds a non-empty stale set into the overall red drain signal). The bounded `protocolsFor(instances)` read scopes to the live presence keys via a single `WHERE instance IN (…)` query — never an N+1 per-worker `findOne`. Consume this ONE module for the harness-protocol gate — do not re-declare a synonym or read the version off a second store.",
+    module: "app/harnessProtocol.ts",
+  },
 } as const satisfies Record<string, TypeContract>;
 
 export const CAPABILITY_URL_CONTRACTS = {

package/app/harnessProtocol.test.ts

@@ -0,0 +1,170 @@
+// Tests for the harness-protocol enrolment gate (issue #802) — the env knobs, the staleness
+// derivation, and the durable registry over `worker_harness_protocol` (migration 107).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  assessWorkers,
+  assessWorkersWithAvailability,
+  HarnessProtocolRegistry,
+  isStaleProtocol,
+  minHarnessProtocol,
+  staleHarnessPolicy,
+} from "./harnessProtocol.ts";
+import { memDataFor } from "../test/worldDb.ts";
+
+const MIGRATIONS = ["107_worker_harness_protocol.sql"];
+
+test("minHarnessProtocol defaults to 1 and reads the declared env knob", () => {
+  assertEquals(minHarnessProtocol({}), 1);
+  assertEquals(minHarnessProtocol({ NANO_AGENTIC_MIN_HARNESS_PROTOCOL: "3" }), 3);
+  // A malformed/blank value degrades to the default rather than NaN-poisoning the gate.
+  assertEquals(minHarnessProtocol({ NANO_AGENTIC_MIN_HARNESS_PROTOCOL: "nonsense" }), 1);
+});
+
+test("minHarnessProtocol rejects parseInt-lenient values (Copilot #802): '3junk'/'1.9'/blank → default", () => {
+  // `Number.parseInt` would accept "3junk" (→ 3) and truncate "1.9" (→ 1); a strict integer parse
+  // degrades all of these to the registered default so a malformed knob never silently shifts the gate.
+  assertEquals(minHarnessProtocol({ NANO_AGENTIC_MIN_HARNESS_PROTOCOL: "3junk" }), 1);
+  assertEquals(minHarnessProtocol({ NANO_AGENTIC_MIN_HARNESS_PROTOCOL: "1.9" }), 1);
+  assertEquals(minHarnessProtocol({ NANO_AGENTIC_MIN_HARNESS_PROTOCOL: "" }), 1);
+  assertEquals(minHarnessProtocol({ NANO_AGENTIC_MIN_HARNESS_PROTOCOL: "  " }), 1);
+  assertEquals(minHarnessProtocol({ NANO_AGENTIC_MIN_HARNESS_PROTOCOL: "-2" }), 1);
+  // A clean integer (with surrounding whitespace) still parses.
+  assertEquals(minHarnessProtocol({ NANO_AGENTIC_MIN_HARNESS_PROTOCOL: " 4 " }), 4);
+  assertEquals(minHarnessProtocol({ NANO_AGENTIC_MIN_HARNESS_PROTOCOL: "0" }), 0);
+});
+
+test("staleHarnessPolicy defaults to flag; only the exact 'refuse' token opts into refusal", () => {
+  assertEquals(staleHarnessPolicy({}), "flag");
+  assertEquals(staleHarnessPolicy({ NANO_AGENTIC_STALE_HARNESS_POLICY: "refuse" }), "refuse");
+  assertEquals(staleHarnessPolicy({ NANO_AGENTIC_STALE_HARNESS_POLICY: "  REFUSE " }), "refuse");
+  assertEquals(staleHarnessPolicy({ NANO_AGENTIC_STALE_HARNESS_POLICY: "flagg" }), "flag");
+});
+
+test("isStaleProtocol: absent version is stale; below-minimum is stale; at-or-above is healthy", () => {
+  assertEquals(isStaleProtocol(undefined, 1), true, "no version advertised = stale");
+  assertEquals(isStaleProtocol(null, 1), true, "null version = stale");
+  assertEquals(isStaleProtocol(0, 1), true, "below minimum = stale");
+  assertEquals(isStaleProtocol(1, 1), false, "at minimum = healthy");
+  assertEquals(isStaleProtocol(5, 1), false, "above minimum = healthy");
+});
+
+test("registry records the advertised protocol and reads it back (idempotent upsert)", async () => {
+  const { data } = memDataFor(MIGRATIONS);
+  const reg = new HarnessProtocolRegistry(data);
+  await reg.recordEnrolment("wk-1", 2);
+  assertEquals(await reg.protocolFor("wk-1"), 2);
+  // Re-enrol overwrites (upsert keyed by instance).
+  await reg.recordEnrolment("wk-1", 4);
+  assertEquals(await reg.protocolFor("wk-1"), 4);
+});
+
+test("a downgrade re-enrol WITHOUT a version clears a stale-healthy value to absent (stale)", async () => {
+  const { data } = memDataFor(MIGRATIONS);
+  const reg = new HarnessProtocolRegistry(data);
+  await reg.recordEnrolment("wk-1", 3);
+  assertEquals(await reg.protocolFor("wk-1"), 3);
+  await reg.recordEnrolment("wk-1", undefined);
+  assertEquals(await reg.protocolFor("wk-1"), undefined, "stale-healthy value cleared to NULL");
+});
+
+test("a blank/whitespace instance is a no-op (no unreachable/colliding row)", async () => {
+  const { data } = memDataFor(MIGRATIONS);
+  const reg = new HarnessProtocolRegistry(data);
+  await reg.recordEnrolment("   ", 2);
+  assertEquals((await reg.all()).size, 0);
+});
+
+test("assessWorkers: flags absent/below-min as stale, at-or-above as healthy (canonical derivation)", async () => {
+  const { data } = memDataFor(MIGRATIONS);
+  const reg = new HarnessProtocolRegistry(data);
+  await reg.recordEnrolment("healthy", 2);
+  await reg.recordEnrolment("old", 0);
+  await reg.recordEnrolment("versionless", undefined);
+  // "never-enrolled" has no row at all.
+  const out = await assessWorkers(data, ["healthy", "old", "versionless", "never-enrolled"], {
+    NANO_AGENTIC_MIN_HARNESS_PROTOCOL: "1",
+  });
+  assertEquals(out.get("healthy"), { instance: "healthy", harnessProtocol: 2, stale: false });
+  assertEquals(out.get("old"), { instance: "old", harnessProtocol: 0, stale: true });
+  assertEquals(out.get("versionless"), { instance: "versionless", stale: true });
+  assertEquals(out.get("never-enrolled"), { instance: "never-enrolled", stale: true });
+});
+
+test("protocolsFor: one bounded IN query maps each ORIGINAL key back, skips blanks, short-circuits empty", async () => {
+  // The hot-path read is a single bounded `WHERE instance IN (…)` over the live set (not a per-worker
+  // findOne / O(history) scan): assert it maps each key back correctly and handles the edge sets.
+  const { data } = memDataFor(MIGRATIONS);
+  const reg = new HarnessProtocolRegistry(data);
+  await reg.recordEnrolment("a", 3);
+  await reg.recordEnrolment("b", undefined); // NULL row → undefined
+  // "c" never enrolled.
+  const got = await reg.protocolsFor(["a", "b", "c", "   "]);
+  assertEquals(got.get("a"), 3);
+  assertEquals(got.get("b"), undefined);
+  assertEquals(got.get("c"), undefined);
+  assertEquals(got.has("   "), false, "a blank instance keys no row and is skipped");
+  // An empty (or all-blank) set short-circuits without issuing an `IN ()` query.
+  assertEquals((await reg.protocolsFor([])).size, 0);
+  assertEquals((await reg.protocolsFor(["  "])).size, 0);
+});
+
+test("protocolsFor chunks past SQLite's host-parameter cap (a large fleet does not overflow one IN query)", async () => {
+  // A fleet larger than a single IN(…) batch must still resolve every key: the read is chunked under
+  // SQLite's ~999 host-parameter floor, so scale never throws (which the caller would mislabel as a
+  // fleet-wide outage marking everyone stale). Exercise > 900 (two batches) plus a boundary key.
+  const { data } = memDataFor(MIGRATIONS);
+  const reg = new HarnessProtocolRegistry(data);
+  const instances: string[] = [];
+  for (let i = 0; i < 1500; i++) {
+    const id = `wk-${i}`;
+    instances.push(id);
+    if (i % 2 === 0) await reg.recordEnrolment(id, 2); // even = enrolled@2, odd = never enrolled
+  }
+  const got = await reg.protocolsFor(instances);
+  assertEquals(got.size, 1500, "every requested key is mapped back across batches");
+  assertEquals(got.get("wk-0"), 2);
+  assertEquals(got.get("wk-900"), 2, "a key in the second batch still resolves");
+  assertEquals(got.get("wk-1"), undefined, "a never-enrolled key reads back undefined");
+  assertEquals(got.get("wk-1499"), undefined);
+});
+
+test("assessWorkers with no data layer treats every worker as stale (fail loud)", async () => {
+  const out = await assessWorkers(undefined, ["a", "b"]);
+  assertEquals(out.get("a")?.stale, true);
+  assertEquals(out.get("b")?.stale, true);
+  assert(!("harnessProtocol" in (out.get("a") ?? {})), "no protocol known without a registry");
+});
+
+test("assessWorkersWithAvailability: registryAvailable is true on a successful read, false without a data layer", async () => {
+  const { data } = memDataFor(MIGRATIONS);
+  await new HarnessProtocolRegistry(data).recordEnrolment("healthy", 2);
+  const ok = await assessWorkersWithAvailability(data, ["healthy"], { NANO_AGENTIC_MIN_HARNESS_PROTOCOL: "1" });
+  assertEquals(ok.registryAvailable, true);
+  assertEquals(ok.assessments.get("healthy")?.stale, false);
+
+  const noData = await assessWorkersWithAvailability(undefined, ["healthy"]);
+  assertEquals(noData.registryAvailable, false, "no data layer = registry could not be consulted");
+  assertEquals(noData.assessments.get("healthy")?.stale, true, "still fails loud per-worker");
+});
+
+test("assessWorkersWithAvailability: a registry read outage reports registryAvailable=false (not silent all-stale)", async () => {
+  // A legacy DB predating migration 107: the table is absent, so the bounded read throws and is caught.
+  const { data } = memDataFor([]);
+  const res = await assessWorkersWithAvailability(data, ["a", "b"]);
+  assertEquals(res.registryAvailable, false, "read failure surfaces as unavailable, distinct from all-healthy");
+  assertEquals(res.assessments.get("a")?.stale, true, "assessments still fail loud");
+});
+
+test("protocolsFor reads only the requested instances (bounded), not the whole history", async () => {
+  const { data } = memDataFor(MIGRATIONS);
+  const reg = new HarnessProtocolRegistry(data);
+  await reg.recordEnrolment("live-1", 2);
+  await reg.recordEnrolment("live-2", undefined);
+  await reg.recordEnrolment("disconnected-history", 3);
+  const scoped = await reg.protocolsFor(["live-1", "live-2", "never-enrolled"]);
+  assertEquals(scoped.get("live-1"), 2);
+  assertEquals(scoped.get("live-2"), undefined, "an enrolled-but-versionless row reads as undefined");
+  assertEquals(scoped.get("never-enrolled"), undefined, "an absent row reads as undefined");
+  assertEquals(scoped.has("disconnected-history"), false, "a historical instance outside the live set is never read");
+});