@nanobpm/nano-workforce 0.188.0 → 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/implementReconcile.test.ts

@@ -0,0 +1,166 @@
+// Red-first coverage for the implement-cell reconcile decision (issue #801) — the implement-stage twin
+// of #796. The defect: an implement-step that returns NO machine-readable `status` but has an OPEN PR
+// on its `feat/<task.id>` branch was dead-ended at a human escalation instead of adopting that PR and
+// converging. These tests pin the canonical `ic_reconcile_gw` decision that reconciles from GitHub
+// before escalating.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { HeadPr } from "./github.ts";
+import {
+  implementCellBranch,
+  pickAdoptablePr,
+  reconcileImplement,
+  shouldReconcileImplement,
+} from "./implementReconcile.ts";
+
+const openPr = (number: number, base = "main"): HeadPr => ({
+  number,
+  url: `https://github.com/owner/repo/pull/${number}`,
+  state: "open",
+  baseRef: base,
+});
+
+test("implementCellBranch: the deterministic feat/<task.id> branch", () => {
+  assertEquals(implementCellBranch("issue-796"), "feat/issue-796");
+});
+
+test("shouldReconcileImplement: only a blank/absent status reconciles", () => {
+  assertEquals(shouldReconcileImplement(null), true);
+  assertEquals(shouldReconcileImplement(undefined), true);
+  assertEquals(shouldReconcileImplement("  "), true);
+  assertEquals(shouldReconcileImplement("escalated"), false);
+  assertEquals(shouldReconcileImplement("opened"), false);
+});
+
+test("pickAdoptablePr: the first OPEN PR wins; merged/closed are not adoptable", () => {
+  assertEquals(pickAdoptablePr(null), null);
+  assertEquals(pickAdoptablePr([]), null);
+  assertEquals(pickAdoptablePr([{ ...openPr(1), state: "merged" }]), null);
+  assertEquals(pickAdoptablePr([{ ...openPr(2), state: "closed" }, openPr(3)])?.number, 3);
+});
+
+test("pickAdoptablePr: a known baseBranch adopts only an open PR that targets it", () => {
+  // Multiple open PRs from the same head branch to different bases — only the one matching the
+  // run's pinned base is adoptable; a stale/wrong-base PR (even if first) is never adopted.
+  const prs = [openPr(10, "old-epic-base"), openPr(11, "epic/feat-x")];
+  assertEquals(pickAdoptablePr(prs, "epic/feat-x")?.number, 11);
+  // No open PR targets the pinned base → nothing adoptable (escalate rather than converge the wrong PR).
+  assertEquals(pickAdoptablePr([openPr(12, "some-other-base")], "epic/feat-x"), null);
+  // Whitespace-only base is treated as "unknown" → first-open fallback.
+  assertEquals(pickAdoptablePr([openPr(13, "main")], "  ")?.number, 13);
+});
+
+// The core defect reproduction: blank status + an open PR on the branch → adopt & converge, no escalation.
+test("reconcileImplement: blank status + open PR on feat/<task.id> → adopt (status=opened, pr set)", async () => {
+  const calls: Array<{ repo: string; branch: string }> = [];
+  const lookup = async (repo: string, branch: string): Promise<HeadPr[]> => {
+    calls.push({ repo, branch });
+    return [openPr(800)];
+  };
+  const res = await reconcileImplement(
+    { status: null, subjectKey: "nanobpm/nano-workforce#796", taskId: "issue-796" },
+    lookup,
+    "token",
+  );
+  assertEquals(res, { reconciled: true, status: "opened", pr: "nanobpm/nano-workforce#800" });
+  assertEquals(calls, [{ repo: "nanobpm/nano-workforce", branch: "feat/issue-796" }]);
+});
+
+test("reconcileImplement: blank status but NO branch/PR → escalate (unchanged behaviour)", async () => {
+  const res = await reconcileImplement(
+    { status: null, subjectKey: "owner/repo#7", taskId: "issue-7" },
+    async () => [],
+    "token",
+  );
+  assertEquals(res, { reconciled: false, status: null, pr: null });
+});
+
+test("reconcileImplement: a genuine escalation status is honoured, GitHub never consulted", async () => {
+  let consulted = false;
+  const res = await reconcileImplement(
+    { status: "escalated", subjectKey: "owner/repo#7", taskId: "issue-7" },
+    async () => {
+      consulted = true;
+      return [openPr(9)];
+    },
+    "token",
+  );
+  assertEquals(res, { reconciled: false, status: "escalated", pr: null });
+  assertEquals(consulted, false);
+});
+
+test("reconcileImplement: only merged/closed PRs on the branch → escalate (nothing in-flight to adopt)", async () => {
+  const res = await reconcileImplement(
+    { status: null, subjectKey: "owner/repo#7", taskId: "issue-7" },
+    async () => [{ ...openPr(5), state: "merged" }],
+    "token",
+  );
+  assertEquals(res.reconciled, false);
+});
+
+test("reconcileImplement: a lookup transport failure falls through to escalate (best-effort)", async () => {
+  const res = await reconcileImplement(
+    { status: null, subjectKey: "owner/repo#7", taskId: "issue-7" },
+    async () => {
+      throw new Error("github 502");
+    },
+    "token",
+  );
+  assertEquals(res, { reconciled: false, status: null, pr: null });
+});
+
+test("reconcileImplement: an existing pr is carried through unchanged on fall-through (never wiped)", async () => {
+  // A genuine escalation status → escalate; any pr already in scope must survive the re-emit.
+  const escalated = await reconcileImplement(
+    { status: "escalated", subjectKey: "owner/repo#7", taskId: "issue-7", pr: "owner/repo#42" },
+    async () => [],
+    "token",
+  );
+  assertEquals(escalated, { reconciled: false, status: "escalated", pr: "owner/repo#42" });
+
+  // Blank status but no adoptable PR → escalate; an existing pr still survives.
+  const noAdopt = await reconcileImplement(
+    { status: null, subjectKey: "owner/repo#7", taskId: "issue-7", pr: "owner/repo#42" },
+    async () => [],
+    "token",
+  );
+  assertEquals(noAdopt, { reconciled: false, status: null, pr: "owner/repo#42" });
+});
+
+test("reconcileImplement: a successful adoption overwrites any existing pr with the adopted key", async () => {
+  const res = await reconcileImplement(
+    { status: null, subjectKey: "owner/repo#7", taskId: "issue-7", pr: "owner/repo#42" },
+    async () => [openPr(99)],
+    "token",
+  );
+  assertEquals(res, { reconciled: true, status: "opened", pr: "owner/repo#99" });
+});
+
+test("reconcileImplement: with a pinned baseBranch, only a PR targeting it is adopted", async () => {
+  // The head branch carries two open PRs to different bases — adopt the one matching the run's base.
+  const adopt = await reconcileImplement(
+    { status: null, subjectKey: "owner/repo#7", taskId: "issue-7", baseBranch: "epic/feat-x" },
+    async () => [openPr(50, "stale-base"), openPr(51, "epic/feat-x")],
+    "token",
+  );
+  assertEquals(adopt, { reconciled: true, status: "opened", pr: "owner/repo#51" });
+
+  // Only a wrong-base PR exists → escalate rather than converge the wrong branch.
+  const escalate = await reconcileImplement(
+    { status: null, subjectKey: "owner/repo#7", taskId: "issue-7", baseBranch: "epic/feat-x", pr: "owner/repo#42" },
+    async () => [openPr(52, "stale-base")],
+    "token",
+  );
+  assertEquals(escalate, { reconciled: false, status: null, pr: "owner/repo#42" });
+});
+
+test("reconcileImplement: a missing taskId or unparseable subjectKey → escalate, no lookup", async () => {
+  let consulted = false;
+  const lookup = async (): Promise<HeadPr[]> => {
+    consulted = true;
+    return [openPr(1)];
+  };
+  assertEquals((await reconcileImplement({ status: null, subjectKey: "owner/repo#7", taskId: null }, lookup, "t")).reconciled, false);
+  assertEquals((await reconcileImplement({ status: null, subjectKey: "not-a-key", taskId: "issue-7" }, lookup, "t")).reconciled, false);
+  assertEquals(consulted, false);
+});

package/app/implementReconcile.ts

@@ -0,0 +1,112 @@
+// Implement-step reconcile — reconcile the implement-cell result from GitHub BEFORE escalating to a
+// human (issue #801).
+//
+// The shared `implement-cell` (resources/processes/implement-cell.bpmn) routes ANY implement-step
+// outcome that is not a clean terminal (`opened`/`blocked`/`skipped`) to a human escalation. But a
+// harness that returns NO machine-readable result envelope (a blank/absent `status`) can still have
+// pushed the slice's branch and opened a green PR — a machine-observable, recoverable outcome the
+// escalation question literally asked a human to go and check (#796's implement-stage twin). Dead-
+// ending that at a person is the defect.
+//
+// This is the CANONICAL, pure decision for the cell's reconcile step: on a blank/absent `status`,
+// look for an OPEN PR opened from the cell's deterministic branch (`feat/<task.id>`, the agent-guide
+// convention every implement-cell caller shares — see resources/prompts/feature.md) and, when one
+// exists, ADOPT it (derive `status = "opened"` + a `pr` key) so the run converges exactly as if the
+// agent had reported it — no human escalation. Only when nothing is observable does the run escalate
+// as today. The GitHub read is injected (the canonical `listPrsForHead`) so this stays a pure,
+// exhaustively testable mirror of the `ic_reconcile_gw` gateway — no second GitHub reconciler.
+import type { HeadPr } from "./github.ts";
+import { parsePr } from "./prParse.ts";
+
+/** The escalate-arm inputs the reconcile step reads from the implement-cell scope. `subjectKey` is the
+ *  cell's `owner/repo#N` subject (a feature run's `feature_key`, or a wave slice's epic `plan_key`) —
+ *  its `owner/repo` half is the repository to look in. `taskId` is `task.id`, which fixes the
+ *  deterministic implement branch `feat/<task.id>`. `status` is the (blank, on this arm) implement-step
+ *  status. `pr` is any PR key already in scope (the implement harness may have set it) — carried through
+ *  unchanged on the non-adopt fall-through so re-emitting the output never wipes it. `baseBranch` is the
+ *  run's pinned base branch (the epic/graph integration branch every implement-cell caller maps into the
+ *  cell scope): when known, only a PR whose base matches it is adoptable, so a stale/unrelated PR sharing
+ *  the deterministic head branch but targeting a different base is never adopted. */
+export interface ReconcileImplementInput {
+  status: unknown;
+  subjectKey: unknown;
+  taskId: unknown;
+  pr?: unknown;
+  baseBranch?: unknown;
+}
+
+/** The reconcile decision. `reconciled` is the `ic_reconcile_gw` gate: true → adopt-and-converge (with
+ *  `status = "opened"` + `pr` set); false → escalate as today. `status`/`pr` are re-emitted so the
+ *  cell (and its caller) route on the adopted values. */
+export interface ReconcileImplementResult {
+  reconciled: boolean;
+  status: string | null;
+  pr: string | null;
+}
+
+/** The injected GitHub read — the canonical `listPrsForHead(repo, headBranch, token)` (so this module
+ *  never grows a second PR-lookup transport). */
+export type OpenPrLookup = (repo: string, branch: string, token: string) => Promise<HeadPr[] | null>;
+
+const str = (v: unknown): string | undefined =>
+  typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+
+/** Reconcile ONLY when the agent left no machine-readable status (blank/absent) — the #796/#801
+ *  no-result condition. A genuine escalation that carries its own status string is honoured (escalate),
+ *  never silently overridden by a branch PR that may be unrelated to the agent's question. */
+export function shouldReconcileImplement(status: unknown): boolean {
+  return str(status) === undefined;
+}
+
+/** The cell's deterministic implement branch — `feat/<task.id>` (resources/prompts/feature.md). */
+export function implementCellBranch(taskId: string): string {
+  return `feat/${taskId}`;
+}
+
+/** The adoptable PR from a head-branch listing: the first OPEN one (a merged/closed PR on the branch is
+ *  not an in-flight result to converge). When `baseBranch` is given, only an open PR whose `baseRef`
+ *  matches it is adoptable — GitHub can carry multiple open PRs from one head branch to different bases,
+ *  so adopting blind to the base could converge a stale/unrelated PR; with no base known, fall back to
+ *  the first open PR (unchanged best-effort behaviour). `null` when the listing is absent (no transport)
+ *  or has no adoptable PR. */
+export function pickAdoptablePr(prs: HeadPr[] | null, baseBranch?: string): HeadPr | null {
+  if (!prs) return null;
+  const open = prs.filter((p) => p.state === "open");
+  const base = typeof baseBranch === "string" ? baseBranch.trim() : "";
+  if (base) return open.find((p) => p.baseRef === base) ?? null;
+  return open[0] ?? null;
+}
+
+/** The canonical implement-cell reconcile decision (mirror of `ic_reconcile_gw`). Best-effort: any
+ *  missing input, unusable transport, or lookup failure falls through to `escalate` — never worse than
+ *  today's behaviour, and idempotent (a pure GitHub read that adopts the SAME open PR on a re-run, so
+ *  a re-dispatch never opens or double-adopts a second PR). */
+export async function reconcileImplement(
+  input: ReconcileImplementInput,
+  lookup: OpenPrLookup,
+  token: string,
+): Promise<ReconcileImplementResult> {
+  const escalate: ReconcileImplementResult = {
+    reconciled: false,
+    status: str(input.status) ?? null,
+    // Carry any existing PR key through unchanged — the reconcile step's `pr` output is mapped back
+    // into the process variable, so returning a bare `null` here would wipe a `pr` the implement
+    // harness already set. Only a successful adoption below overwrites it.
+    pr: str(input.pr) ?? null,
+  };
+  if (!shouldReconcileImplement(input.status)) return escalate;
+  const taskId = str(input.taskId);
+  // `subjectKey` shares the `owner/repo#N` shape parsePr validates; we use only its `repo` half.
+  const parsed = parsePr(input.subjectKey);
+  if (!taskId || !parsed) return escalate;
+  const branch = implementCellBranch(taskId);
+  let prs: HeadPr[] | null;
+  try {
+    prs = await lookup(parsed.repo, branch, token);
+  } catch {
+    return escalate; // transport hiccup → escalate as today
+  }
+  const adopt = pickAdoptablePr(prs, str(input.baseBranch));
+  if (!adopt) return escalate;
+  return { reconciled: true, status: "opened", pr: `${parsed.repo}#${adopt.number}` };
+}

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