@nanobpm/nano-workforce 0.176.0 → 0.177.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **cancel:** reconcile feature_runs in the app cancel door with a truthful result ([#712](https://github.com/nanobpm/nano-workforce/issues/712)) ([810979b](https://github.com/nanobpm/nano-workforce/commit/810979b3708a247b2ab4ee068c211abd5478363a)), closes [#667](https://github.com/nanobpm/nano-workforce/issues/667) [#705](https://github.com/nanobpm/nano-workforce/issues/705)
+
 ## [0.176.0](https://github.com/nanobpm/nano-workforce/compare/v0.175.2...v0.176.0) (2026-09-02)
 
 ### Features

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