@nanobpm/nano-workforce 0.176.1 → 0.177.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.177.0](https://github.com/nanobpm/nano-workforce/compare/v0.176.1...v0.177.0) (2026-09-02)
+
+### Features
+
+* **agentic:** explicit claim registry drives cockpit jobKeys visibility ([#714](https://github.com/nanobpm/nano-workforce/issues/714)) ([173ae9f](https://github.com/nanobpm/nano-workforce/commit/173ae9f61ec23f1d5807517e24afe62d034de727)), closes [nano-ide#542](https://github.com/nanobpm/nano-ide/issues/542) [#713](https://github.com/nanobpm/nano-workforce/issues/713)
+
 ## [0.176.1](https://github.com/nanobpm/nano-workforce/compare/v0.176.0...v0.176.1) (2026-09-02)
 
 ### Bug Fixes

package/app/agentic/claim-registry.test.ts

@@ -0,0 +1,155 @@
+// Unit tests for the explicit job-ownership CLAIM registry (#713, upstream keystone nano-ide#542).
+//
+// The claim registry is the AUTHORITATIVE visibility source that replaces the fragile relay-derived
+// jobKeys. These tests pin: idempotent claim / release; the two derived-from-one-write projections
+// (instance→jobKeys and jobKey→owner) staying consistent across claim / re-claim (move) / release /
+// releaseInstance; the late/duplicate-release no-op; the presence `jobKeysFor` seam; the claim-keyed
+// drill `primaryStreamFor`; the reconnect-resync rebuild; the bounded-memory `reconcile`; and the
+// sorted snapshot. Mirrors `app/agentic/correlation.test.ts`.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  ClaimRegistry,
+  currentClaimRegistry,
+  setCurrentClaimRegistry,
+} from "./claim-registry.ts";
+
+test("claim records both projections; jobKeysFor and primaryStreamFor resolve against it", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["8420"]);
+  assert.equal(reg.ownerOf("8420"), "wk-a");
+  assert.equal(reg.isClaimed("8420"), true);
+  assert.equal(reg.primaryStreamFor("wk-a"), "job:8420");
+  assert.equal(reg.count(), 1);
+});
+
+test("claim is idempotent — a duplicate claim of the same {instance, jobKey} is a no-op re-assertion", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-a", "8420");
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["8420"]);
+  assert.equal(reg.count(), 1);
+});
+
+test("empty instance or jobKey is ignored (an empty value is invalid)", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("", "8420");
+  reg.claim("wk-a", "");
+  assert.equal(reg.count(), 0);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), []);
+  reg.release("", "8420");
+  reg.release("wk-a", "");
+  assert.equal(reg.count(), 0);
+});
+
+test("re-claiming a jobKey under a different instance MOVES it (drops the stale reverse edge)", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-b", "8420");
+  assert.deepEqual(reg.jobKeysFor("wk-a"), [], "the old owner no longer holds it");
+  assert.deepEqual(reg.jobKeysFor("wk-b"), ["8420"], "the new owner holds it");
+  assert.equal(reg.ownerOf("8420"), "wk-b");
+  assert.equal(reg.count(), 1, "a moved job never double-counts");
+});
+
+test("a worker can hold several claims; jobKeysFor is sorted and primaryStreamFor is the lowest", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-a", "8419");
+  reg.claim("wk-a", "8421");
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["8419", "8420", "8421"]);
+  assert.equal(reg.primaryStreamFor("wk-a"), "job:8419");
+});
+
+test("release clears one claim; a late / duplicate release is a no-op", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.release("wk-a", "8420");
+  assert.deepEqual(reg.jobKeysFor("wk-a"), []);
+  assert.equal(reg.isClaimed("8420"), false);
+  assert.equal(reg.count(), 0);
+  // Late / duplicate release — a no-op, never throws.
+  reg.release("wk-a", "8420");
+  // A release with no preceding claim — a no-op.
+  reg.release("wk-a", "9999");
+  assert.equal(reg.count(), 0);
+});
+
+test("release from a non-owner (the job already moved) is a strict no-op — it can't blank the live owner", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-b", "8420"); // moved to wk-b
+  reg.release("wk-a", "8420"); // stale release from the former owner
+  assert.deepEqual(reg.jobKeysFor("wk-b"), ["8420"], "the current owner's job is untouched");
+  assert.equal(reg.ownerOf("8420"), "wk-b");
+});
+
+test("releaseInstance clears every claim a worker holds", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-a", "8421");
+  reg.claim("wk-b", "8500");
+  reg.releaseInstance("wk-a");
+  assert.deepEqual(reg.jobKeysFor("wk-a"), []);
+  assert.equal(reg.isClaimed("8420"), false);
+  assert.equal(reg.isClaimed("8421"), false);
+  assert.deepEqual(reg.jobKeysFor("wk-b"), ["8500"], "another instance's claims survive");
+  reg.releaseInstance("nobody"); // unknown instance — no-op
+});
+
+test("reconnect-resync: re-register + re-claim rebuilds the same claim (never blanks a still-running job)", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  // A WS reconnect drops the connection but presence survives (keyed by instance); the supervisor
+  // re-claims every active jobKey. The idempotent claim leaves the jobKey in place across the churn.
+  reg.claim("wk-a", "8420");
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["8420"], "the jobKey never blanked across the reconnect");
+  assert.equal(reg.count(), 1);
+});
+
+test("reconcile drops claims for absent instances, keeps present ones, and reports the released", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-b", "8500");
+  reg.claim("wk-c", "8600");
+  const released = reg.reconcile(new Set(["wk-b"]));
+  assert.deepEqual(released.sort(), ["wk-a", "wk-c"]);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), []);
+  assert.deepEqual(reg.jobKeysFor("wk-c"), []);
+  assert.deepEqual(reg.jobKeysFor("wk-b"), ["8500"], "a present instance's claim survives");
+  assert.equal(reg.isClaimed("8420"), false);
+  assert.equal(reg.isClaimed("8500"), true);
+});
+
+test("primaryStreamFor / jobKeysFor for an unknown instance are undefined / empty", () => {
+  const reg = new ClaimRegistry();
+  assert.equal(reg.primaryStreamFor("nobody"), undefined);
+  assert.deepEqual(reg.jobKeysFor("nobody"), []);
+});
+
+test("snapshot is sorted by instance then jobKey and counts held claims", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-b", "8500");
+  reg.claim("wk-a", "8421");
+  reg.claim("wk-a", "8420");
+  const snap = reg.snapshot();
+  assert.deepEqual(snap.claims, [
+    { instance: "wk-a", jobKey: "8420" },
+    { instance: "wk-a", jobKey: "8421" },
+    { instance: "wk-b", jobKey: "8500" },
+  ]);
+  assert.equal(snap.count, 3);
+});
+
+test("currentClaimRegistry / setCurrentClaimRegistry install and clear the singleton", () => {
+  assert.equal(currentClaimRegistry(), undefined);
+  const reg = new ClaimRegistry();
+  setCurrentClaimRegistry(reg);
+  assert.equal(currentClaimRegistry(), reg);
+  setCurrentClaimRegistry(undefined);
+  assert.equal(currentClaimRegistry(), undefined);
+});

package/app/agentic/claim-registry.ts

@@ -0,0 +1,194 @@
+// nano-workforce — the explicit job-ownership CLAIM registry (#713, upstream keystone nano-ide#542).
+//
+// The authoritative source of "which jobs a worker instance is currently running", replacing the
+// fragile relay-DERIVED visibility it supersedes. Cockpit `jobKeys` used to be INFERRED from the
+// `job:<jobKey>` relay-terminal stream correlated to a worker via its CONNECTION id — a path that in
+// production went effectively dead (every live worker reported `jobKeys:[]` while actively running a
+// job) and that breaks by construction the moment one per-host supervisor multiplexes N workers over
+// a single connection (the instance can no longer be derived from `conn.id`).
+//
+// This registry fixes the failure MODE, not one instance of it: job ownership becomes a first-class,
+// EXPLICITLY-attributed fact carried by `claim` / `release` frames (wire codes 8/9, added to
+// `@nanobpm/agentic` by nano-ide#542). Each frame names its OWNING `instance` explicitly, so one
+// connection can carry the ownership frames of many distinct workers. A worker that holds a claim
+// reads "working" even with ZERO transcript — visibility no longer depends on terminal bytes landing
+// or correlating.
+//
+// Relationship to the correlation registry (`./correlation.ts`): correlation is DEMOTED to drill-in
+// context only (the process-instance / plan a terminal belongs to, keyed by jobKey). This registry —
+// keyed by the frame's explicit `instance` — is the visibility source the supply snapshot's
+// `jobKeysFor` seam resolves against. The two are distinct signals: presence "connected" and job
+// "claimed" must not be conflated (a live channel is not an observed agent).
+//
+// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+// is untouched — a claim is an app-side ownership announcement on the agentic channel, not a new wire
+// type on the job protocol; ADVISORY — the registry is a read-only visibility source and NEVER
+// hard-locks or gates a BPMN sequence flow.
+
+import { jobStream } from "./correlation.ts";
+
+/** One ownership record: a worker instance's claim over a job. */
+export interface Claim {
+  /** The owning worker instance (carried EXPLICITLY in the frame, never inferred from a connection). */
+  readonly instance: string;
+  /** The Camunda-8 job key the instance owns. */
+  readonly jobKey: string;
+}
+
+/** The read-only claim snapshot: every currently-held claim, sorted by instance then jobKey. */
+export interface ClaimSnapshot {
+  readonly claims: readonly Claim[];
+  readonly count: number;
+}
+
+/**
+ * The advisory in-memory job-ownership registry. It holds two derived-from-one-write projections of
+ * the same `claim` call: `instance → jobKeys` (the presence resolver) and `jobKey → instance` (the
+ * owner lookup, so `release` and a re-claim can move a job cleanly). A jobKey is owned by at most one
+ * instance at a time; re-claiming it under a different instance MOVES it (dropping the stale reverse
+ * edge) so a re-dispatched job never double-counts. Every mutation is idempotent, matching the wire
+ * contract: a duplicate `claim` is a no-op re-assertion; a duplicate or late `release` is a no-op.
+ *
+ * It needs no durable backing: claims are ephemeral and re-announced. On a WS reconnect the supervisor
+ * re-`register`s every worker and re-`claim`s every active jobKey, so the registry is rebuilt from that
+ * full-state resync — which is exactly what makes it survive the reconnect that the old relay-derived
+ * path stranded the jobKey across.
+ */
+export class ClaimRegistry {
+  /** worker instance → the set of jobKeys it currently owns (insertion-ordered). */
+  readonly #jobsOf = new Map<string, Set<string>>();
+  /** jobKey → the worker instance that currently owns it. */
+  readonly #ownerOf = new Map<string, string>();
+
+  /**
+   * Record that `instance` now OWNS `jobKey` (the authoritative ownership window opens). Idempotent:
+   * a repeat claim of the same `{ instance, jobKey }` is a no-op re-assertion. If the jobKey is
+   * currently owned by a DIFFERENT instance, it MOVES to the new owner (the stale reverse edge is
+   * dropped) — a re-dispatched or reconnected-under-new-instance job never double-counts. Both args
+   * must be non-empty; an empty value is ignored.
+   */
+  claim(instance: string, jobKey: string): void {
+    if (instance === "" || jobKey === "") return;
+    const previousOwner = this.#ownerOf.get(jobKey);
+    if (previousOwner === instance) return; // idempotent re-assertion
+    if (previousOwner !== undefined) {
+      this.#jobsOf.get(previousOwner)?.delete(jobKey);
+      this.#pruneInstance(previousOwner);
+    }
+    this.#ownerOf.set(jobKey, instance);
+    const jobs = this.#jobsOf.get(instance) ?? new Set<string>();
+    jobs.add(jobKey);
+    this.#jobsOf.set(instance, jobs);
+  }
+
+  /**
+   * Release `instance`'s claim over `jobKey` (the ownership window closes — the job finished, failed,
+   * or moved on). Idempotent and a strict no-op unless `instance` is the CURRENT owner: a duplicate or
+   * late `release`, a `release` with no preceding `claim`, or a `release` from an instance that no
+   * longer owns the job (it already moved to another owner) all leave the registry untouched — so a
+   * stale release can never blank a still-running job another instance now owns.
+   */
+  release(instance: string, jobKey: string): void {
+    if (instance === "" || jobKey === "") return;
+    if (this.#ownerOf.get(jobKey) !== instance) return;
+    this.#ownerOf.delete(jobKey);
+    this.#jobsOf.get(instance)?.delete(jobKey);
+    this.#pruneInstance(instance);
+  }
+
+  /**
+   * Release EVERY claim a worker instance holds (e.g. its supervisor connection dropped, or presence
+   * aged it out). No-op for an unknown instance.
+   */
+  releaseInstance(instance: string): void {
+    const jobs = this.#jobsOf.get(instance);
+    if (!jobs) return;
+    for (const jobKey of jobs) this.#ownerOf.delete(jobKey);
+    this.#jobsOf.delete(instance);
+  }
+
+  /**
+   * Drop every claim whose owning instance is NOT in `presentInstances` — the bounded-memory
+   * reconcile a maintenance tick drives against the live presence set, so a departed supervisor's
+   * claims do not linger. A reconnecting worker keeps its presence row (presence is keyed by instance
+   * across reconnects), so this never drops a mid-job reconnect's claim; a truly-exited worker loses
+   * its presence row and its claims are reclaimed here. Returns the released instance ids. This is a
+   * safety net, not the primary path — `release` frames and reconnect-resync are.
+   */
+  reconcile(presentInstances: ReadonlySet<string>): string[] {
+    const released: string[] = [];
+    for (const instance of [...this.#jobsOf.keys()]) {
+      if (!presentInstances.has(instance)) {
+        this.releaseInstance(instance);
+        released.push(instance);
+      }
+    }
+    return released;
+  }
+
+  /**
+   * The jobKeys a worker instance currently owns, sorted for a stable render. This is the resolver
+   * injected into {@link PresenceRegistry.snapshot}'s `jobKeysFor` seam — the visibility source the
+   * supply feed / cockpit reads (superseding the relay correlation).
+   */
+  jobKeysFor(instance: string): string[] {
+    const jobs = this.#jobsOf.get(instance);
+    return jobs ? [...jobs].sort((a, b) => a.localeCompare(b)) : [];
+  }
+
+  /**
+   * The jobKey-scoped relay stream a worker's terminal should drill into: its lowest-sorted current
+   * claim's stream (`job:<jobKey>`). A worker runs one job at a time in this fleet, but sorting keeps
+   * it stable if it ever holds several. Undefined when the worker holds no claim — the caller then
+   * falls back to the instance-keyed stream. This is the "relay demoted to drill-in, keyed by the
+   * CLAIM (not by `instanceForConnection`)" seam.
+   */
+  primaryStreamFor(instance: string): string | undefined {
+    const [first] = this.jobKeysFor(instance);
+    return first === undefined ? undefined : jobStream(first);
+  }
+
+  /** Whether any instance currently owns `jobKey`. */
+  isClaimed(jobKey: string): boolean {
+    return this.#ownerOf.has(jobKey);
+  }
+
+  /** The instance currently owning `jobKey`, or undefined when it is unclaimed. */
+  ownerOf(jobKey: string): string | undefined {
+    return this.#ownerOf.get(jobKey);
+  }
+
+  /** The number of currently-held claims. */
+  count(): number {
+    return this.#ownerOf.size;
+  }
+
+  /** The read-only claim snapshot: every held claim, sorted by instance then jobKey. */
+  snapshot(): ClaimSnapshot {
+    const claims: Claim[] = [];
+    for (const [instance, jobs] of this.#jobsOf) {
+      for (const jobKey of jobs) claims.push({ instance, jobKey });
+    }
+    claims.sort((a, b) => a.instance.localeCompare(b.instance) || a.jobKey.localeCompare(b.jobKey));
+    return { claims, count: claims.length };
+  }
+
+  /** Drop a worker's reverse-edge entry once it holds no more claims, so the map stays bounded. */
+  #pruneInstance(instance: string): void {
+    const jobs = this.#jobsOf.get(instance);
+    if (jobs && jobs.size === 0) this.#jobsOf.delete(instance);
+  }
+}
+
+/** The live claim registry from the most recent mount, so the supply report (H5) can read it. */
+let currentRegistry: ClaimRegistry | undefined;
+
+/** The mounted claim registry, or undefined before mount / after teardown. */
+export function currentClaimRegistry(): ClaimRegistry | undefined {
+  return currentRegistry;
+}
+
+/** Install the live registry (called by the claim family's `mount`). */
+export function setCurrentClaimRegistry(registry: ClaimRegistry | undefined): void {
+  currentRegistry = registry;
+}

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

@@ -0,0 +1,196 @@
+// Unit tests for the agentic `claim` / `release` job-ownership family (#713).
+//
+// Drives REAL `claim` / `release` frames through a live AgenticHub over an in-memory transport —
+// exactly as the presence family is exercised — so the singleton the supply operation reads is the
+// live one. Pins: mount attaches the two handlers and installs the registry singleton; a `claim`
+// populates jobKeys with ZERO transcript; ONE connection attributes N distinct instances by the
+// frame's EXPLICIT `instance` (never `conn.id`); `release` clears it and a late/duplicate release is a
+// no-op; a reconnect re-`claim` never blanks a still-running job; a malformed payload is rejected
+// without touching the registry; teardown clears the singleton.
+import { test } from "node:test";
+import { AgenticHub } from "@nanobpm/agentic/channel";
+import type { Authenticator, ChannelConnection, ChannelTransport } from "@nanobpm/agentic/channel";
+import { encodeFrame, type Frame } from "@nanobpm/agentic/protocol";
+import { assert, assertEquals } from "#test-assert";
+import { noopLog } from "../../../test/log.ts";
+import { currentClaimRegistry } from "../claim-registry.ts";
+import type { AgenticContext } from "../registry.ts";
+import { CLAIM_FAMILY, family, RELEASE_FAMILY } from "./claim.family.ts";
+
+interface FakeConn {
+  readonly conn: ChannelConnection;
+  feed(frame: Frame): void;
+}
+
+function fakeConn(id: string, identity: string): FakeConn {
+  let onMessage: ((bytes: Uint8Array) => void) | undefined;
+  const conn: ChannelConnection = {
+    id,
+    handshake: { query: { identity }, token: "t", credential: "c" },
+    send: () => {},
+    close: () => {},
+    onMessage: (l) => { onMessage = l; },
+    onClose: () => {},
+  };
+  return { conn, feed: (frame) => onMessage?.(encodeFrame(frame)) };
+}
+
+function memTransport(): { transport: ChannelTransport; connect(conn: ChannelConnection): void } {
+  let onConnection: ((conn: ChannelConnection) => void) | undefined;
+  const transport: ChannelTransport = {
+    onConnection: (l) => { onConnection = l; },
+    address: { port: 0 },
+    close: async () => {},
+  };
+  return { transport, connect: (conn) => onConnection?.(conn) };
+}
+
+const authenticator: Authenticator = (req) => ({ ok: true, grant: { identity: req.query?.identity ?? "anon" } });
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+
+function claimFrame(instance: string, jobKey: string): Frame {
+  return { lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance, jobKey } };
+}
+function releaseFrame(instance: string, jobKey: string): Frame {
+  return { lane: "control", family: RELEASE_FAMILY, seq: 1, payload: { instance, jobKey } };
+}
+
+function mountClaim(): { hub: AgenticHub; transport: ReturnType<typeof memTransport> } {
+  const transport = memTransport();
+  const hub = new AgenticHub({ transport: transport.transport, authenticator, sweepIntervalMs: 0 });
+  const ctx: AgenticContext = {
+    hub,
+    registry: hub.registry,
+    transport: transport.transport as never,
+    data: undefined,
+    log: noopLog(),
+  };
+  family.mount(ctx);
+  return { hub, transport };
+}
+
+test("mount attaches the claim and release handlers and installs the registry singleton", () => {
+  const { hub } = mountClaim();
+  try {
+    assertEquals(hub.router.families().sort(), ["claim", "release"]);
+    assert(currentClaimRegistry() !== undefined, "the claim family installs the singleton");
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a claim populates the worker's jobKeys with ZERO transcript (visibility no longer needs the relay)", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "leafA");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg, "registry mounted");
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"]);
+    assertEquals(reg.primaryStreamFor("wk-a"), "job:8420", "the drill stream repoints at the claimed job");
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("ONE connection attributes N distinct instances by the frame's EXPLICIT instance (never conn.id)", async () => {
+  const { transport } = mountClaim();
+  try {
+    // A single per-host supervisor multiplexes two workers over ONE connection.
+    const supervisor = fakeConn("c1", "host-supervisor");
+    transport.connect(supervisor.conn);
+    await flush();
+    supervisor.feed(claimFrame("wk-a", "8420"));
+    supervisor.feed(claimFrame("wk-b", "8500"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "attributed to the frame's instance, not the connection");
+    assertEquals(reg.jobKeysFor("wk-b"), ["8500"]);
+    assertEquals(reg.count(), 2);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("release clears the jobKey; a late / duplicate release is a no-op", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "leafA");
+    transport.connect(peer.conn);
+    await flush();
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+    peer.feed(releaseFrame("wk-a", "8420"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), []);
+    // Late / duplicate release — a no-op, never throws or wedges the handler.
+    peer.feed(releaseFrame("wk-a", "8420"));
+    await flush();
+    assertEquals(reg.count(), 0);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("reconnect-resync: a mid-job re-claim over a fresh connection never blanks the still-running job", async () => {
+  const { transport } = mountClaim();
+  try {
+    const first = fakeConn("c1", "leafA");
+    transport.connect(first.conn);
+    await flush();
+    first.feed(claimFrame("wk-a", "8420"));
+    await flush();
+
+    // The WS reconnects on a new connection; the supervisor re-claims every active jobKey.
+    const second = fakeConn("c2", "leafA");
+    transport.connect(second.conn);
+    await flush();
+    second.feed(claimFrame("wk-a", "8420"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"], "the jobKey survived the reconnect");
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("a malformed claim payload is rejected without touching the registry (advisory, connection kept)", async () => {
+  const { transport } = mountClaim();
+  try {
+    const peer = fakeConn("c1", "leafA");
+    transport.connect(peer.conn);
+    await flush();
+    // Missing jobKey → validatePayload rejects it.
+    peer.feed({ lane: "control", family: CLAIM_FAMILY, seq: 1, payload: { instance: "wk-a" } });
+    await flush();
+    // A well-formed claim still works afterwards — the handler was not wedged.
+    peer.feed(claimFrame("wk-a", "8420"));
+    await flush();
+
+    const reg = currentClaimRegistry();
+    assert(reg);
+    assertEquals(reg.jobKeysFor("wk-a"), ["8420"]);
+    assertEquals(reg.count(), 1);
+  } finally {
+    family.teardown?.();
+  }
+});
+
+test("teardown clears the singleton", () => {
+  mountClaim();
+  assert(currentClaimRegistry() !== undefined);
+  family.teardown?.();
+  assertEquals(currentClaimRegistry(), undefined);
+});

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

@@ -0,0 +1,148 @@
+// nano-workforce — the agentic-channel `claim` / `release` job-ownership family (#713).
+//
+// H0 (#143) seam plug-in: ONE new file under `app/agentic/families/`, discovered by the loader's
+// `*.family.ts` convention and mounted by the seam — it never edits `main.ts`, `drainAndExit`, or any
+// shared boot line. It owns the `claim` (wire code 8) and `release` (wire code 9) message families —
+// the explicit job-ownership frames nano-ide#542 appended to `@nanobpm/agentic` — attaching each
+// handler through the hub's `registerFamilyHandler` seam (one family, one owning module), never a
+// shared dispatch switch.
+//
+// What it gives the fleet: a first-class {@link ClaimRegistry} (`instance → set<jobKey>`) that becomes
+// the AUTHORITATIVE source the supply snapshot reads for `jobKeys` — replacing the fragile
+// relay-derived visibility. Each frame carries its OWNING `instance` EXPLICITLY, so attribution reads
+// the frame, NOT the connection id (`conn.id`); that is what lets one per-host supervisor multiplex N
+// distinct workers' ownership over a single connection. On a reconnect the supervisor re-`register`s
+// every worker and re-`claim`s every active jobKey, and the (idempotent) claim handler rebuilds the
+// registry from that resync.
+//
+// Liveness: a worker holding a claim reads "working" even with ZERO transcript — visibility no longer
+// depends on terminal bytes landing/correlating. A bounded-memory maintenance tick reconciles the
+// claim registry against the live presence set so a departed supervisor's claims are reclaimed (the
+// `release` frame is the primary clear; this is the safety net for an unclean drop).
+//
+// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+// is untouched; ADVISORY — the registry is a read-only visibility source and NEVER gates a BPMN
+// sequence flow.
+import type { HubConnection } from "@nanobpm/agentic/channel";
+import { type Frame, validatePayload } from "@nanobpm/agentic/protocol";
+import { ClaimRegistry, setCurrentClaimRegistry } from "../claim-registry.ts";
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+import { currentPresenceRegistry } from "./presence.family.ts";
+
+/** The message-family names this module owns (the two ownership frames). */
+export const CLAIM_FAMILY = "claim";
+export const RELEASE_FAMILY = "release";
+
+/** The reconcile tick runs at a third of the presence TTL — matching the presence-maintenance cadence. */
+const SWEEP_DIVISOR = 3;
+/** Fallback reconcile cadence when no presence registry is mounted to source a TTL. */
+const DEFAULT_RECONCILE_MS = 10_000;
+
+/** Read a string property from an unknown frame payload, or undefined when absent / non-string. */
+function readString(value: unknown, key: string): string | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  if (!Object.hasOwn(value, key)) return undefined;
+  const field = Object.getOwnPropertyDescriptor(value, key)?.value;
+  return typeof field === "string" ? field : undefined;
+}
+
+interface MountState {
+  readonly registry: ClaimRegistry;
+  timer: ReturnType<typeof setTimeout> | undefined;
+  stopped: boolean;
+}
+
+let state: MountState | undefined;
+
+/**
+ * The `claim` / `release` family module. `mount` installs a fresh {@link ClaimRegistry} as the
+ * process-wide singleton, attaches the two frame handlers via the S1 seam, and starts ONE bounded
+ * reconcile tick. `teardown` stops the tick, detaches nothing (the hub owns handler lifetime for the
+ * remount-guarded test path) and clears the singleton.
+ */
+export const family: AgenticFamily = {
+  name: CLAIM_FAMILY,
+
+  mount(ctx: AgenticContext): void {
+    const registry = new ClaimRegistry();
+    setCurrentClaimRegistry(registry);
+
+    // `claim` opens the ownership window; `release` closes it. Attribution reads the frame's EXPLICIT
+    // `instance` — never `conn.id` — so one connection can carry many instances' ownership frames. A
+    // malformed payload is rejected before it touches the registry (advisory: logged, connection
+    // kept). Both mutations are idempotent, matching the wire contract.
+    ctx.hub.registerFamilyHandler(CLAIM_FAMILY, (frame: Frame, _conn: HubConnection) => {
+      const result = validatePayload(CLAIM_FAMILY, frame.payload);
+      if (!result.ok) {
+        ctx.log.warn("agentic claim: malformed payload", { errors: result.errors.map((e) => e.code) });
+        return;
+      }
+      const instance = readString(frame.payload, "instance");
+      const jobKey = readString(frame.payload, "jobKey");
+      if (!instance || !jobKey) return;
+      registry.claim(instance, jobKey);
+    });
+
+    ctx.hub.registerFamilyHandler(RELEASE_FAMILY, (frame: Frame, _conn: HubConnection) => {
+      const result = validatePayload(RELEASE_FAMILY, frame.payload);
+      if (!result.ok) {
+        ctx.log.warn("agentic release: malformed payload", { errors: result.errors.map((e) => e.code) });
+        return;
+      }
+      const instance = readString(frame.payload, "instance");
+      const jobKey = readString(frame.payload, "jobKey");
+      if (!instance || !jobKey) return;
+      registry.release(instance, jobKey);
+    });
+
+    // Bounded-memory reconcile: drop claims whose owning instance no longer has a presence row (a
+    // dropped supervisor / aged-out worker). BOTH the drop-set AND the cadence are recomputed per
+    // tick from the live presence registry via a self-rescheduling timer, so the reconcile is truly
+    // independent of family mount order: whether presence mounts before or after this family, once it
+    // is present each tick reclaims absent instances' claims AND adjusts its cadence to the real TTL
+    // (a fixed-at-mount interval would stay pinned to the fallback cadence when claim mounts first).
+    // Advisory — a fault is logged, never thrown, and the tick never keeps the process alive on its
+    // own.
+    const reconcileMs = (): number => {
+      const presenceTtl = currentPresenceRegistry()?.ttlMs;
+      return Math.max(1, Math.floor((presenceTtl ?? DEFAULT_RECONCILE_MS) / SWEEP_DIVISOR));
+    };
+    const schedule = (): void => {
+      if (!state || state.stopped) return;
+      const timer = setTimeout(tick, reconcileMs());
+      timer.unref?.();
+      state.timer = timer;
+    };
+    const tick = () => {
+      try {
+        const presence = currentPresenceRegistry();
+        if (presence) {
+          const present = new Set(presence.registeredWorkers().map((w) => w.instance));
+          const released = registry.reconcile(present);
+          if (released.length > 0) {
+            ctx.log.info("agentic claim reconcile released absent instances", { released: released.length });
+          }
+        }
+        // else: no presence source → keep claims until one mounts (resync repopulates)
+      } catch (err) {
+        ctx.log.warn("agentic claim reconcile failed", { err: String(err) });
+      }
+      schedule();
+    };
+
+    state = { registry, timer: undefined, stopped: false };
+    schedule();
+    ctx.log.info("agentic claim family mounted", { families: [CLAIM_FAMILY, RELEASE_FAMILY] });
+  },
+
+  teardown(): void {
+    if (state) {
+      state.stopped = true;
+      if (state.timer !== undefined) clearTimeout(state.timer);
+    }
+    state = undefined;
+    setCurrentClaimRegistry(undefined);
+  },
+};
+
+export default family;

package/operations/getAgenticSupply.test.ts

@@ -12,7 +12,9 @@ import { encodeFrame, type Frame } from "@nanobpm/agentic/protocol";
 import type { SqliteDb } from "@nanobpm/agentic/presence";
 import type { AppApi, DataLayer } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
+import { currentClaimRegistry } from "../app/agentic/claim-registry.ts";
 import { currentCorrelation } from "../app/agentic/correlation.ts";
+import { family as claimFamily } from "../app/agentic/families/claim.family.ts";
 import { family as correlationFamily } from "../app/agentic/families/correlation.family.ts";
 import { family } from "../app/agentic/families/presence.family.ts";
 import type { AgenticContext } from "../app/agentic/registry.ts";
@@ -154,7 +156,32 @@ test("shared-secret guard rejects a missing secret when configured", async () =>
   }
 });
 
-test("H6: with the correlation family mounted, jobKeys populate, stream repoints, and correlations are reported", async () => {
+test("#713: a claim populates jobKeys and repoints the drill stream with ZERO transcript (claim is the visibility source)", async () => {
+  const hub = await mountPresence(memSqlite());
+  const ctx: AgenticContext = { hub, registry: hub.registry, transport: undefined as never, data: undefined, log: noopLog() };
+  claimFamily.mount(ctx);
+  const claims = currentClaimRegistry();
+  assert(claims !== undefined, "the claim family installs the singleton");
+  // An explicit claim — no relay produce frame, no correlation link, zero transcript.
+  claims.claim("wk-a", "8420");
+  try {
+    const res = (await handler(input(), app)) as {
+      status: number;
+      body: { workers: Array<Record<string, unknown>>; correlations: unknown[] };
+    };
+    assertEquals(res.status, 200);
+    const w = res.body.workers[0];
+    assertEquals(w.jobKeys, ["8420"], "the claim registry feeds the jobKeys seam");
+    assertEquals(w.stream, "job:8420", "the drill stream repoints at the claimed job, keyed by the claim");
+    assertEquals(res.body.correlations.length, 0, "no correlation context until a terminal lands (drill-in only)");
+  } finally {
+    claimFamily.teardown?.();
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("#713: the correlation registry is demoted to drill-in context — a link alone no longer feeds jobKeys", async () => {
   const hub = await mountPresence(memSqlite());
   correlationFamily.mount({
     hub,
@@ -165,6 +192,7 @@ test("H6: with the correlation family mounted, jobKeys populate, stream repoints
   });
   const correlation = currentCorrelation();
   assert(correlation !== undefined, "the correlation family installs the singleton");
+  // A correlation link (drill-in context) WITHOUT a claim: visibility must NOT light up from it.
   correlation.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "o/r#142" });
   try {
     const res = (await handler(input(), app)) as {
@@ -176,8 +204,9 @@ test("H6: with the correlation family mounted, jobKeys populate, stream repoints
     };
     assertEquals(res.status, 200);
     const w = res.body.workers[0];
-    assertEquals(w.jobKeys, ["6494"], "the correlation registry feeds the jobKeys seam");
-    assertEquals(w.stream, "job:6494", "the drill stream repoints at the live job's stream");
+    assertEquals(w.jobKeys, [], "correlation alone no longer feeds jobKeys (relay demoted)");
+    assertEquals(w.stream, "wk-a", "the drill stream stays instance-keyed without a claim");
+    // The correlation context is still reported for drill-in.
     assertEquals(res.body.correlations.length, 1);
     const c = res.body.correlations[0];
     assertEquals(c.jobKey, "6494");

package/operations/getAgenticSupply.ts

@@ -3,11 +3,14 @@
 // worker list — family, host, current jobs, liveness — grouped by leaf token, sourced from the H1
 // presence registry (#144). Read-only projection; it NEVER gates control flow (advisory-only, ADR 0056).
 //
-// H6 (#149) closes the loop: the correlation registry (`app/agentic/correlation.ts`) supplies the
-// `jobKeysFor` resolver the presence snapshot exposes as a seam, so each worker's current jobKeys light
-// up; each worker's drill `stream` is repointed at its jobKey-scoped relay stream (`job:<jobKey>`); and
-// the report carries the `correlations` — the process-instance / plan context for every current job —
-// so the cockpit lines a worker's terminal up with "that process instance / this plan".
+// H6/#713 closes the loop with an EXPLICIT claim registry (`app/agentic/claim-registry.ts`): it is the
+// AUTHORITATIVE source the presence snapshot's `jobKeysFor` seam resolves against, so each worker's
+// current jobKeys light up from `claim` frames — not inferred from the relay terminal — and appear even
+// with ZERO transcript. Each worker's drill `stream` is repointed at its claimed jobKey-scoped relay
+// stream (`job:<jobKey>`), keyed by the CLAIM (explicit instance+jobKey), not by a connection. The
+// relay correlation registry is DEMOTED to drill-in context only: it still supplies the `correlations`
+// — the process-instance / plan context for a job's terminal — so the cockpit lines a worker's terminal
+// up with "that process instance / this plan", but it is no longer the visibility source.
 //
 // This is the supply half of the visibility plane only. The demand×supply matrix, missing-agent-type
 // reds, and diversity-SLO lights are DE-SCOPED to the enrolment epic #152 — this report carries no
@@ -16,7 +19,8 @@
 // The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`): when
 // NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset → open.
 
-import { type CorrelationRegistry, currentCorrelation, type JobCorrelation } from "../app/agentic/correlation.ts";
+import { type ClaimRegistry, currentClaimRegistry } from "../app/agentic/claim-registry.ts";
+import { currentCorrelation, type JobCorrelation } from "../app/agentic/correlation.ts";
 import { currentPresenceRegistry, type SupplyWorker } from "../app/agentic/families/presence.family.ts";
 import { envVar } from "../app/version.ts";
 import type { AgenticJobCorrelation, AgenticSupplyReport, AgenticSupplyWorker } from "../nano-generated/api-io.d.ts";
@@ -27,13 +31,14 @@ import { defineOperation } from "../nano-generated/operations.ts";
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
 // Project a presence-registry row to the wire worker. The drill `stream` defaults to the worker
-// instance (H5) but is repointed at the worker's jobKey-scoped relay stream (`job:<jobKey>`) when the
-// correlation registry knows a current job for it (H6) — so drilling in opens the LIVE job's terminal.
-function toWorker(w: SupplyWorker, correlation: CorrelationRegistry | undefined): AgenticSupplyWorker {
+// instance (H5) but is repointed at the worker's claimed jobKey-scoped relay stream (`job:<jobKey>`)
+// when the claim registry knows a current claim for it (#713) — keyed by the CLAIM, not by the
+// connection — so drilling in opens the LIVE job's terminal even before any transcript lands.
+function toWorker(w: SupplyWorker, claims: ClaimRegistry | undefined): AgenticSupplyWorker {
   const out: AgenticSupplyWorker = {
     instance: w.instance,
     identity: w.identity,
-    stream: correlation?.primaryStreamFor(w.instance) ?? w.instance,
+    stream: claims?.primaryStreamFor(w.instance) ?? w.instance,
     jobKeys: [...w.jobKeys],
     live: w.live,
     staleMs: w.staleMs,
@@ -67,15 +72,19 @@ export default defineOperation("getAgenticSupply", async ({ req }, app) => {
     return { status: 200, body: empty };
   }
 
-  // Thread the H6 correlation registry (if mounted) as the presence snapshot's jobKeysFor resolver so a
-  // worker's current jobKeys populate; absent → jobKeys stay empty (advisory, never an error).
+  // #713: the CLAIM registry (if mounted) is the authoritative `jobKeysFor` source the presence
+  // snapshot resolves against — a worker's current jobKeys come from explicit `claim` frames, not the
+  // relay terminal, so they populate with zero transcript. Absent → jobKeys stay empty (advisory).
+  const claims = currentClaimRegistry();
+  // The correlation registry is demoted to drill-in context only: it still carries the per-job
+  // process-instance / plan context surfaced in `correlations`, but no longer feeds visibility.
   const correlation = currentCorrelation();
-  const snapshot = registry.snapshot(correlation ? { jobKeysFor: (instance) => correlation.jobKeysFor(instance) } : {});
+  const snapshot = registry.snapshot(claims ? { jobKeysFor: (instance) => claims.jobKeysFor(instance) } : {});
   const report: AgenticSupplyReport = {
     count: snapshot.count,
     generatedAt: new Date().toISOString(),
-    workers: snapshot.workers.map((w) => toWorker(w, correlation)),
-    leaves: snapshot.leaves.map((leaf) => ({ token: leaf.token, workers: leaf.workers.map((w) => toWorker(w, correlation)) })),
+    workers: snapshot.workers.map((w) => toWorker(w, claims)),
+    leaves: snapshot.leaves.map((leaf) => ({ token: leaf.token, workers: leaf.workers.map((w) => toWorker(w, claims)) })),
     correlations: correlation ? correlation.snapshot().correlations.map(toCorrelation) : [],
   };
   return { status: 200, body: report };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.176.1",
+  "version": "0.177.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -62,7 +62,7 @@
     "lint:fix": "biome check --write app operations workers pages components scripts e2e main.ts"
   },
   "dependencies": {
-    "@nanobpm/agentic": "^0.10.0",
+    "@nanobpm/agentic": "^0.11.0",
     "@nanobpm/urban": "^0.90.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },

package/test/agentic-e2e.test.ts

@@ -154,6 +154,7 @@ test("E2E: the whole visibility plane wires up — presence, correlation, supply
   assert(names.includes("presence"), "H1 presence family is discovered by the H0 seam");
   assert(names.includes("relay"), "H3 relay family is discovered by the H0 seam");
   assert(names.includes("correlation"), "H6 correlation family is discovered by the H0 seam");
+  assert(names.includes("claim"), "#713 claim family is discovered by the H0 seam");
 
   // ── H1: a worker connects and REGISTERs; a live presence row appears with its family/host. ──
   const worker = conn("wk-conn-1", "leafA");
@@ -162,7 +163,14 @@ test("E2E: the whole visibility plane wires up — presence, correlation, supply
   worker.feed({ lane: "control", family: "register", seq: 1, payload: { instance: "wk-a", capability: { family: "opus", host: "boxA" } } });
   await flush();
 
-  // ── H6: the orchestrator links the worker's active jobKey to its process instance / plan. ──
+  // ── #713: the worker CLAIMs its active jobKey — the authoritative visibility source (explicit
+  // instance, no relay/connection inference). This is what lights up jobKeys, even before any
+  // transcript lands. ──
+  worker.feed({ lane: "control", family: "claim", seq: 2, payload: { instance: "wk-a", jobKey: JOB } });
+  await flush();
+
+  // ── H6: the orchestrator links the worker's active jobKey to its process instance / plan (drill-in
+  // context only, since #713 — no longer the visibility source). ──
   const correlation = currentCorrelation();
   assert(correlation !== undefined, "the correlation family installed the singleton");
   correlation.link("wk-a", JOB, { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "nanobpm/nano-workforce#142" });
@@ -179,8 +187,8 @@ test("E2E: the whole visibility plane wires up — presence, correlation, supply
     assertEquals(w.instance, "wk-a");
     assertEquals(w.family, "opus");
     assertEquals(w.host, "boxA");
-    assertEquals(w.jobKeys, [JOB], "H1×H6: the correlation registry feeds the presence jobKeys seam");
-    assertEquals(w.stream, STREAM, "H6: the drill stream repoints at the live job's stream");
+    assertEquals(w.jobKeys, [JOB], "#713: the claim registry feeds the presence jobKeys seam");
+    assertEquals(w.stream, STREAM, "#713: the drill stream repoints at the claimed job's stream");
     assertEquals(res.body.correlations.length, 1);
     const c = res.body.correlations[0];
     assertEquals(c.jobKey, JOB);