@nanobpm/nano-workforce 0.188.1 → 0.189.1

package/app/service.ts

@@ -9,7 +9,8 @@
 // `Table<T>` surface), not hand-written SQL. Row shapes are declared inline here.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { ABANDONED_STATUS, abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
-import { escalationFormId } from "./agentCompletion.ts";
+import { matchAdjudication, prAdjudications, resetAdjudications } from "./adjudications.ts";
+import { completeEscalationAutoApplied, escalationFormId } from "./agentCompletion.ts";
 import { agentSlaTimeout } from "./agentSla.ts";
 import {
   CAPS_RESOLVED_MESSAGE,
@@ -585,6 +586,14 @@ export async function submitPr(
     for (const e of await escs(data).find({ pr_key: parsed.prKey, status: "open" })) {
       await escs(data).update(e.id, { status: "stale" });
     }
+    // A fresh convergence run must ALSO start with a clean durable adjudication memory (issue #806,
+    // Copilot review): the auto-resume replays a prior `(PR, question)` answer forever, so a re-opened
+    // PR whose question recurs would silently auto-apply the stale decision and an operator could never
+    // force a fresh one. This PR's adjudications are invalidated on reopen — but the reset is deferred
+    // to AFTER `process_key` is advanced to the new instance (see below), NOT here: clearing the memory
+    // while `process_key` still names the OLD instance leaves a window where a delayed old-instance
+    // answer job still passes the worker's staleness gate and reinserts its adjudication into the fresh
+    // run (Copilot review of #806). Advancing the run identity FIRST, then clearing, fences that job.
     // Re-open a previously converged/abandoned/merged PR for a fresh convergence run.
     await table.update(parsed.prKey, {
       status: "converging",
@@ -682,8 +691,44 @@ export async function submitPr(
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);
-  if (processKey != null) {
-    await table.update(parsed.prKey, { process_key: processKey });
+  // The `process_key` advance and the adjudication reset below are the two writes that MAKE the new
+  // run authoritative. If EITHER throws, the newly created instance is already live but the reopen is
+  // only half-committed — and a retry would short-circuit at the `alreadyRunning` idempotency gate
+  // (the new instance is ACTIVE, so `derived_status` is non-terminal), never re-running the reset. A
+  // failed reset would then leave the fresh run replaying STALE adjudication memory indefinitely
+  // (Copilot review). So roll the just-created run back on failure: terminate it and rethrow, so the
+  // submission is NOT treated as started. Terminating flips the PR's derived tracking status to a
+  // terminal edge (`abandoned`) via the `instanceTracking` reconciler, making the PR resubmittable so
+  // a retry re-creates a fresh instance and re-runs the reset cleanly — no orphaned run auto-applies
+  // stale decisions in the meantime.
+  try {
+    if (processKey != null) {
+      await table.update(parsed.prKey, { process_key: processKey });
+    }
+    // Invalidate this PR's durable adjudication memory for the fresh run (issue #806, Copilot review) —
+    // deferred to HERE, after `process_key` is advanced to the new instance above, so the reset happens
+    // UNDER the new run identity. On reopen (`existing`), any delayed old-instance answer job is now
+    // rejected by the worker's staleness gate (its `processInstanceKey` no longer matches the advanced
+    // `process_key`), so it cannot reinsert a stale adjudication after the reset; and the worker reads
+    // `process_key` as late as possible so it observes this advance. The insert-if-absent record then
+    // re-learns the operator's new answer for the new run. Runs unconditionally (even if `processKey` is
+    // null: the memory must still be clean for the fresh run). The wipe is a SINGLE atomic `DELETE`
+    // (`resetAdjudications`), never a row-by-row loop, so a crash mid-reset cannot leave a partially
+    // cleared memory (Copilot review of #806).
+    if (existing) {
+      await resetAdjudications(data, parsed.prKey);
+    }
+  } catch (err) {
+    if (processInstanceKey != null) {
+      try {
+        await engine.cancelInstance({ processInstanceKey: String(processInstanceKey) });
+      } catch (cancelErr) {
+        // Best-effort: a failed rollback-cancel leaves the instance for the abandon/reconcile poller
+        // to reap, but must not mask the original error that the caller needs to see and retry on.
+        console.warn(`[submit] ${parsed.prKey} rollback-cancel of ${processInstanceKey} failed: ${cancelErr}`);
+      }
+    }
+    throw err;
   }
   return { prKey: parsed.prKey, processKey };
 }
@@ -2839,12 +2884,67 @@ export async function pollUserTasks(
   // Desired set, deduped by completable key (a task is open at most once; guard a page overlap / a
   // subject seen under two statuses mid-pass).
   const desiredByKey = new Map<string, UserTaskRow>();
+  // Keys auto-resumed from a durable adjudication this pass (issue #806). The reduced-capability scan
+  // visits each instance twice (direct + callActivity hierarchy), and both queries snapshot the task
+  // BEFORE the resume removes it, so the second visit would otherwise re-attempt a now-gone completion
+  // and fall through to projecting the very row we just retired. Recording the key keeps the resume
+  // one-shot and out of the inbox.
+  const resumedByKey = new Set<string>();
   const project = async (elementId: string | undefined, userTaskKey: string, processInstanceKey: string, rootProcessInstanceKey: string, formKey: string) => {
     if (!elementId) return;
     const rowKey = userTaskKey.trim();
-    if (!rowKey || desiredByKey.has(rowKey)) return;
+    if (!rowKey || desiredByKey.has(rowKey) || resumedByKey.has(rowKey)) return;
     const ctx = await contextFor(elementId, userTaskKey, processInstanceKey, rootProcessInstanceKey, formKey);
     if (!ctx) return;
+    // Durable adjudication auto-resume (issue #806): before surfacing a NEW convergence `wait-answer`
+    // to a human, check whether THIS PR already has a settled adjudication for the SAME question
+    // (canonical `questionFingerprint`). If it does, resume the loop with the recorded answer through
+    // the canonical `completeUserTaskAttributed` door — attributed to the prior adjudicator and marked
+    // `auto_applied` (a machine replay, reversible so a human can still override) so it is never
+    // laundered into a first-hand irreversible human authority (Copilot review of #806) — instead of
+    // re-parking a human on an already-answered question (PR #800 / proc 46310: the same design
+    // question escalated at round 2 and again at round 13). Scoped to the review loop's `wait-answer`
+    // on a real PR key; on any resolution failure the task still projects, so an un-resumable question
+    // always reaches a human (fail-open to the human).
+    if (elementId === PR_WAIT_ANSWER_ELEMENT && ctx.subjectType === "pr" && ctx.question && parsePr(ctx.subjectKey)) {
+      try {
+        // The adjudication LOOKUP lives inside this fail-open `try` (not just the resume) so a transient
+        // `pr_adjudications.find` error never rejects `project` and aborts `pollUserTasks` mid-pass — the
+        // task still projects and the question always reaches a human (SPEC: adjudication-resolution
+        // failures fail open to the human).
+        const adjudication = matchAdjudication(await prAdjudications(data).find({ pr_key: ctx.subjectKey }), ctx.question);
+        // Only auto-resume when the prior adjudicator's provenance is KNOWN. A settled row with a blank
+        // `adjudicated_by` (completed out of band, so `latestAdjudicator` returned no actor) must NOT be
+        // manufactured into a synthetic `human` actor — that would audit an unknown-provenance replay as
+        // a first-hand human decision. Fail open to a fresh human task instead (Copilot review of #806).
+        const adjudicatedBy = adjudication?.adjudicated_by?.trim();
+        if (adjudication && adjudicatedBy) {
+          const resumed = await completeEscalationAutoApplied(data, engine, {
+            userTaskKey: rowKey,
+            // The sweep already discovered this task's owning instance — hand it to the resolve so the
+            // auto-apply scans that ONE instance, not every open user task engine-wide (issue #806
+            // Copilot review: an unfiltered per-task scan makes a single poll pass O(N²) across N
+            // already-adjudicated PRs). `contextFor`/the sweep report the task's direct instance, so the
+            // filtered scan finds exactly this task; a miss still fails open to the human.
+            processInstanceKey,
+            variables: { answer: adjudication.answer },
+            actor: {
+              kind: adjudication.adjudicated_kind === "agent" ? "agent" : "human",
+              id: adjudicatedBy,
+            },
+            // Link the auto-apply back to the replayed adjudication (issue #806) so a human revert of the
+            // resulting completion invalidates this exact decision instead of it being silently re-applied.
+            adjudicationId: adjudication.id,
+          });
+          if (resumed.ok) {
+            resumedByKey.add(rowKey);
+            return;
+          }
+        }
+      } catch (err) {
+        console.error(`[poller] adjudication auto-resume (${ctx.subjectKey}): ${err}`);
+      }
+    }
     const row = buildUserTaskRow(ctx, at);
     if (row) desiredByKey.set(rowKey, row);
   };

package/app/terminalReaderBehaviour.test.ts

@@ -51,6 +51,27 @@ function memData(stores: Stores) {
   return {
     table: withTrackingViews((name: string, key: string) =>
       memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
+    // Emulates the atomic bulk `DELETE FROM "pr_adjudications" WHERE "pr_key" = ?` submitPr issues via
+    // `data.open().exec` to reset a reopened PR's adjudication memory (Copilot review of #806). The SQL
+    // is validated against real SQLite in app/adjudications.test.ts; here it need only mutate the store.
+    open: () => ({
+      exec: async (sql: string, params: any[] = []) => {
+        if (/DELETE FROM "pr_adjudications" WHERE "pr_key" = \?/.test(sql)) {
+          const store = stores.pr_adjudications;
+          let changed = 0;
+          if (store) {
+            for (let i = store.rows.length - 1; i >= 0; i--) {
+              if (store.rows[i].pr_key === params[0]) {
+                store.rows.splice(i, 1);
+                changed++;
+              }
+            }
+          }
+          return { changed };
+        }
+        throw new Error(`unexpected exec sql: ${sql}`);
+      },
+    }),
   } as any;
 }
 

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/db/migrations/109_pr_adjudications.sql

@@ -0,0 +1,61 @@
+-- 109_pr_adjudications.sql — issue #806: persist wait-answer human adjudications so an
+-- already-answered convergence question does not re-escalate.
+--
+-- The convergence loop's `wait-answer` escalation (`record-answer` → resume) applies a human's
+-- answer to the CURRENT round but keeps NO durable memory that "(this PR, this question) was already
+-- adjudicated to X". A stateless later round that re-derives the identical escalation condition
+-- re-parks a human from scratch (PR #800 / proc 46310: the same design question escalated at round 2
+-- and again at round 13, both answered identically). A human adjudication is NOT GitHub-derivable —
+-- it is a fact the app itself must remember — so it lives here, durably.
+--
+-- One row per (PR, question) a human has settled: `pr.answer-escalation` (record-answer) writes it on
+-- answering, and the poller (`pollUserTasks`) reads it before surfacing a NEW `wait-answer` — when the
+-- question's fingerprint matches an existing row it auto-resumes with the recorded answer (attributed
+-- to the prior adjudicator) instead of re-escalating a human.
+--
+--   • question_fingerprint — the canonical `normalizeAdvisoryText` + `fingerprint` digest of the
+--     escalation question (app/github.ts `questionFingerprint`), the SAME line-stable normalisation
+--     advisory acks use; so only a byte/semantic-identical, already-answered question is suppressed
+--     while a materially different question still escalates. No second fingerprint implementation.
+--   • answer / adjudicated_by / adjudicated_kind / adjudicated_at — the settled answer, who settled it,
+--     whether they were a `human` or an `agent` (ADR 0046), and when, so the auto-resume replays the
+--     exact decision AND preserves the original attribution kind — a human-settled decision replays as
+--     human, an agent-settled one as agent, so an auto-apply can never launder an agent decision into an
+--     irreversible human authority (Copilot review of #806).
+--   • invalidated_at — a TOMBSTONE set when a human REVERTS the auto-applied completion that replayed
+--     this decision (`revertAgentCompletion` → `invalidateAdjudication`, Copilot review of #806). A plain
+--     DELETE is NOT race-safe: the reverted completion's `record-answer` job can be redelivered
+--     (at-least-once) AFTER the delete and re-insert the SAME `(pr_key, question_fingerprint)`, so the
+--     next poller pass re-auto-applies and silently undoes the revert. Keeping the row as a tombstone lets
+--     the `UNIQUE (pr_key, question_fingerprint)` fence make that redelivered re-insert a no-op, and
+--     `matchAdjudication` skips a tombstoned row so it never auto-applies again. The tombstone is cleared
+--     only by `resetAdjudications` on a fresh-run re-submit. NULL for a live, replayable decision.
+--   • source_completion_id — the `task_completions.id` of the WINNING completion that produced this
+--     decision (issue #806 review). A FIRST-HAND agent answer to a `wait-answer` records its own durable
+--     adjudication (`adjudicated_kind="agent"`) but — unlike a machine auto-apply — its ledger row has
+--     `auto_applied=0` and NO `source_adjudication_id`, so a human revert of that reversible agent
+--     completion could not previously find and tombstone the decision it created, and the poller would
+--     re-auto-apply the reverted answer. Linking every convergence adjudication to its winning completion
+--     lets `revertAgentCompletion` invalidate the decision on ANY reversible agent revert, not only a
+--     machine replay (`invalidateAdjudicationByCompletion`). INSERT-if-absent, so only the ORIGINAL
+--     first-hand completion is recorded; a later auto-apply's re-record is a UNIQUE no-op that leaves the
+--     link pointing at the first-hand winner. NULL for a legacy/uncorrelated answer.
+--
+-- `UNIQUE (pr_key, question_fingerprint)` keeps one settled answer per (PR, question); the surrogate
+-- `id` PK gives the `Table<T>` gateway a single-column key. Forward-only, additive (expand). Numbered
+-- after the current highest committed prefix (104) in the pre-assigned 109–110 block (#806); the
+-- runner wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+CREATE TABLE IF NOT EXISTS pr_adjudications (
+  id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+  pr_key               TEXT NOT NULL REFERENCES pull_requests(pr_key),
+  question_fingerprint TEXT NOT NULL,
+  answer               TEXT,
+  adjudicated_by       TEXT,
+  adjudicated_kind     TEXT,
+  adjudicated_at       TEXT NOT NULL,
+  invalidated_at       TEXT,
+  source_completion_id INTEGER,
+  UNIQUE (pr_key, question_fingerprint)
+);
+CREATE INDEX IF NOT EXISTS idx_pradj_pr ON pr_adjudications(pr_key);
+CREATE INDEX IF NOT EXISTS idx_pradj_srccompletion ON pr_adjudications(source_completion_id);

package/db/migrations/110_task_completions_auto_applied.sql

@@ -0,0 +1,34 @@
+-- 110_task_completions_auto_applied.sql — issue #806 (Copilot review): mark an AUTO-APPLIED escalation
+-- completion so it is distinguishable from a fresh human/agent submission in the attribution ledger.
+--
+-- The convergence poller auto-resumes an already-answered `wait-answer` by replaying a durable
+-- adjudication through the SAME `completeUserTaskAttributed` door a human/agent uses (app/service.ts,
+-- issue #806). Without a marker that replay is INDISTINGUISHABLE from a real, first-hand submission in
+-- `task_completions`, and — recorded as an irreversible authority — it could launder an earlier
+-- agent-originated decision into an unchallengeable human one. `auto_applied=1` records "this
+-- completion is a machine replay of a prior decision, not a fresh submission"; the app also records
+-- such completions `reversible=1` so a human can always override an auto-applied answer.
+--
+-- Forward-only, additive (expand): a nullable-defaulted `ADD COLUMN`, so every existing completion
+-- reads back `auto_applied=0` (a genuine first-hand submission). Numbered after 109 in the pre-assigned
+-- 109–110 block (#806); the runner wraps each file in its own transaction, so no BEGIN/COMMIT here.
+ALTER TABLE task_completions ADD COLUMN auto_applied INTEGER NOT NULL DEFAULT 0;
+
+-- Link an AUTO-APPLIED escalation completion back to the durable adjudication it replayed (issue #806,
+-- Copilot review), so a human's revert of that completion can invalidate the exact decision. The
+-- convergence poller auto-resumes an already-answered `wait-answer` by replaying a `pr_adjudications`
+-- row through `completeEscalationAutoApplied` (app/service.ts); recording WHICH adjudication it replayed
+-- lets `revertAgentCompletion` tombstone that decision (`invalidateAdjudication`) so the revert becomes a
+-- real override — the next round re-parks a human — instead of the poller silently re-applying the same
+-- overridden answer. NULL for every first-hand (human/agent) submission and for legacy rows; only an
+-- auto-apply carries a source adjudication. Additive (expand): a nullable `ADD COLUMN`. Folded into this
+-- file to keep the whole change inside the pre-assigned 109–110 block (#806, Copilot review) rather than
+-- consuming an unallocated 111 prefix.
+ALTER TABLE task_completions ADD COLUMN source_adjudication_id INTEGER;
+
+-- `latestAdjudicator` (workers/answer-escalation) now looks a completion up by `process_instance_key`
+-- for every convergence answer, to correlate the settled adjudicator's attribution (#806). The ledger
+-- is append-only and only carried an index on `user_task_key` (026_agent_completion.sql), so that
+-- lookup would scan the whole completion history as the fleet grows. Index `process_instance_key` too
+-- (additive/expand — a new index, no existing shape touched).
+CREATE INDEX idx_task_completions_pik ON task_completions(process_instance_key);

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/completeUserTask.test.ts

@@ -80,7 +80,7 @@ test("complete-user-task: completes a plan-review escalation and drops its read-
   assertEquals(res.status, 200);
   assertEquals(res.body.ok, true);
   assertEquals(res.body.elementId, "plan-review-decision");
-  assertEquals(completed, [{ userTaskKey: "ut-1", variables: { directive: "revise", notes: "narrow scope" } }]);
+  assertEquals(completed, [{ userTaskKey: "ut-1", variables: { directive: "revise", notes: "narrow scope", completedUserTaskKey: "ut-1", completedCompletionId: 1 } }]);
   assertEquals(stores.user_tasks, []);
   // Attribution recorded as a human completion.
   assertEquals(stores.task_completions.length, 1);
@@ -93,7 +93,7 @@ test("complete-user-task: completes a trial-merge escalation with the typed acti
   const res = await call(app, { userTaskKey: "ut-2", variables: { action: "rebase" } });
 
   assertEquals(res.status, 200);
-  assertEquals(completed, [{ userTaskKey: "ut-2", variables: { action: "rebase" } }]);
+  assertEquals(completed, [{ userTaskKey: "ut-2", variables: { action: "rebase", completedUserTaskKey: "ut-2", completedCompletionId: 1 } }]);
 });
 
 test("complete-user-task: a missing userTaskKey is a 400", async () => {
@@ -120,7 +120,7 @@ test("complete-user-task: completes a feature-blocked acknowledgement with the t
   const res = await call(app, { userTaskKey: "ut-4", variables: { note: "reassigned" } });
   assertEquals(res.status, 200);
   assertEquals(res.body.elementId, "feature-blocked");
-  assertEquals(completed, [{ userTaskKey: "ut-4", variables: { note: "reassigned" } }]);
+  assertEquals(completed, [{ userTaskKey: "ut-4", variables: { note: "reassigned", completedUserTaskKey: "ut-4", completedCompletionId: 1 } }]);
 });
 
 test("complete-user-task: completes a feature-escalation answer (issue #332)", async () => {
@@ -128,7 +128,7 @@ test("complete-user-task: completes a feature-escalation answer (issue #332)", a
   const res = await call(app, { userTaskKey: "ut-6", variables: { resolution: "answer", answer: "use v2" } });
   assertEquals(res.status, 200);
   assertEquals(res.body.elementId, "feature-escalation");
-  assertEquals(completed, [{ userTaskKey: "ut-6", variables: { resolution: "answer", answer: "use v2" } }]);
+  assertEquals(completed, [{ userTaskKey: "ut-6", variables: { resolution: "answer", answer: "use v2", completedUserTaskKey: "ut-6", completedCompletionId: 1 } }]);
 });
 
 test("complete-user-task: refuses a non-completable internal user task (400)", async () => {
@@ -161,5 +161,5 @@ test("complete-user-task: a read-model cleanup failure does not mask a resumed c
 
   assertEquals(res.status, 200);
   assertEquals(res.body.ok, true);
-  assertEquals(completed, [{ userTaskKey: "ut-5", variables: { directive: "revise", notes: "narrow scope" } }]);
+  assertEquals(completed, [{ userTaskKey: "ut-5", variables: { directive: "revise", notes: "narrow scope", completedUserTaskKey: "ut-5", completedCompletionId: 1 } }]);
 });

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;
+  }
+});