@nanobpm/nano-workforce 0.188.1 → 0.189.0

package/app/harnessProtocol.ts

@@ -0,0 +1,312 @@
+// nano-workforce — the harness-protocol ENROLMENT GATE (issue #802).
+//
+// A stale worker harness — a `c8ctl-nano` build predating the AgentInstance-minting + transcript-flush
+// + result-envelope path — silently services jobs and swallows every machine-readable artifact, so
+// good agent work is lost to the orchestration and every run it touches dead-ends at a human
+// (#796/#801). Job routing was BLIND to harness capability/version: enrolment advertised
+// family/host/cognition/weight/durableResume but NOT a harness protocol version, so a stale harness
+// won job leases indistinguishably from a healthy one.
+//
+// This module makes harness staleness OBSERVABLE and GATEABLE. It records, per worker instance, the
+// protocol version the harness advertised at enrolment (a WORKER ATTRIBUTE — ADR 0056 §7, capability
+// gates enrolment and is NEVER a routing token `network.role#seat`), and derives whether a worker is
+// stale (below the minimum protocol, or advertising no version at all). The minimum protocol and the
+// enforcement policy (flag-only vs refuse-routing) are declared env-contract knobs (app/contracts.ts).
+//
+// Advisory + app-tier only (ADR 0056): the registry NEVER hard-locks a BPMN sequence flow. The one
+// place it may WITHHOLD is the SERVE-token resolution at enrol under the `refuse` policy — a stale
+// harness is handed an empty SERVE set so it wins no job leases — which is a REGISTER→SERVE gate, not
+// an engine/job-protocol change.
+import type { DataLayer } from "@nanobpm/urban";
+import { readEnvOr } from "./contracts.ts";
+
+/**
+ * The canonical name of the harness-protocol enrolment attribute. A worker advertises it at enrol; the
+ * registry records it here. It is an ENROLMENT gate (ADR 0056 §7), never a routing token.
+ */
+export const HARNESS_PROTOCOL_ATTR = "harness-protocol";
+
+/** The default minimum harness protocol when {@link NANO_AGENTIC_MIN_HARNESS_PROTOCOL} is unset. Kept
+ * in the ONE registry entry (app/contracts.ts) — this literal only documents it for the reader. */
+const DEFAULT_MIN_HARNESS_PROTOCOL = 1;
+
+/** The staleness-enforcement policy: `flag` only marks a stale worker (observability); `refuse` also
+ * withholds its SERVE tokens at enrol so it wins no job leases. */
+export type StaleHarnessPolicy = "flag" | "refuse";
+
+/** The default enforcement policy — `flag`, so a fleet whose harnesses have not yet been upgraded is
+ * made VISIBLE but not abruptly drained. An operator opts into `refuse` to hard-gate routing. */
+const DEFAULT_STALE_HARNESS_POLICY: StaleHarnessPolicy = "flag";
+
+/** The durable table backing {@link HarnessProtocolRegistry} (`db/migrations/107_worker_harness_protocol.sql`).
+ * The ONE source of truth for the name so the `Table<T>` gateway and the bounded batch read below can
+ * never drift. */
+const HARNESS_PROTOCOL_TABLE = "worker_harness_protocol";
+
+/** Max bound host-parameters per `WHERE instance IN (…)` batch in {@link HarnessProtocolRegistry.protocolsFor}.
+ * SQLite caps the number of host parameters per statement (`SQLITE_MAX_VARIABLE_NUMBER` — historically
+ * 999, and still that low on many builds), so a single `IN (…)` binding one placeholder per live worker
+ * would THROW once the fleet outgrows that limit — and the caller's read-failure fallback marks every
+ * worker stale (a false fleet-wide drain/outage signal from mere scale). 900 stays safely under the
+ * conservative 999 floor while keeping the batch count minimal; the live keys are chunked into batches of
+ * this size and unioned, so the bounded hot-path read scales past the parameter cap. */
+const IN_QUERY_MAX_PARAMS = 900;
+
+/** A persisted enrolment row (`worker_harness_protocol`): one worker instance's advertised protocol. */
+interface WorkerHarnessProtocolRow {
+  instance: string;
+  harness_protocol: number | null;
+  updated_at: string;
+}
+
+/**
+ * The configured minimum harness protocol a worker must advertise to be considered healthy. Read
+ * through the ONE typed env schema ({@link NANO_AGENTIC_MIN_HARNESS_PROTOCOL}); a non-integer / blank
+ * value degrades to the registered default rather than throwing (advisory — the report must never
+ * fail on a malformed knob).
+ */
+export function minHarnessProtocol(env: Record<string, string | undefined> = process.env): number {
+  const raw = readEnvOr("NANO_AGENTIC_MIN_HARNESS_PROTOCOL", String(DEFAULT_MIN_HARNESS_PROTOCOL), env).trim();
+  // `Number.parseInt` accepts `"3junk"` (→ 3) and truncates `"1.9"` (→ 1), so a malformed/non-integer
+  // knob would NOT degrade to the registered default as this function and the env contract promise.
+  // Parse with `Number` and require a strict non-negative integer. A blank value (`Number("")` → 0)
+  // must also fall through to the default, hence the explicit non-empty guard.
+  const parsed = Number(raw);
+  return raw.length > 0 && Number.isInteger(parsed) && parsed >= 0 ? parsed : DEFAULT_MIN_HARNESS_PROTOCOL;
+}
+
+/**
+ * The configured staleness-enforcement policy. Read through the ONE typed env schema
+ * ({@link NANO_AGENTIC_STALE_HARNESS_POLICY}); anything other than the exact `refuse` token (case- and
+ * whitespace-insensitive) is the safe default `flag`, so a typo never silently drains the fleet.
+ */
+export function staleHarnessPolicy(env: Record<string, string | undefined> = process.env): StaleHarnessPolicy {
+  const raw = readEnvOr("NANO_AGENTIC_STALE_HARNESS_POLICY", DEFAULT_STALE_HARNESS_POLICY, env).trim().toLowerCase();
+  return raw === "refuse" ? "refuse" : "flag";
+}
+
+/**
+ * Whether an advertised protocol is STALE against the minimum. A `undefined`/`null` protocol — a
+ * harness that advertised NO version, or one never enrolled through this app — is stale (absent version
+ * = stale, the #802 signature). Otherwise stale iff below the minimum.
+ */
+export function isStaleProtocol(
+  protocol: number | undefined | null,
+  min: number = minHarnessProtocol(),
+): boolean {
+  if (protocol === undefined || protocol === null || !Number.isFinite(protocol)) return true;
+  return protocol < min;
+}
+
+/** A worker's harness-staleness assessment — the shape surfaced in `getAgenticSupply` / the registry. */
+export interface HarnessAssessment {
+  /** The worker instance id. */
+  readonly instance: string;
+  /** The advertised protocol version, when a numeric one is known (omitted for absent/none). */
+  readonly harnessProtocol?: number;
+  /** Whether the worker's harness is stale (below minimum, or no version advertised). */
+  readonly stale: boolean;
+}
+
+/**
+ * The result of {@link assessWorkersWithAvailability}: the per-instance assessments plus whether the
+ * harness-protocol registry could actually be CONSULTED. `registryAvailable` is `false` when no data
+ * layer is mounted or the read threw (a legacy DB predating migration 107, an in-flight desync); the
+ * assessments still fail loud (every worker reads STALE) so per-worker supply visibility is unchanged,
+ * but the registry report uses this flag to OMIT its `staleWorkers` list rather than mislabel an
+ * outage as a fleet-wide drain signal (issue #802).
+ */
+export interface WorkerAssessment {
+  /** False when the harness-protocol registry could not be consulted (no data layer, or the read threw). */
+  readonly registryAvailable: boolean;
+  /** The canonical per-instance staleness assessment (every requested instance is present). */
+  readonly assessments: Map<string, HarnessAssessment>;
+}
+
+/**
+ * The durable registry of per-worker advertised harness protocol, over the `worker_harness_protocol`
+ * table (`db/migrations/107_worker_harness_protocol.sql`). Backed by the app's SQLite DataLayer through
+ * the RAD `Table<T>` surface (`data.table(...)`) — NOT hand-written SQL — mirroring
+ * {@link ../durableResume.ts DurableResumeRegistry}.
+ */
+export class HarnessProtocolRegistry {
+  readonly #data: DataLayer;
+
+  constructor(data: DataLayer) {
+    this.#data = data;
+  }
+
+  #table() {
+    return this.#data.table<WorkerHarnessProtocolRow>(HARNESS_PROTOCOL_TABLE, "instance");
+  }
+
+  /** Canonicalise an instance key: trim surrounding whitespace and reject a blank one — the instance
+   * is the PRIMARY KEY, so a whitespace/blank key would create an unreachable row or let unrelated
+   * workers collide. Returns the trimmed key, or `undefined` when empty/whitespace. */
+  static #normaliseInstance(instance: string): string | undefined {
+    const trimmed = instance.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+
+  /** Coerce an advertised protocol to the stored INTEGER (or NULL when none/malformed). A finite
+   * non-negative integer is stored; anything else records NULL — an "advertised no usable version"
+   * marker that reads back as STALE. */
+  static #coerce(protocol: number | undefined | null): number | null {
+    if (typeof protocol === "number" && Number.isInteger(protocol) && protocol >= 0) return protocol;
+    return null;
+  }
+
+  /**
+   * Record a worker's advertised harness protocol at enrolment (an idempotent UPSERT keyed by
+   * `instance`). A re-enrol overwrites the value so a harness that GAINS — or LOSES — protocol support
+   * across a redeploy is reflected (a downgrade re-enrol without a version clears a stale-healthy value
+   * to NULL → stale). The `findOne`-then-insert is racy under a concurrent duplicate enrol, so a
+   * PRIMARY KEY fence collision folds into the update path (same end-state either way). A
+   * blank/whitespace `instance` is a no-op — it cannot key a reachable row.
+   */
+  async recordEnrolment(instance: string, protocol: number | undefined | null): Promise<void> {
+    const key = HarnessProtocolRegistry.#normaliseInstance(instance);
+    if (key === undefined) return;
+    const value = HarnessProtocolRegistry.#coerce(protocol);
+    const table = this.#table();
+    const now = new Date().toISOString();
+    const existing = await table.findOne({ instance: key });
+    if (existing) {
+      await table.update(key, { harness_protocol: value, updated_at: now });
+      return;
+    }
+    try {
+      await table.insert({ instance: key, harness_protocol: value, updated_at: now });
+    } catch (err) {
+      if (!isFenceCollision(err)) throw err;
+      await table.update(key, { harness_protocol: value, updated_at: now });
+    }
+  }
+
+  /** The advertised protocol for a worker instance, or `undefined` when it advertised none (NULL row)
+   * or was never enrolled here. */
+  async protocolFor(instance: string): Promise<number | undefined> {
+    const key = HarnessProtocolRegistry.#normaliseInstance(instance);
+    if (key === undefined) return undefined;
+    const row = await this.#table().findOne({ instance: key });
+    const value = row?.harness_protocol;
+    return typeof value === "number" ? value : undefined;
+  }
+
+  /** Every recorded (instance → advertised protocol) mapping, for a bulk supply/registry join. */
+  async all(): Promise<Map<string, number | undefined>> {
+    const rows = await this.#table().find({});
+    const out = new Map<string, number | undefined>();
+    for (const row of rows) {
+      out.set(row.instance, typeof row.harness_protocol === "number" ? row.harness_protocol : undefined);
+    }
+    return out;
+  }
+
+  /**
+   * The recorded protocols for a bounded set of live instances — the supply/registry hot-path read.
+   * Unlike {@link all}, this scopes the query to the CURRENT `instances` set rather than scanning
+   * every historical row, so a table that grows with disconnected worker instances does not turn each
+   * 2-second cockpit poll into an O(history) full-table load (an instance is never removed on
+   * disconnect). It issues ONE bounded `WHERE instance IN (…)` query over the normalised, de-duplicated
+   * live keys — not a per-worker `findOne` — so the poll never degrades into an N+1 round-trip pattern
+   * as the fleet grows (Copilot #802). The bound keys are chunked into batches under SQLite's
+   * host-parameter cap ({@link IN_QUERY_MAX_PARAMS}) and unioned, so a very large fleet cannot overflow
+   * a single `IN (…)`'s placeholder limit and throw (which the caller would mislabel as a fleet-wide
+   * outage). A blank/whitespace instance is skipped (it can key no reachable
+   * row); an empty set short-circuits without a query (`IN ()` is not valid SQL). Any read error
+   * propagates so the caller can distinguish "registry unavailable" from "all healthy".
+   */
+  async protocolsFor(instances: readonly string[]): Promise<Map<string, number | undefined>> {
+    const out = new Map<string, number | undefined>();
+    // Normalise + de-duplicate the live keys to bind into a single bounded IN query.
+    const keys = new Set<string>();
+    for (const instance of instances) {
+      const key = HarnessProtocolRegistry.#normaliseInstance(instance);
+      if (key !== undefined) keys.add(key);
+    }
+    if (keys.size === 0) return out;
+    const keyList = [...keys];
+    // Chunk the bound keys into batches under SQLite's host-parameter cap (see IN_QUERY_MAX_PARAMS):
+    // a single IN (…) binding one placeholder per live worker would throw once the fleet outgrows the
+    // limit, and the caller then mislabels every worker stale (a false drain/outage signal from scale).
+    const byKey = new Map<string, number | undefined>();
+    for (let offset = 0; offset < keyList.length; offset += IN_QUERY_MAX_PARAMS) {
+      const batch = keyList.slice(offset, offset + IN_QUERY_MAX_PARAMS);
+      const placeholders = batch.map(() => "?").join(", ");
+      const rows = await this.#data
+        .open()
+        .query<WorkerHarnessProtocolRow>(
+          `SELECT instance, harness_protocol FROM ${HARNESS_PROTOCOL_TABLE} WHERE instance IN (${placeholders})`,
+          batch,
+        );
+      for (const row of rows) {
+        byKey.set(row.instance, typeof row.harness_protocol === "number" ? row.harness_protocol : undefined);
+      }
+    }
+    // Key the result back by the caller's ORIGINAL instance strings (the assessment reads it by the
+    // same key it passed in); an instance with no row reads back `undefined` → stale, unchanged.
+    for (const instance of instances) {
+      const key = HarnessProtocolRegistry.#normaliseInstance(instance);
+      if (key === undefined) continue;
+      out.set(instance, byKey.get(key));
+    }
+    return out;
+  }
+}
+
+/** True when `err` is the durable PRIMARY KEY fence firing (a SQLite `UNIQUE constraint failed` from a
+ * concurrent/duplicate enrol between our `findOne` and `insert`). `recordEnrolment` is an upsert, so a
+ * collision means "the row now exists" — the same intended outcome as the update branch. Matched on
+ * the message substring the RAD `Table` surface propagates verbatim (mirrors `DurableResumeRegistry`). */
+function isFenceCollision(err: unknown): boolean {
+  return err instanceof Error && /UNIQUE constraint failed/i.test(err.message);
+}
+
+/**
+ * Assess a set of worker instances against the recorded harness protocols and the configured minimum,
+ * ALSO reporting whether the registry could be consulted — the ONE canonical staleness derivation
+ * shared by `getAgenticSupply` and the registry report (no second heuristic). The read is bounded to
+ * the current `instances` set (not an O(history) full-table scan). Best-effort: any registry read
+ * failure (a legacy DB predating migration 107, an in-flight desync, no data layer mounted) degrades
+ * to "unknown protocol" → every worker STALE (fail loud, per absent-version-is-stale) with
+ * `registryAvailable: false`, rather than throwing — so a caller can OMIT an aggregate stale list
+ * instead of mislabelling an outage as a drain signal.
+ */
+export async function assessWorkersWithAvailability(
+  data: DataLayer | undefined,
+  instances: readonly string[],
+  env: Record<string, string | undefined> = process.env,
+): Promise<WorkerAssessment> {
+  const min = minHarnessProtocol(env);
+  let protocols: Map<string, number | undefined> = new Map();
+  let registryAvailable = false;
+  if (data) {
+    try {
+      protocols = await new HarnessProtocolRegistry(data).protocolsFor(instances);
+      registryAvailable = true;
+    } catch (err) {
+      console.warn(`[harness-protocol] supply assessment read failed: ${err}`);
+    }
+  }
+  const out = new Map<string, HarnessAssessment>();
+  for (const instance of instances) {
+    const protocol = protocols.get(instance);
+    const assessment: HarnessAssessment = { instance, stale: isStaleProtocol(protocol, min) };
+    out.set(instance, protocol !== undefined ? { ...assessment, harnessProtocol: protocol } : assessment);
+  }
+  return { registryAvailable, assessments: out };
+}
+
+/**
+ * The per-instance staleness assessments — the fail-loud supply path (a read failure reads every
+ * worker as STALE). A thin projection of {@link assessWorkersWithAvailability} for callers that only
+ * need the per-worker verdict and not the registry-availability signal (there is ONE derivation).
+ */
+export async function assessWorkers(
+  data: DataLayer | undefined,
+  instances: readonly string[],
+  env: Record<string, string | undefined> = process.env,
+): Promise<Map<string, HarnessAssessment>> {
+  return (await assessWorkersWithAvailability(data, instances, env)).assessments;
+}

package/app/mcpToolSurface.ts

@@ -105,8 +105,14 @@ export const MCP_TOOL_COUNT_BUDGET = 60;
  * `x-mcp` convention that read/orient doors stay exposed; only operator-only control doors are
  * excluded, see app/mcpExclusions.test.ts). Measured +1,846 bytes serialized (84,043 → 85,889 —
  * over the old ceiling's 457-byte headroom). Deliberate, documented growth — not schema fat.
+ *
+ * RAISE PROVENANCE — 86_500 → 87_000 (#802): the worker-harness protocol surface adds
+ * `harnessProtocol`/`harnessStale` observability fields to the `enrolAgenticWorker`,
+ * `getAgenticSupply`, and registry read schemas (plus the `StaleWorker` leaf) so an operator can spot
+ * and drain a stale harness from the tool surface alone. Measured 86,509 bytes serialized — 9 over the
+ * old ceiling's headroom. Deliberate, documented growth — not schema fat.
  */
-export const MCP_SURFACE_BYTES_BUDGET = 86_500;
+export const MCP_SURFACE_BYTES_BUDGET = 87_000;
 
 /**
  * The eagerly-loaded curated subset MUST stay materially smaller than the full surface — otherwise it

package/db/migrations/107_worker_harness_protocol.sql

@@ -0,0 +1,30 @@
+-- 107_worker_harness_protocol.sql — issue #802: make stale worker harnesses observable and gateable.
+--
+-- A stale worker harness (a `c8ctl-nano` build predating the AgentInstance-minting + transcript-flush
+-- + result-envelope path) silently services jobs and swallows every machine-readable artifact, so good
+-- agent work is lost to the orchestration and every run it touches dead-ends at a human (#796/#801).
+-- Job routing is blind to harness capability/version, so a stale harness wins job leases
+-- indistinguishably from a healthy one.
+--
+-- The fix persists the protocol version a harness advertises at ENROLMENT — a WORKER ATTRIBUTE (ADR
+-- 0056 §7 — capability gates enrolment, NEVER a routing token `network.role#seat`) — so the app can
+-- (a) expose it in `getAgenticSupply` / the registry and (b) flag RED / refuse agent-job routing for
+-- any worker below the minimum protocol. A MISSING version is treated as stale.
+--
+-- This mirrors `worker_durable_resume` (migration 052): one FK-free table keyed by the worker
+-- instance (`register.instance` / the enrol `instance`). FK-free by design — enrolment is per-worker
+-- and connection-agnostic, with no parent row to reference. EXPAND (additive) phase: one new table;
+-- nothing is dropped or renamed. Migration-prefix block 107–108 pre-assigned to this slice
+-- (issue #802) off the origin/main high-water mark (104). The runner wraps each file in its own
+-- transaction, so this file must NOT contain BEGIN/COMMIT.
+
+CREATE TABLE IF NOT EXISTS worker_harness_protocol (
+  instance          TEXT PRIMARY KEY,  -- the worker instance id (enrol `instance` / register.instance)
+  -- The protocol version the harness advertised, or NULL when it advertised NONE. NULL is a first-class
+  -- "advertised no version" marker — distinct in intent from an absent row (never enrolled here), but
+  -- BOTH resolve to STALE at read time (absent version = stale). Recorded even on a downgrade so a
+  -- harness that previously advertised a healthy protocol and later re-enrols WITHOUT one clears its
+  -- stale-healthy value (mirrors the worker_durable_resume degrade-to-scratch semantics).
+  harness_protocol  INTEGER,
+  updated_at        TEXT NOT NULL
+);

package/openapi.yaml

@@ -429,6 +429,7 @@ components:
         - jobKeys
         - live
         - staleMs
+        - harnessStale
       properties:
         instance:
           type: string
@@ -456,6 +457,17 @@ components:
         staleMs:
           type: integer
           description: Milliseconds since the last liveness refresh (0 when fresh).
+        harnessProtocol:
+          type: integer
+          minimum: 0
+          description: The worker-harness protocol version this worker advertised at enrolment (issue #802), when a numeric one is known.
+        harnessStale:
+          type: boolean
+          description: >-
+            Whether this worker's harness is STALE (issue #802) — below the configured minimum protocol
+            or advertising no version at all — so it may silently swallow AgentInstance / transcript /
+            result-envelope artifacts. Surfaced so the operator can drain it. Distinct from the
+            liveness `staleMs` heartbeat grade.
     AgenticSupplyLeaf:
       type: object
       description: The supply for one leaf token — the workers registered under it.
@@ -622,6 +634,16 @@ components:
             sets false) redrives a re-leased round from scratch. Recorded only when `instance` is
             a non-blank string — a missing, empty, or whitespace-only `instance` is echoed back for
             provenance but the flag is not persisted.
+        harnessProtocol:
+          type: integer
+          minimum: 0
+          description: >-
+            The worker-harness protocol version (issue #802) — a non-negative integer declaring which
+            machine-readable artifacts the harness emits (AgentInstance, transcript flush, result
+            envelope). An ENROLMENT attribute, never a routing token. Recorded per instance so the app
+            can flag a stale harness in getAgenticSupply / the registry and — under
+            NANO_AGENTIC_STALE_HARNESS_POLICY=refuse — refuse it agent-job routing. A missing version is
+            treated as stale.
     EnrolledRole:
       type: object
       description: One matched role in an enrolment resolution — provenance for the resolved SERVE set.
@@ -643,6 +665,7 @@ components:
         - roles
         - demandVersion
         - leaseTtl
+        - harnessStale
       properties:
         instance:
           type: string
@@ -655,6 +678,20 @@ components:
             guarantee of durable persistence — recording into the durable-resume registry is
             best-effort (skipped when `instance` is absent/blank, and a registry write hiccup is
             logged without failing enrolment).
+        harnessProtocol:
+          type: integer
+          minimum: 0
+          description: >-
+            Echo of the request's advertised harness protocol version (issue #802). Present only when
+            the request supplied it.
+        harnessStale:
+          type: boolean
+          description: >-
+            Whether this worker's harness is STALE (issue #802) — below the configured minimum protocol
+            (NANO_AGENTIC_MIN_HARNESS_PROTOCOL) or advertising no version at all. Always present. Under
+            NANO_AGENTIC_STALE_HARNESS_POLICY=refuse a stale harness is handed an EMPTY `serve` set so
+            it wins no job leases; under the default `flag` policy `serve` is unchanged and the worker
+            is only flagged for observability/drain.
         serve:
           type: array
           description: The SERVE token set — sorted, de-duplicated leaf tokens the worker may serve.
@@ -812,7 +849,36 @@ components:
         status:
           type: string
           enum: [green, amber, red]
-          description: The overall SLO — worst of the missing-agent signal and the diversity SLO.
+          description: >-
+            The overall SLO — worst of the missing-agent signal and the diversity SLO, and folded to
+            `red` when any enrolled harness is stale (`staleWorkers` non-empty, issue #802), since the
+            board renders only this pill as its overall signal.
+        staleWorkers:
+          type: array
+          description: >-
+            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. Present (possibly empty) when
+            the app's harness-protocol registry is available.
+          items:
+            $ref: "#/components/schemas/StaleWorker"
+    StaleWorker:
+      type: object
+      description: One enrolled worker flagged as running a stale harness (issue #802).
+      required:
+        - instance
+        - stale
+      properties:
+        instance:
+          type: string
+          description: The worker instance id.
+        harnessProtocol:
+          type: integer
+          minimum: 0
+          description: The advertised harness protocol version, when a numeric one is known (omitted when none was advertised).
+        stale:
+          type: boolean
+          description: Whether the worker's harness is stale (always true for entries in this list).
     AgenticTranscript:
       type: object
       description: One captured agent session's transcript metadata (H3/#146 transcript store). A durable
@@ -3993,6 +4059,10 @@ paths:
                 durableResume:
                   type: boolean
                   description: "Whether this worker's harness advertises durable-resume (issue #325, ADR 0062 Slice 5/5) — an ENROLMENT attribute, never a routing token. Recorded per instance so the app emits the world-restore marker only to a fleet with a participant; a harness that omits it (or sets false) redrives a re-leased round from scratch. Recorded only when `instance` is a non-blank string — a missing, empty, or whitespace-only `instance` is echoed back for provenance but the flag is not persisted."
+                harnessProtocol:
+                  type: integer
+                  minimum: 0
+                  description: 'The worker-harness protocol version (issue #802) — a non-negative integer declaring which machine-readable artifacts the harness emits (AgentInstance, transcript flush, result envelope). An ENROLMENT attribute, never a routing token. Recorded per instance so the app can flag a stale harness in getAgenticSupply / the registry and — under NANO_AGENTIC_STALE_HARNESS_POLICY=refuse — refuse it agent-job routing. A missing version is treated as stale.'
               # END generated:mcp-body
       responses:
         "200":

package/operations/enrolAgenticWorker.test.ts

@@ -4,6 +4,7 @@ import { assert, assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
 import { memDataFor } from "../test/worldDb.ts";
 import { DurableResumeRegistry } from "../app/durableResume.ts";
+import { HarnessProtocolRegistry } from "../app/harnessProtocol.ts";
 import { noopLog } from "../test/log.ts";
 import handler from "./enrolAgenticWorker.ts";
 
@@ -151,3 +152,86 @@ test("enforces the shared secret when NANO_PR_WEBHOOK_SECRET is set", async () =
     else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
   }
 });
+
+// Harness-protocol enrolment gate (issue #802).
+const HARNESS_MIGRATIONS = ["052_worker_durable_resume.sql", "107_worker_harness_protocol.sql"];
+
+test("echoes harnessProtocol and reports harnessStale=false for a healthy protocol (>= minimum)", async () => {
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", harnessProtocol: 2 }), app)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.harnessProtocol, 2);
+  assertEquals(res.body.harnessStale, false);
+  // No routing regression under the default `flag` policy: SERVE is unchanged.
+  assert(res.body.serve.includes("decide"));
+});
+
+test("flags harnessStale=true when the harness advertises no version at all (absent = stale)", async () => {
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1" }), app)) as any;
+  assertEquals(res.status, 200);
+  assertEquals("harnessProtocol" in res.body, false, "no protocol echoed when none advertised");
+  assertEquals(res.body.harnessStale, true);
+  // Default `flag` policy: a stale harness is still routed (only flagged), so no fleet regression.
+  assert(res.body.serve.includes("decide"), "flag policy leaves SERVE intact");
+});
+
+test("flags harnessStale=true for a below-minimum protocol", async () => {
+  const prev = process.env["NANO_AGENTIC_MIN_HARNESS_PROTOCOL"];
+  process.env["NANO_AGENTIC_MIN_HARNESS_PROTOCOL"] = "3";
+  try {
+    const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", harnessProtocol: 1 }), app)) as any;
+    assertEquals(res.status, 200);
+    assertEquals(res.body.harnessStale, true);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_AGENTIC_MIN_HARNESS_PROTOCOL"];
+    else process.env["NANO_AGENTIC_MIN_HARNESS_PROTOCOL"] = prev;
+  }
+});
+
+test("rejects a non-integer/negative harnessProtocol as 400", async () => {
+  const nonInt = (await handler(input({ capability: { cognition: "decide" }, harnessProtocol: 1.5 }), app)) as any;
+  assertEquals(nonInt.status, 400);
+  const negative = (await handler(input({ capability: { cognition: "decide" }, harnessProtocol: -1 }), app)) as any;
+  assertEquals(negative.status, 400);
+  const str = (await handler(input({ capability: { cognition: "decide" }, harnessProtocol: "2" }), app)) as any;
+  assertEquals(str.status, 400);
+});
+
+test("records the advertised harness protocol in the registry when a data layer + instance are present", async () => {
+  const { data } = memDataFor(HARNESS_MIGRATIONS);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", harnessProtocol: 2 }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(await new HarnessProtocolRegistry(data).protocolFor("w1"), 2);
+});
+
+test("a re-enrol WITHOUT a protocol clears a stale-healthy recorded value (degrade to stale)", async () => {
+  const { data } = memDataFor(HARNESS_MIGRATIONS);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  await handler(input({ capability: { cognition: "decide" }, instance: "w1", harnessProtocol: 3 }), withData);
+  assertEquals(await new HarnessProtocolRegistry(data).protocolFor("w1"), 3);
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1" }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(await new HarnessProtocolRegistry(data).protocolFor("w1"), undefined, "stale-healthy value cleared");
+});
+
+test("under the `refuse` policy a stale harness is handed an EMPTY SERVE set (no job leases)", async () => {
+  const prev = process.env["NANO_AGENTIC_STALE_HARNESS_POLICY"];
+  process.env["NANO_AGENTIC_STALE_HARNESS_POLICY"] = "refuse";
+  try {
+    const mod = await import(`./enrolAgenticWorker.ts?refuse=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    // A stale (version-less) worker: SERVE withheld.
+    const stale = (await guarded(input({ capability: { cognition: "decide" }, instance: "w1" }), app)) as any;
+    assertEquals(stale.status, 200);
+    assertEquals(stale.body.harnessStale, true);
+    assertEquals(stale.body.serve, [], "refuse policy withholds SERVE for a stale harness");
+    assertEquals(stale.body.roles, []);
+    // A healthy worker is routed exactly as today.
+    const healthy = (await guarded(input({ capability: { cognition: "decide" }, instance: "w2", harnessProtocol: 5 }), app)) as any;
+    assertEquals(healthy.body.harnessStale, false);
+    assert(healthy.body.serve.includes("decide"), "healthy harness routed under refuse policy");
+  } finally {
+    if (prev === undefined) delete process.env["NANO_AGENTIC_STALE_HARNESS_POLICY"];
+    else process.env["NANO_AGENTIC_STALE_HARNESS_POLICY"] = prev;
+  }
+});