@nanobpm/nano-workforce 0.201.5 → 0.203.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.203.0](https://github.com/nanobpm/nano-workforce/compare/v0.202.0...v0.203.0) (2026-10-13)
+
+### Features
+
+* **escalation-steward:** opt-in auto-resolution of escalations with a reviewable record (Closes [#889](https://github.com/nanobpm/nano-workforce/issues/889)) ([#892](https://github.com/nanobpm/nano-workforce/issues/892)) ([cd1c9eb](https://github.com/nanobpm/nano-workforce/commit/cd1c9eb58bc44b7af0c66d4c1a7bc615920a46d2)), closes [887/#888](https://github.com/887/nano-workforce/issues/888) [#833](https://github.com/nanobpm/nano-workforce/issues/833) [o/r#1](https://github.com/o/r/issues/1) [o/r#1](https://github.com/o/r/issues/1)
+
+## [0.202.0](https://github.com/nanobpm/nano-workforce/compare/v0.201.5...v0.202.0) (2026-10-12)
+
+### Features
+
+* **agentic:** authoritative claim resync on supervisor reconnect (Closes [#893](https://github.com/nanobpm/nano-workforce/issues/893)) ([#894](https://github.com/nanobpm/nano-workforce/issues/894)) ([2f39fcb](https://github.com/nanobpm/nano-workforce/commit/2f39fcb680ccafa22f633b409e2f66674ae85a7c))
+
 ## [0.201.5](https://github.com/nanobpm/nano-workforce/compare/v0.201.4...v0.201.5) (2026-10-11)
 
 ### Bug Fixes

package/SPEC.md

@@ -1310,6 +1310,54 @@ re-park (a human node has no separate escalation twin to re-park onto). The gate
 like the escalation resume's no-required-target case), and a no-emit acknowledgement node
 has nothing to validate.
 
+## 13.4 Escalation steward (`escalation-steward.bpmn`) — issue #889
+
+An **opt-in**, timer-paced loop that reviews a run's OPEN escalations and submits a recommended
+choice for each, so work keeps moving when no human is watching — while every automatic decision
+stays **reviewable after the fact** in the Auto-resolutions view. It is strictly opt-in: only work
+whose start request set `autoResolveEscalations: true` (persisted as `auto_resolve_escalations` on
+the subject row) is ever touched; everything else is fail-closed out.
+
+- **Pacing + master switch.** `pollEscalationSteward` (a `pollOnce` pass) starts ONE
+  `escalation-steward` instance per interval — `NANO_ESCALATION_STEWARD_INTERVAL` (default `PT30M`,
+  parsed through the canonical `isoDurationToMs`) — when the loop is enabled (`NANO_ESCALATION_STEWARD`,
+  default on) and no prior tick is still ACTIVE. The pass is **best-effort and isolated**: a
+  steward-specific failure is caught and logged so it never starves the poller's other liveness
+  passes, and the tick timestamp advances only after a successful start (a failed start retries next
+  pass).
+- **Eligibility + the claim fence.** The collect step (`pr.escalation-steward-collect`) gathers the
+  open escalation user tasks whose owning subject OPTED IN — resolved off the subject row by
+  `process_key`, falling back to the root-correlated `subject_key` so an escalation parked inside a
+  callActivity child cell (`human-escalation`/`implement-cell`) inherits its parent run's opt-in —
+  that are past a short minimum age (`NANO_ESCALATION_STEWARD_MIN_AGE_MS`, default 5 min, so a human
+  already answering wins), of a steward-answerable kind, and not already claimed. It claims them with
+  a durable compare-and-swap lease (`escalation_auto_resolutions` `claimed` placeholder + a partial
+  UNIQUE index), so two overlapping ticks (or a tick racing a human) never double-answer; an expired
+  lease is released so a crashed steward never wedges a task.
+- **The agent + the record.** The `senior:escalation-steward` agent reviews the claimed escalations
+  and returns one decision each (`resolved` + typed form `variables`, or `abstained`). The record
+  step (`pr.escalation-steward-record`) submits each resolution through the ONE canonical attributed
+  door (`completeEscalationAsAgent`, AGENT attribution — never a human decision, ADR 0046) and writes
+  exactly one durable `escalation_auto_resolutions` row per acted escalation.
+- **Fail-closed guards (defence-in-depth under the prompt's own abstain rules).** Before any
+  submission the record step enforces, in one place: the **claim/ownership fence** (this run must
+  hold a live claim for the key — a hallucinated or foreign key is **skipped**, leaving any other
+  run's claim untouched, *not* recorded `abstained`: `recordResolution` finalises the claim row keyed
+  only by `user_task_key`, so writing even an `abstained` row for a key this run does not own would
+  finalise another run's live claim); the **destructive-option guard**
+  (`abandon`/`force-merge`/credential, derived from the decision's own selected value scoped to the
+  task's ACTUAL form — abstained, never submitted; a foreign safe key can never shadow a destructive
+  own-form key, and a decision carrying conflicting selection fields is abstained as ambiguous); the
+  **loop guard** (a subject auto-resolved `LOOP_GUARD_MAX_RESOLUTIONS` times
+  that escalates again is abstained); and the **malformed-decision guards** (a non-object entry is
+  skipped; a `resolved` decision with no valid `variables` object is recorded `abstained`, never a
+  false `resolved`). Human-only / irreversible kinds (`merge-approval`, `acp-permission`,
+  readiness gates, `feature-blocked`, `conformance-`/`empty-plan-`escalation) are refused before the
+  agent is even dispatched.
+- **The reviewable record.** Every final decision (`resolved`/`abstained`) is listed in
+  Auto-resolutions, attributed to the steward agent, where an operator can **Dismiss** (reviewed, no
+  action) or **Intervene** (stepped in) with a note — a record is never a hidden machine decision.
+
 ## 14. Open questions / future
 
 - **Provisioning the existing PR branch** — resolved: the `c8ctl` host-git

package/app/admittedStaging.test.ts

@@ -23,9 +23,20 @@ function memData() {
           find: (q: any) =>
             Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
           insert: (r: any) => {
+            // Enforce the PRIMARY KEY (plan_key) uniqueness the real SQLite table has, so the
+            // concurrent-insert race path (a colliding second insert throws) is exercisable.
+            if (rows.some((x) => x[key] === r[key])) {
+              return Promise.reject(new Error(`UNIQUE constraint failed: ${name}.${key}`));
+            }
             rows.push(r);
             return Promise.resolve(r);
           },
+          update: (k: any, patch: any) => {
+            const i = rows.findIndex((r) => r[key] === k);
+            if (i === -1) return Promise.resolve({ changed: 0 });
+            rows[i] = { ...rows[i], ...patch };
+            return Promise.resolve({ changed: 1 });
+          },
         };
       },
     } as any,
@@ -59,6 +70,66 @@ test("recordAdmittedEpic is idempotent on plan_key (no second row, existing wins
   assertEquals(again.base_branch, "epic/a"); // the existing staged row is returned, not overwritten
 });
 
+test("recordAdmittedEpic widens the staged escalation opt-in monotonically on an idempotent retry", async () => {
+  const { data, tables } = memData();
+  // Stage the epic OPTED OUT (the caller omitted the flag → 0), as a crashed-before-lowering request
+  // would leave it.
+  const first = await recordAdmittedEpic(data, EPIC);
+  assertEquals(first.auto_resolve_escalations, 0, "an omitted opt-in stages as 0 (opted out)");
+  // Retry the SAME admission now opting in: the staged row must WIDEN to opted-in (issue #889 review),
+  // not stay opted out — otherwise the epic starts opted out despite the caller's opt-in.
+  const retried = await recordAdmittedEpic(data, { ...EPIC, auto_resolve_escalations: 1 });
+  assertEquals(tables.get("admitted_epics")!.length, 1, "still one staged row (idempotent)");
+  assertEquals(retried.auto_resolve_escalations, 1, "the retry widened the staged opt-in to 1");
+  assertEquals(retried.created_at, first.created_at, "the original staged row is preserved");
+  assertEquals(tables.get("admitted_epics")![0].auto_resolve_escalations, 1, "the widening is persisted");
+});
+
+test("recordAdmittedEpic never narrows an opted-in staged row back to opted-out", async () => {
+  const { data, tables } = memData();
+  await recordAdmittedEpic(data, { ...EPIC, auto_resolve_escalations: 1 });
+  // A retry that omits (or explicitly clears) the flag must NOT narrow the staged opt-in back to 0 —
+  // the flag is monotonic (mirrors submitPr's live-loop adoption, service.ts).
+  const retried = await recordAdmittedEpic(data, { ...EPIC, auto_resolve_escalations: 0 });
+  assertEquals(retried.auto_resolve_escalations, 1, "an opted-in staged row is never narrowed to 0");
+  assertEquals(tables.get("admitted_epics")![0].auto_resolve_escalations, 1);
+});
+
+test("recordAdmittedEpic applies the monotonic widening on the concurrent-insert race path", async () => {
+  // Simulate the race the reviewer cited (issue #889): an opted-OUT admission's insert WINS, so by
+  // the time the opted-IN caller runs, the row already exists — but the opted-in caller's initial
+  // `get` raced ahead of that commit and observed NO row, so it proceeds to `insert`, collides on the
+  // PRIMARY KEY, and lands in the catch path. The catch must apply the SAME 0→1 widening before
+  // returning the raced row, or the opt-in is silently lost.
+  const { data, tables } = memData();
+  // The winning racer commits its opted-out row directly (as its own successful insert).
+  await recordAdmittedEpic(data, { ...EPIC, auto_resolve_escalations: 0 });
+  assertEquals(tables.get("admitted_epics")![0].auto_resolve_escalations, 0, "the racer staged opted-out");
+
+  // Force the opted-in caller's FIRST `get` to miss (the race window: it read before the racer's
+  // commit became visible); the catch-path re-read then sees the committed row.
+  const realTable = (data as any).table;
+  let missOnce = true;
+  (data as any).table = (name: string, key: string) => {
+    const t = realTable(name, key);
+    if (name !== "admitted_epics") return t;
+    return {
+      ...t,
+      get: (k: any) => (missOnce ? ((missOnce = false), Promise.resolve(null)) : t.get(k)),
+    };
+  };
+
+  // The opted-in caller: get misses → insert collides (mock enforces PK uniqueness) → catch path.
+  const raced = await recordAdmittedEpic(data, { ...EPIC, auto_resolve_escalations: 1 });
+  assertEquals(raced.auto_resolve_escalations, 1, "the catch path widens the raced opted-out row to 1");
+  assertEquals(
+    tables.get("admitted_epics")!.find((r) => r.plan_key === EPIC.plan_key)!.auto_resolve_escalations,
+    1,
+    "the widening is persisted on the raced row",
+  );
+  assertEquals(tables.get("admitted_epics")!.length, 1, "still exactly one staged row (no duplicate)");
+});
+
 test("recordAdmittedPlanDep stages an edge and stays out of plan_deps", async () => {
   const { data, tables } = memData();
   await recordAdmittedPlanDep(data, {

package/app/agentActivationLedger.ts

@@ -34,6 +34,11 @@ export const AGENT_SLA_JOB_TYPES: readonly string[] = [
   "senior:retro", // retro synthesize
   "senior:fix-ci", // merge-loop CI-fix cell (be_fixci_sla)
   "senior:rebase", // merge-loop rebase cell (be_rebase_sla)
+  // Tracked for AUDIT PROVENANCE, not an SLA boundary (issue #889 review): the escalation-steward
+  // record step reads this row's `job_key` to persist the ACTUAL answering agent's activation key on
+  // the durable auto-resolution (rather than its own record-task key), so the review surface points at
+  // the job that made the decision.
+  "senior:escalation-steward", // escalation-steward agent (escalation-steward.bpmn)
 ];
 
 /** One ledger row: whether (and when) a worker picked up an agent job for a given process instance. */

package/app/agentCompletion.test.ts

@@ -21,6 +21,8 @@ import {
   escalationFormId,
   latestCompletion,
   revertAgentCompletion,
+  snapshotEscalationFormOptions,
+  snapshotUserTaskFormOptions,
   type TaskCompletion,
   validateEscalationVariables,
 } from "./agentCompletion.ts";
@@ -958,3 +960,34 @@ test("feature-escalation demands non-blank answer on the answer path, but not on
     "the abandon path does not demand the hidden answer field",
   );
 });
+
+test("snapshotUserTaskFormOptions: resolves the engine form_key first (delivery-graph human tasks)", () => {
+  // A delivery-graph human task's element id is dynamic and has NO static escalationFormId mapping, so
+  // the element-only snapshot returns null — but its engine form_key names the real deployed form. The
+  // form_key must win so the options are the REAL choices, not NULL (issue #889 review).
+  assertEquals(snapshotEscalationFormOptions("delivery-human-task__publish"), null, "no static form for a dynamic element id");
+  assertEquals(
+    snapshotUserTaskFormOptions("delivery-escalation", "delivery-human-task__publish"),
+    ["continue", "retry"],
+    "the engine form_key resolves the deployed form's real options",
+  );
+});
+
+test("snapshotUserTaskFormOptions: falls back to the element's static form when form_key is blank", () => {
+  // No engine form_key — fall back to the fixed-form element's static linkage (trial-merge-decision →
+  // [proceed, rebase, abandon]).
+  assertEquals(snapshotUserTaskFormOptions(null, "trial-merge-decision"), ["proceed", "rebase", "abandon"]);
+  assertEquals(snapshotUserTaskFormOptions("   ", "trial-merge-decision"), ["proceed", "rebase", "abandon"], "a blank form_key falls through to the element form");
+});
+
+test("snapshotUserTaskFormOptions: an unresolvable form_key never throws (safe read)", () => {
+  // `formContract` does a readFileSync that THROWS on a missing file — a form_key that names no bundled
+  // form must degrade to the element fallback / null, never throw (a throw in the claim loop wedges the
+  // steward). With neither a resolvable form_key NOR a mappable element, the result is null.
+  assertEquals(snapshotUserTaskFormOptions("no-such-form", "delivery-human-task__x"), null, "unresolvable key + dynamic element → null, no throw");
+  assertEquals(
+    snapshotUserTaskFormOptions("no-such-form", "trial-merge-decision"),
+    ["proceed", "rebase", "abandon"],
+    "an unresolvable form_key falls back to the element's static form",
+  );
+});

package/app/agentCompletion.ts

@@ -296,6 +296,82 @@ export function validateEscalationVariables(
   return null;
 }
 
+/** Snapshot the REAL option values an escalation's deployed `.form` offers (the union of every `select`
+ *  field's allowed `values`), read from the canonical form contract host-side. The escalation-steward
+ *  record step persists THIS — never the deciding agent's self-reported `options` array, which the agent
+ *  may omit or misstate (issue #889 review) — so the reviewable record shows the choices that were
+ *  genuinely on offer. Returns `null` when the element has no linked form (nothing to snapshot). */
+export function snapshotEscalationFormOptions(elementId: string): string[] | null {
+  const formId = escalationFormId(elementId);
+  if (!formId) return null;
+  return optionUnionForForm(formId);
+}
+
+/** The SELECT-field KEYS a fixed-form escalation's deployed `.form` carries (e.g. `["action"]` for
+ *  `trial-merge-decision`, `["directive"]` for `plan-review-decision`), read from the SAME canonical
+ *  form contract the completer validates against — one derivation, no second field list. The
+ *  escalation-steward record step uses this to scope its destructive-option guard to the field the
+ *  task's ACTUAL form submits, so a foreign recognized key (a `resolution` on a `trial-merge-decision`,
+ *  whose own select is `action`) can never shadow the real destructive choice (issue #889 review).
+ *  Returns `null` when the element has no linked form (nothing to scope to — the caller falls back to
+ *  its conservative recognized-key sweep). Never throws on an unreadable form (yields `null`). */
+export function escalationFormSelectKeys(elementId: string): string[] | null {
+  const formId = escalationFormId(elementId);
+  if (!formId) return null;
+  let contract: FormContract;
+  try {
+    contract = formContract(formId);
+  } catch {
+    return null;
+  }
+  return Object.keys(contract.allowed);
+}
+
+/** The union of every `select` field's allowed option values in a deployed `.form`, or `null` when the
+ *  form id is blank/unreadable (a missing or non-`.form` key never throws — see the try/catch). Shared
+ *  by {@link snapshotEscalationFormOptions} (fixed-form escalations, keyed off the element) and
+ *  {@link snapshotUserTaskFormOptions} (keyed off the engine-resolved `form_key`). */
+function optionUnionForForm(formId: string): string[] | null {
+  let contract: FormContract;
+  try {
+    contract = formContract(formId);
+  } catch {
+    // `formContract` does a `readFileSync` and THROWS on a missing/unreadable `.form` — a `form_key`
+    // can be a key that doesn't name a bundled form. Treat that as "nothing to snapshot", never a throw
+    // that would incident the record tick.
+    return null;
+  }
+  const out: string[] = [];
+  for (const values of Object.values(contract.allowed)) {
+    for (const v of values) if (!out.includes(v)) out.push(v);
+  }
+  return out;
+}
+
+/** Snapshot the REAL option values a parked user task's deployed form offers, resolving the form from
+ *  the engine-reported `formKey` FIRST and falling back to the element's static form linkage — the SAME
+ *  precedence the Tasks grid denormalises with (`app/service.ts`), so there is one derivation. This is
+ *  what the escalation-steward record step persists for a DELIVERY-GRAPH human task, whose element id is
+ *  dynamic (`delivery-human-task__<node>`) and so has NO static `escalationFormId` mapping — snapshotting
+ *  off `element_id` alone would record `NULL` options for exactly those tasks (issue #889 review). Reads
+ *  the `formKey` safely (a key that doesn't name a bundled `.form` yields `null`, never a throw).
+ *  Returns `null` when neither source resolves a readable form. */
+export function snapshotUserTaskFormOptions(
+  formKey: string | null | undefined,
+  elementId: string | null | undefined,
+): string[] | null {
+  const engineKey = typeof formKey === "string" ? formKey.trim() : "";
+  if (engineKey) {
+    const fromKey = optionUnionForForm(engineKey);
+    if (fromKey != null) return fromKey;
+  }
+  if (elementId) {
+    const formId = escalationFormId(elementId);
+    if (formId) return optionUnionForForm(formId);
+  }
+  return null;
+}
+
 /** The canonical attributed completer. Records an attribution row in `task_completions` and THEN
  *  completes the user task with the exact typed `variables` — so the ledger row can never be lost by a
  *  resume that fires before the write. If the engine completion throws (a failed/rejected completion,
@@ -401,6 +477,30 @@ export async function latestCompletion(
   return newest;
 }
 
+/** The newest NON-reverted completion an AGENT recorded for a user-task key under a specific
+ *  `agentId`, or undefined. The escalation-steward record step uses this to make its
+ *  completion→record pair idempotent across a service-job retry (issue #889 review): the engine
+ *  completion lands first, then the record worker finalises the claim row — if that finalise fails
+ *  transiently, the retry finds the user task already COMPLETED (the attributed door reports "no open
+ *  completable task") and must NOT degrade the already-applied decision to a false `abstained`.
+ *  Detecting the prior agent-attributed row lets the retry recover the original submitted variables
+ *  and finalise the SAME decision instead. Reverted rows are excluded: a human overrode that
+ *  completion, so it is not a live applied decision to recover. */
+export async function priorAgentCompletion(
+  data: DataLayer,
+  userTaskKey: string,
+  agentId: string,
+): Promise<TaskCompletion | undefined> {
+  const rows = await taskCompletions(data).find({ user_task_key: userTaskKey });
+  let newest: TaskCompletion | undefined;
+  for (const row of rows) {
+    if (row.actor_kind !== "agent" || row.actor_id !== agentId) continue;
+    if (row.reverted === 1) continue;
+    if (!newest || row.id > newest.id) newest = row;
+  }
+  return newest;
+}
+
 export interface AgentCompleteResult {
   ok: boolean;
   reason?: string;
@@ -460,14 +560,20 @@ function isCompletableElement(elementId: string, allowed: ReadonlySet<string>):
 export async function completeEscalationAsAgent(
   data: DataLayer,
   engine: EngineClient,
-  input: { userTaskKey: string; variables: Record<string, unknown>; agentId: string },
+  input: { userTaskKey: string; variables: Record<string, unknown>; agentId: string; processInstanceKey?: string | null },
 ): Promise<AgentCompleteResult> {
   const userTaskKey = input.userTaskKey.trim();
   if (!userTaskKey) return { ok: false, reason: "userTaskKey is required" };
   const agentId = input.agentId.trim();
   if (!agentId) return { ok: false, reason: "agentId is required" };
 
-  const resolved = await resolveEscalationTask(engine, userTaskKey);
+  // When the caller already knows the task's owning process instance (the escalation-steward record
+  // worker does — it holds the claim row's `process_instance_key`), scope the resolve scan to that ONE
+  // instance instead of an engine-wide `openUserTasks()` per decision. A record tick finalises MANY
+  // claimed tasks in one pass, so an unfiltered global scan each is O(N²) REST load (issue #889 review);
+  // the instance filter makes it O(N) and never changes the outcome (the task lives in exactly that
+  // instance). A bare-key caller (a one-off human/agent door) omits it and keeps the engine-wide scan.
+  const resolved = await resolveEscalationTask(engine, userTaskKey, ESCALATION_TASK_ELEMENTS, input.processInstanceKey ?? undefined);
   if (!resolved.ok) return resolved;
 
   const invalid = validateEscalationVariables(resolved.elementId, input.variables);

package/app/agentic/README.md

@@ -79,6 +79,54 @@ derivation half:
   a chosen offset, so an exited session can be branched and replayed independently, offset-parity
   preserved. Byte-replay and resume-from-offset (`transcript-read.ts`) are untouched.
 
+## Job-ownership claims & authoritative reconnect resync (#713, #893)
+
+The `claim` / `release` family (`families/claim.family.ts`) backs the {@link ClaimRegistry}
+(`claim-registry.ts`) — the authoritative "which jobs a worker instance is running" visibility source
+the supply snapshot reads. Each `claim` (wire code 8) / `release` (wire code 9) frame names its OWNING
+`instance` explicitly, so one per-host supervisor connection can carry many workers' ownership frames.
+
+**Authoritative resync (the supervisor's view wins).** On a WS reconnect a supervisor re-`register`s
+every worker and re-`claim`s every active jobKey. Re-claims alone are *additive* — a claim that is not
+re-asserted is never dropped, so a `release` lost during a hub outage would leave the job shown as
+"working" until the worker exits entirely. To close that gap a supervisor may end its resync with an
+**authoritative snapshot**: a `claim` frame enriched with the full `jobKeys` set it currently owns
+(`{ instance, jobKeys: [...] }` — possibly empty, the meaningful "owns nothing now" resync). The hub
+then calls `ClaimRegistry.replaceInstance(instance, jobKeys)`, which **drops every claim that instance
+held but did not re-assert** and (re-)claims the snapshot's set. The snapshot rides the existing
+`claim` wire family as a forward-compatible enrichment (the protocol's structural validators tolerate
+the extra field), so **no new wire code** is needed.
+
+The `claim` family thus carries **two payload variants** — the classic per-job claim
+`{ instance, jobKey }` and the resync snapshot `{ instance, jobKeys }` (the `claim.snapshot` wire
+contract in `app/contracts.ts`). The pinned `@nanobpm/agentic` validator predates the snapshot variant
+and requires a non-empty `jobKey`, so the hub validates the **union** itself: a frame is well-formed
+iff it is a valid snapshot (non-empty `instance` + a `jobKeys` array of **non-empty** strings) or a
+valid per-job claim. This is a **union with a validated overlap**, not an exclusive-or: a frame
+carrying *both* fields is accepted, but only when *both* halves validate, so the snapshot branch never
+bypasses validation. The **presence** of `jobKeys` (not its validity) is the snapshot discriminant, so
+a present-but-malformed `jobKeys` — a non-array, a non-string element, **or an empty-string element**
+(held to the same non-empty bar as the per-job `jobKey`) — is a broken snapshot and is **rejected**,
+never treated as absent and laundered through the per-job validator (which would accept it on any
+frame that also carries a valid `jobKey`). The empty *array* remains the meaningful "owns nothing now"
+resync — only empty *elements* are rejected. Versioning the snapshot into the canonical `@nanobpm/agentic` protocol payloads is the
+nano-ide follow-up issue #893 scopes ("coordinate with the `@nanobpm/agentic` package owners"); the
+producer half (one snapshot per instance, including empty sets) is nano-supervisor#63.
+
+Guarantees `replaceInstance` keeps:
+
+- A claim re-asserted in the snapshot is unchanged.
+- A jobKey that has **moved to another instance** is never blanked by the old instance's resync (the
+  old instance no longer holds it, so the drop pass cannot touch it).
+- Repeated resyncs are safe (idempotent).
+- **Compatibility:** a supervisor that never sends a snapshot keeps the pre-#893 additive behaviour —
+  claims are then cleared only by an explicit `release` or the presence-driven `reconcile`.
+
+Authoritative replacement is safe because ownership is advisory, short-lived visibility the supervisor
+can always restate; the registry never gates a BPMN flow (ADR 0056). This is what lets a downstream hub
+client (nano-supervisor#63) **bound** its RELEASE buffer during an outage instead of buffering every
+RELEASE without limit.
+
 ## Invariants (ADR 0056)
 
 - **App-tier only** — never the engine. The Camunda-8 job protocol (worker⇄engine) is untouched;

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

@@ -112,6 +112,67 @@ test("reconnect-resync: re-register + re-claim rebuilds the same claim (never bl
   assert.equal(reg.count(), 1);
 });
 
+test("replaceInstance: an authoritative resync drops a claim the supervisor did NOT re-assert (a lost RELEASE no longer strands the job)", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-a", "8421");
+  // The hub missed the `release` for 8420 during an outage. On reconnect the supervisor restates its
+  // authoritative snapshot: wk-a now owns only 8421. The non-re-asserted 8420 is dropped.
+  reg.replaceInstance("wk-a", ["8421"]);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["8421"]);
+  assert.equal(reg.isClaimed("8420"), false, "the stranded claim was dropped");
+  assert.equal(reg.count(), 1);
+});
+
+test("replaceInstance: a re-asserted claim is unchanged; an added one is claimed", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.replaceInstance("wk-a", ["8420", "8421"]);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["8420", "8421"]);
+  assert.equal(reg.ownerOf("8420"), "wk-a");
+  assert.equal(reg.ownerOf("8421"), "wk-a");
+});
+
+test("replaceInstance: an empty snapshot drops every claim the instance held", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-a", "8421");
+  reg.replaceInstance("wk-a", []);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), []);
+  assert.equal(reg.count(), 0);
+});
+
+test("replaceInstance: a jobKey that moved to another instance is NOT dropped by the old instance's resync", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-b", "8420"); // 8420 moved to wk-b
+  // wk-a's authoritative resync no longer mentions 8420 (it does not run it) — and must not blank the
+  // live owner wk-b.
+  reg.replaceInstance("wk-a", []);
+  assert.deepEqual(reg.jobKeysFor("wk-b"), ["8420"], "the current owner's claim survives");
+  assert.equal(reg.ownerOf("8420"), "wk-b");
+});
+
+test("replaceInstance: only the resyncing instance's claims are touched; siblings are untouched", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.claim("wk-b", "8500");
+  reg.replaceInstance("wk-a", []);
+  assert.deepEqual(reg.jobKeysFor("wk-a"), []);
+  assert.deepEqual(reg.jobKeysFor("wk-b"), ["8500"], "an unrelated instance's claim is untouched");
+});
+
+test("replaceInstance is idempotent and ignores empty jobKeys / an empty instance", () => {
+  const reg = new ClaimRegistry();
+  reg.claim("wk-a", "8420");
+  reg.replaceInstance("wk-a", ["8420", ""]); // the empty jobKey is ignored
+  reg.replaceInstance("wk-a", ["8420"]); // repeat — no churn
+  assert.deepEqual(reg.jobKeysFor("wk-a"), ["8420"]);
+  reg.replaceInstance("", ["9999"]); // an empty instance is ignored
+  assert.equal(reg.isClaimed("9999"), false);
+  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");

package/app/agentic/claim-registry.ts

@@ -52,7 +52,9 @@ export interface ClaimSnapshot {
  * 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.
+ * path stranded the jobKey across. A supervisor may close its resync with an AUTHORITATIVE snapshot via
+ * {@link replaceInstance} (issue #893), dropping any claim it did not re-assert so a lost `release`
+ * cannot strand a job; omitting it keeps the additive re-claim behaviour.
  */
 export class ClaimRegistry {
   /** worker instance → the set of jobKeys it currently owns (insertion-ordered). */
@@ -107,6 +109,38 @@ export class ClaimRegistry {
     this.#jobsOf.delete(instance);
   }
 
+  /**
+   * Authoritatively REPLACE every claim held by `instance` with `jobKeys` — the reconnect-resync
+   * contract (issue #893). A reconnecting supervisor restates the full, current ownership snapshot for
+   * one worker instance; its view WINS. Every claim this instance held that is NOT in `jobKeys` is
+   * dropped (so a `release` lost during a hub outage no longer strands the job as "working" until the
+   * worker exits entirely), and every jobKey in `jobKeys` is (re-)claimed — an idempotent no-op for one
+   * it already owned, a {@link claim} move for one another instance held.
+   *
+   * It keeps the registry's existing guarantees: a jobKey that has MOVED to another instance is never
+   * blanked by the OLD instance's resync (the old instance no longer holds it, so the drop pass cannot
+   * touch it), and repeated resyncs are safe. Only `instance`'s own claims are considered — a sibling's
+   * claims are untouched. An empty `instance` is ignored; empty jobKeys in the snapshot are skipped.
+   *
+   * This is ADDITIVE on the wire: a supervisor that never sends a resync snapshot keeps the pre-#893
+   * merge behaviour (claims cleared only by an explicit `release` or the presence-driven
+   * {@link reconcile}). Authoritative replacement is safe precisely because ownership is advisory,
+   * short-lived visibility the supervisor can always restate (ADR 0056 — the registry never gates a
+   * BPMN flow).
+   */
+  replaceInstance(instance: string, jobKeys: Iterable<string>): void {
+    if (instance === "") return;
+    const next = new Set<string>();
+    for (const jobKey of jobKeys) if (jobKey !== "") next.add(jobKey);
+    const current = this.#jobsOf.get(instance);
+    if (current) {
+      for (const jobKey of [...current]) {
+        if (!next.has(jobKey)) this.release(instance, jobKey);
+      }
+    }
+    for (const jobKey of next) this.claim(instance, jobKey);
+  }
+
   /**
    * 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