@nanobpm/nano-workforce 0.201.4 → 0.202.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* protect engine-owned process vars from agent-completion clobber (Closes [#887](https://github.com/nanobpm/nano-workforce/issues/887)) ([#888](https://github.com/nanobpm/nano-workforce/issues/888)) ([4245287](https://github.com/nanobpm/nano-workforce/commit/4245287e3d7553881f29bdda50cbd6d2b60b6268))
+
 ## [0.201.4](https://github.com/nanobpm/nano-workforce/compare/v0.201.3...v0.201.4) (2026-10-11)
 
 ### Bug Fixes

package/SPEC.md

@@ -428,6 +428,79 @@ Notes:
   `answer`/`scopePending` (inputs the agent consumes) stay cleared on the
   review-round output.
 
+- **Engine-owned process variables are restored around every external-agent task
+  (issue #887).** The engine merges **every** variable an external agent returns
+  into process scope **unfiltered** — the `io.nanobpm.dataEnvelope.out` shape is
+  codegen/typing-only and applies **no** runtime filtering or coercion. An agent
+  that echoes an engine-owned variable with a colliding name or drifted type (a
+  `senior:pr-review` job that returned `round: "4"` — a string) therefore
+  overwrites the real process value, and the next FEEL guard that reads it
+  (`round >= maxRounds` at `gw-guard`) raises `comparison not defined for string
+  and number` and wedges the loop on an unrecoverable incident. The categorical
+  guard is a **snapshot/restore** on each external-agent task (`review-round`,
+  `adversarial-review`, `classify-scope`): before the agent runs, each
+  engine-owned variable is copied into a task-**local** `guard<Name>` input
+  (`<zeebe:input source="=round" target="guardRound"/>` …), and the task's output
+  mapping **restores** the process variable from that snapshot
+  (`<zeebe:output source="=guardRound" target="round"/>`). Because the snapshot
+  holds the pre-merge value, the restore overwrites whatever the completion
+  merged in, so the agent's real outputs (`status`/`summary`/`question`,
+  `adversarialFindings`, the scope verdict) flow through but it can never alter
+  the protected set. The protected set is **every engine-owned variable the loop
+  relies on that the agent does not own as an output**: the control counters and
+  budgets (`round`, `maxRounds`, `advPass`, `advMax`, `ackRetryRound`,
+  `ackRetryMax`, `huskRetries`, `reviewWaitTimeout`), the `prKey` correlation
+  key, **and** the PR identity inputs (`repo`, `prNumber`, `prUrl`) — the last
+  three because the unfiltered merge lets an input-echo replace the identity that
+  `progress-check`, `converge-gate`, and `finalize` go on to read (a wrong
+  `prNumber` would make `finalize` start the merge loop for the wrong PR) — **and**
+  the gate controls `humanApproval` and `convergeOnly`. These last two are
+  decision flags the loop acts on after the agent returns: `humanApproval = true`
+  routes a converged PR through the `gw-approval` human gate instead of
+  auto-merging, and `convergeOnly = true` ends a review-only run without ever
+  handing the PR to the merge loop. Left unguarded, a converged completion that
+  echoed `humanApproval: false` would **bypass** the approval gate, and one that
+  echoed `convergeOnly: false` would hand a review-only PR to the merge loop.
+  `convergeOnly` is a plain seeded constant, so the usual `=guardConvergeOnly`
+  restore applies. `humanApproval` is the one engine-owned flag that is **also
+  legitimately mutated mid-flight** — a gated caller that adopts a live loop
+  raises it `false → true` via `engine.setVariables` (`submitPr` in
+  `app/service.ts`); it is **monotonic** (only ever rises). A plain
+  `=guardHumanApproval` restore would clobber that concurrent host-set true, so
+  the restore is the monotonic join
+  `=(guardHumanApproval = true) or (humanApproval = true)`: it recovers the
+  snapshot's `true`, honours a concurrent adopter's `true`, and ignores an agent
+  echo of `false`. The direction is **fail-safe** — the only state it can force
+  is *more* human review, never a merge the loop would otherwise have gated. The
+  protected set also covers the two **progress bookkeeping** values the loop
+  reads back after the agent returns: `reviewStale` (the converge-gate's
+  stale-body signal — `f_guardMax` escalates only when `round >= maxRounds and
+  reviewStale != true`, so a forged `reviewStale: true` would suppress the
+  max-round escalation) and `roundEntryHead` (the within-round baseline
+  `pr.capture-head` captures and `pr.progress-check` consumes — a forged head
+  would falsify the no-progress decision). Both are plain process-owned reads, so
+  the usual `=guardReviewStale` / `=guardRoundEntryHead` restore pins them. The
+  protected set further covers the two **seeded cooperative-abandon** reads:
+  `abandonUrl` (the capability `pr.persist-round`/`pr.persist-escalation`/
+  `pr.finalize` record for a human — a forged echo would redirect the abandon
+  token) and `abandonBrief` (which feeds the NEXT agent task's `appendPrompt`
+  input `=(if abandonBrief = null then "" else abandonBrief)` — a non-string echo
+  would carry a wrong/non-string brief into that later prompt). Both are plain
+  process-owned reads, pinned by the usual `=guardAbandonUrl` / `=guardAbandonBrief`
+  restore. The reserved **`io.nanobpm.agentTask`** repository envelope is
+  *deliberately not* in this list: it is a flat dotted framework key with no
+  FEEL-path access, so snapshotting it would need backtick-escaped FEEL
+  (`` =`io.nanobpm.agentTask` ``) that has no precedent on this engine and would,
+  if evaluated as the default dotted path, resolve to `null` and **null the
+  fleet-critical envelope on restore** — a strictly worse failure than the
+  hypothetical clobber (an agent would have to emit a result-JSON key literally
+  named `io.nanobpm.agentTask`). A counter the task itself advances is incremented
+  **from the snapshot** (`adversarial-review` computes `advPass` as
+  `(if guardAdvPass = null then 0
+  else guardAdvPass) + 1`), never from the mergeable process variable. Any new
+  external-agent task added to this loop must apply the same guard to every
+  engine-owned variable in scope.
+
 
 ## 5. Agent job contract (`senior:pr-review`)
 
@@ -817,6 +890,37 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
   `pr.persist-escalation` worker as the review stage (status `escalated`), answered
   via the native `wait-merge-answer` `userTask` (the same `completeUserTask` door as
   the review escalation, #256); answering re-arms and retries.
+- **Engine-owned variable guard (issue #887)** — the merge-loop applies the same
+  snapshot/restore invariant as the convergence loop (§4) around its external-agent
+  tasks (`fix-ci`, `rebase`). Each guards the loop counters and budgets
+  (`ciFixRound`, `ciFixMax`, `rebaseRound`, `rebaseMax`, `mergeRetryRound`,
+  `mergeRetryMax`, `mergeStallRounds`, `mergeStallMax`), the `prKey` correlation
+  key, and the PR identity inputs (`repo`, `prNumber`, `prUrl`) — the last three
+  because `pr.merge` reads them directly for GitHub operations after the agent
+  re-arms the poller, so an input-echo that replaced them would merge the wrong
+  PR. It further guards the **lifecycle marker and timeout config** the loop
+  re-arms on every pass: `ciBlockedReconciled` (arm-merge seeds it `null`;
+  `ci-reconcile` sets it `true`; `gw-ci-blocked` runs the one-shot ground-truth
+  reconcile exactly once per episode while it is `!= true`) and the seeded timer
+  durations (`agentSlaTimeout`, `landedWaitTimeout`, `mergeableWaitTimeout`,
+  `mergeableRepollInterval`). Left unguarded, a `{status:"blocked", pushed:false,
+  ciBlockedReconciled:true}` completion would **skip** the mandatory first
+  reconcile and page a human immediately, and a clobbered timeout would silently
+  reshape a wait a later loop pass re-arms. The guard also pins the two values
+  `pr.merge` (attempt-merge) consumes directly after a successful fix/rebase
+  re-arms the poller: `round` (the converged round `ensurePr` records on the
+  merge audit row) and `abandonUrl` (the cooperative-abandon capability URL whose
+  token the merge worker extracts). A completion echoing either would corrupt the
+  recorded round or replace the abandon token, so `=guardRound` /
+  `=guardAbandonUrl` restores pin both. It likewise guards `abandonBrief`, which
+  feeds the fix-ci/rebase `appendPrompt` input (`=(if abandonBrief = null then ""
+  else abandonBrief)`) on the next re-arm — a non-string echo would carry a
+  non-string brief into that later prompt. (As in the convergence loop (§4), the
+  reserved dotted `io.nanobpm.agentTask` repository envelope is *not* guarded: it
+  has no FEEL-path access and a backtick-escaped restore, untested on this engine,
+  would risk nulling the envelope used for later agent provisioning.) The counter
+  the task advances is incremented from the snapshot (`ciFixRound`/`rebaseRound`
+  become `guard<Name> + 1`).
 - **Terminal** — `merged` (with `merged_at`), or `converged` when
   `NANO_PR_AUTO_MERGE=0` (review-only), or `abandoned` on cancel.
 

package/app/agentOutputEnvelope.test.ts

@@ -0,0 +1,464 @@
+// Regression guard for issue #887 — an external-agent job's completion variables must not clobber
+// engine-owned process state.
+//
+// The defect (merlin PI 351101, incident 363350 at `gw-guard`): a `senior:pr-review` job returned
+// `round: "4"` (a STRING) alongside its result. The engine merges EVERY variable an external agent
+// returns into process scope UNFILTERED (the `io.nanobpm.dataEnvelope.out` shape is typing-only — no
+// runtime filtering/coercion), so the agent's string overwrote the engine-owned integer counter
+// `round`. The next `gw-guard` evaluation (`round >= maxRounds`) then raised
+//   "comparison not defined for string and number"
+// and wedged the loop on an unrecoverable incident.
+//
+// Failure CLASS: any external-agent task can corrupt engine-owned state (round, maxRounds, the
+// adversarial/ack/husk counters, prKey…) by name collision or type drift. The categorical fix snapshots
+// each engine-owned control variable into a task-LOCAL input before the agent runs and RESTORES it from
+// that snapshot on the task's output mapping, so an agent completion can never alter it (the snapshot is
+// the pre-merge value; an output `source="=round"` would read the already-clobbered merge — proven by the
+// `app/agentCompletion*`/testkit notes). The agent's real outputs (status/summary/question for a review
+// round, findings for the adversarial pass, the scope verdict) still flow through untouched.
+//
+// These deploy the committed convergence-loop into the real WASM engine and drive a token to `gw-guard`
+// with an agent that echoes `round: "4"`; the fix means NO incident is raised and `round` stays the
+// engine-managed integer.
+import { after, test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { readFileSync } from "node:fs";
+import { createWasmEngineClient, type WasmEngineClient } from "@nanobpm/urban-testkit";
+
+const MODEL = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
+
+type Output = Record<string, unknown>;
+type Responder = Output | ((job: { variables: Record<string, unknown> }) => Output);
+
+const ALL_JOB_TYPES = [
+  "senior:pr-review",
+  "senior:adversarial-review",
+  "pr.capture-head",
+  "pr.persist-round",
+  "pr.progress-check",
+  "pr.converge-gate",
+  "senior:scope-classify",
+  "pr.finalize",
+  "pr.persist-escalation",
+  "pr.answer-escalation",
+] as const;
+
+const DEFAULT_RESPONSES: Record<string, Responder> = {
+  "senior:pr-review": { status: "addressed", summary: "fixed" },
+  "senior:adversarial-review": { adversarialFindings: "", adversarialSummary: "clean" },
+  "pr.capture-head": { roundEntryHead: "sha-entry" },
+  "pr.persist-round": {},
+  "pr.progress-check": { progressed: true },
+  "pr.converge-gate": { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false },
+  "senior:scope-classify": { scopeBlocked: false, scopeBlockReason: "" },
+  "pr.finalize": {},
+  "pr.persist-escalation": { escalated: true },
+  "pr.answer-escalation": {},
+};
+
+const DEFAULT_VARS: Record<string, unknown> = {
+  prKey: "o/r#1",
+  repo: "o/r",
+  prNumber: 1,
+  prUrl: "https://example.test/pr/1",
+  round: 1,
+  maxRounds: 20,
+  reviewWaitTimeout: "PT30M",
+  ackRetryRound: 0,
+  ackRetryMax: 2,
+  abandonUrl: "https://hooks.test/abandon?token=seed",
+  abandonBrief: "\n\n---\nAbort if cancelled: curl …",
+  status: null,
+  question: null,
+  summary: null,
+  answer: null,
+  scopePending: false,
+  scopeAnswer: null,
+  convergeBlocked: null,
+  convergeBlockReason: null,
+  convergeAckOnly: null,
+  reviewStale: null,
+  roundEntryHead: null,
+  huskRetries: 0,
+  progressed: true,
+  escalated: null,
+  humanApproval: false,
+  convergeOnly: false,
+};
+
+const engines: WasmEngineClient[] = [];
+after(async () => {
+  await Promise.all(engines.map((e) => e.close()));
+});
+
+async function boot(opts: { responses?: Record<string, Responder>; vars?: Record<string, unknown> } = {}) {
+  const engine = await createWasmEngineClient();
+  engines.push(engine);
+  await engine.deployResources([{ name: "convergence-loop.bpmn", content: MODEL, contentType: "text/xml" }]);
+  const responses = { ...DEFAULT_RESPONSES, ...(opts.responses ?? {}) };
+  for (const jobType of ALL_JOB_TYPES) {
+    const responder = responses[jobType];
+    await engine.registerWorker(jobType, (job) =>
+      typeof responder === "function" ? responder(job as { variables: Record<string, unknown> }) : (responder ?? {}),
+    );
+  }
+  const created = await engine.createInstance({
+    processDefinitionId: "convergence-loop",
+    awaitCompletion: false,
+    variables: { ...DEFAULT_VARS, ...(opts.vars ?? {}) },
+  });
+  return { engine, processInstanceKey: created.processInstanceKey };
+}
+
+function instanceVars(engine: WasmEngineClient): Record<string, unknown> {
+  const snap = engine.snapshot() as { instances?: { variables?: Record<string, unknown> }[] };
+  return snap.instances?.[0]?.variables ?? {};
+}
+
+/** Read one variable's deserialized value via the engine read channel — works on a COMPLETED instance. */
+async function variableValue(engine: WasmEngineClient, processInstanceKey: string, name: string): Promise<unknown> {
+  const rows = await engine.searchVariables({ processInstanceKey, name });
+  const row = rows.find((v) => v.name === name);
+  assert(row, `expected variable ${name} to be present`);
+  return JSON.parse(row.value);
+}
+
+test("a review-round agent echoing round:\"4\" does not clobber the engine-owned counter or wedge gw-guard", async () => {
+  const { engine } = await boot({
+    responses: { "senior:pr-review": { status: "addressed", summary: "fixed", round: "4" } },
+  });
+  // gw-guard evaluates `round >= maxRounds`. If the agent's string "4" clobbered `round`, the engine
+  // raises "comparison not defined for string and number" and parks the token on an open incident.
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident must be raised; got: ${JSON.stringify(incidents)}`);
+  // The engine-owned counter must remain the integer it was — untouched by the agent's echo.
+  assertEquals(instanceVars(engine).round, 1, "engine-owned `round` must stay the integer 1, unclobbered");
+});
+
+test("a review-round agent echoing numeric engine counters cannot alter them", async () => {
+  // A well-formed numeric echo must still be ignored — the agent owns NONE of these control variables.
+  const { engine } = await boot({
+    responses: {
+      "senior:pr-review": { status: "addressed", summary: "fixed", round: 99, maxRounds: 1, prKey: "evil/repo#999" },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.round, 1, "round must be unchanged");
+  assertEquals(vars.maxRounds, 20, "maxRounds must be unchanged");
+  assertEquals(vars.prKey, "o/r#1", "prKey correlation key must be unchanged");
+});
+
+test("a review-round agent echoing PR identity inputs cannot alter them", async () => {
+  // `repo`/`prNumber`/`prUrl` are the agent's declared *inputs* (PrReviewRoundIn), not its outputs —
+  // but the engine merges a completion UNFILTERED, so an input-echo would replace the valid process
+  // identity that `progress-check`, `converge-gate`, and `finalize` go on to read. The snapshot/restore
+  // guard must pin them.
+  const { engine } = await boot({
+    responses: {
+      "senior:pr-review": {
+        status: "addressed",
+        summary: "fixed",
+        repo: "evil/repo",
+        prNumber: 999,
+        prUrl: "https://evil.test/pr/999",
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.repo, "o/r", "repo must be unchanged");
+  assertEquals(vars.prNumber, 1, "prNumber must be unchanged");
+  assertEquals(vars.prUrl, "https://example.test/pr/1", "prUrl must be unchanged");
+});
+
+// The adversarial reviewer (`senior:adversarial-review`) and scope classifier
+// (`senior:scope-classify`) are hardened by the SAME snapshot/restore mappings as `review-round`;
+// these drive each of those tasks with an engine-owned-field echo so removing either task's guard
+// turns this suite red (the `review-round` regressions above would stay green).
+
+test("an adversarial-review agent echoing engine counters cannot alter them", async () => {
+  // advMax: 1 makes the adversarial pass due on round 1. The agent echoes `advPass`/`advMax` (and a
+  // counter) as the WRONG type; the guard must keep the engine's own increment (0 → 1) and budget.
+  const { engine } = await boot({
+    vars: { advMax: 1 },
+    responses: {
+      "senior:adversarial-review": { adversarialFindings: "", adversarialSummary: "clean", advPass: "7", advMax: "0", round: "9" },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.advPass, 1, "advPass must be the engine increment (0 → 1), not the agent's \"7\"");
+  assertEquals(vars.advMax, 1, "advMax budget ceiling must be unchanged");
+  assertEquals(vars.round, 1, "round must be unchanged");
+});
+
+test("an adversarial-review agent echoing PR identity inputs cannot alter them", async () => {
+  const { engine } = await boot({
+    vars: { advMax: 1 },
+    responses: {
+      "senior:adversarial-review": {
+        adversarialFindings: "",
+        adversarialSummary: "clean",
+        repo: "evil/repo",
+        prNumber: 999,
+        prUrl: "https://evil.test/pr/999",
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.repo, "o/r", "repo must be unchanged");
+  assertEquals(vars.prNumber, 1, "prNumber must be unchanged");
+  assertEquals(vars.prUrl, "https://example.test/pr/1", "prUrl must be unchanged");
+});
+
+test("a scope-classify agent echoing engine-owned fields cannot alter them", async () => {
+  // Drive to the scope classifier via a `converged` review. The classifier echoes prKey + the PR
+  // identity inputs; the guard must keep them. The instance runs to completion, so read the
+  // variables back through the read channel (a completed instance's `snapshot().variables` is folded).
+  const { engine, processInstanceKey } = await boot({
+    responses: {
+      "senior:pr-review": { status: "converged", summary: "done" },
+      "senior:scope-classify": {
+        scopeBlocked: false,
+        scopeBlockReason: "",
+        prKey: "evil/repo#999",
+        repo: "evil/repo",
+        prNumber: 999,
+        prUrl: "https://evil.test/pr/999",
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(await variableValue(engine, processInstanceKey, "prKey"), "o/r#1", "prKey correlation key must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "repo"), "o/r", "repo must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "prNumber"), 1, "prNumber must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "prUrl"), "https://example.test/pr/1", "prUrl must be unchanged");
+});
+
+// ---------------------------------------------------------------------------
+// Issue #887 (round 3): the seeded merge-control gates `humanApproval` and
+// `convergeOnly` are ALSO engine-owned and must survive an agent completion.
+// A converged review that echoes `humanApproval:false` would bypass `gw-approval`
+// (skip the required human merge approval), and `convergeOnly:false` would hand a
+// review-only PR to the merge loop. The snapshot/restore guard pins both.
+//
+// `humanApproval` is MONOTONIC (false→true only — the host flips it true via
+// `engine.setVariables` when a gated caller adopts a live loop, app/service.ts).
+// So its restore is `(guardHumanApproval = true) or (humanApproval = true)`: it
+// recovers a snapshot-true against an agent's false AND preserves a concurrent
+// host-set true, but never lets an agent force it back to false.
+// ---------------------------------------------------------------------------
+
+test("a review-round agent echoing humanApproval:false cannot bypass the approval gate", async () => {
+  // Seeded gated (humanApproval:true). The agent echoes false; the monotonic restore must keep it true.
+  const { engine } = await boot({
+    vars: { humanApproval: true },
+    responses: { "senior:pr-review": { status: "addressed", summary: "fixed", humanApproval: false } },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(instanceVars(engine).humanApproval, true, "seeded humanApproval:true must survive the agent's false echo");
+});
+
+test("a review-round agent echoing convergeOnly:false cannot re-target a review-only run at the merge loop", async () => {
+  // Seeded review-only (convergeOnly:true). The agent echoes false; the restore must keep it true.
+  const { engine } = await boot({
+    vars: { convergeOnly: true },
+    responses: { "senior:pr-review": { status: "addressed", summary: "fixed", convergeOnly: false } },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(instanceVars(engine).convergeOnly, true, "seeded convergeOnly:true must survive the agent's false echo");
+});
+
+test("an adversarial-review agent echoing humanApproval/convergeOnly cannot alter the seeded gates", async () => {
+  const { engine } = await boot({
+    vars: { advMax: 1, humanApproval: true, convergeOnly: true },
+    responses: {
+      "senior:adversarial-review": {
+        adversarialFindings: "",
+        adversarialSummary: "clean",
+        humanApproval: false,
+        convergeOnly: false,
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.humanApproval, true, "humanApproval gate must be unchanged");
+  assertEquals(vars.convergeOnly, true, "convergeOnly flag must be unchanged");
+});
+
+test("a scope-classify agent echoing humanApproval/convergeOnly cannot alter the seeded gates", async () => {
+  // Drive to the scope classifier via a `converged` review with the gates seeded true; the classifier
+  // echoes them false. With humanApproval:true the instance then parks at the merge-approval user task
+  // (still ACTIVE), so read the gates back through the variables channel after classify-scope ran.
+  const { engine, processInstanceKey } = await boot({
+    vars: { humanApproval: true, convergeOnly: true },
+    responses: {
+      "senior:pr-review": { status: "converged", summary: "done" },
+      "senior:scope-classify": {
+        scopeBlocked: false,
+        scopeBlockReason: "",
+        humanApproval: false,
+        convergeOnly: false,
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(await variableValue(engine, processInstanceKey, "humanApproval"), true, "humanApproval gate must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "convergeOnly"), true, "convergeOnly flag must be unchanged");
+});
+
+// ---------------------------------------------------------------------------
+// Issue #887 (round 4 — Copilot "previously missed"): `reviewStale` and
+// `roundEntryHead` are ALSO process-owned and readable by downstream decisions,
+// so an agent completion must not overwrite them:
+//   * `f_guardMax` escalates only when `round >= maxRounds and reviewStale != true`
+//     — a forged `reviewStale:true` suppresses the max-round escalation.
+//   * `check-progress` (pr.progress-check) consumes `roundEntryHead` as the
+//     within-round baseline — a forged head falsifies the progress decision.
+// The snapshot/restore guard pins both on all three agent tasks.
+// ---------------------------------------------------------------------------
+
+test("a review-round agent echoing reviewStale:true cannot suppress the max-round escalation", async () => {
+  // Seeded at the max-round boundary with reviewStale false. The agent echoes reviewStale:true;
+  // without the guard, gw-guard's `reviewStale != true` arm would go false and suppress escalation.
+  const { engine } = await boot({
+    vars: { round: 20, maxRounds: 20, reviewStale: false },
+    responses: { "senior:pr-review": { status: "addressed", summary: "fixed", reviewStale: true } },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(instanceVars(engine).reviewStale, false, "seeded reviewStale:false must survive the agent's true echo");
+});
+
+test("a review-round agent echoing a forged roundEntryHead cannot falsify the progress baseline", async () => {
+  // capture-head seeds roundEntryHead="sha-entry"; the agent echoes a forged head. The restore must keep it.
+  const { engine } = await boot({
+    responses: { "senior:pr-review": { status: "addressed", summary: "fixed", roundEntryHead: "sha-forged" } },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(instanceVars(engine).roundEntryHead, "sha-entry", "captured roundEntryHead must survive the agent's forged echo");
+});
+
+test("an adversarial-review agent echoing reviewStale/roundEntryHead cannot alter them", async () => {
+  const { engine } = await boot({
+    vars: { advMax: 1, reviewStale: false },
+    responses: {
+      "senior:adversarial-review": {
+        adversarialFindings: "",
+        adversarialSummary: "clean",
+        reviewStale: true,
+        roundEntryHead: "sha-forged",
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.reviewStale, false, "reviewStale must be unchanged");
+  assertEquals(vars.roundEntryHead, "sha-entry", "roundEntryHead must be unchanged");
+});
+
+test("a scope-classify agent echoing reviewStale/roundEntryHead cannot alter them", async () => {
+  // Drive to the scope classifier via a `converged` review; the classifier echoes both. With
+  // humanApproval:false the instance runs to completion, so read the vars back via the channel.
+  const { engine, processInstanceKey } = await boot({
+    vars: { reviewStale: false },
+    responses: {
+      "senior:pr-review": { status: "converged", summary: "done" },
+      "senior:scope-classify": {
+        scopeBlocked: false,
+        scopeBlockReason: "",
+        reviewStale: true,
+        roundEntryHead: "sha-forged",
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(await variableValue(engine, processInstanceKey, "reviewStale"), false, "reviewStale must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "roundEntryHead"), "sha-entry", "roundEntryHead must be unchanged");
+});
+
+// ---------------------------------------------------------------------------
+// Issue #887 (round 5 — Copilot "previously missed"): `abandonUrl` and
+// `abandonBrief` are ALSO seeded engine-owned state readable by downstream
+// persistence and prompt mappings:
+//   * `abandonUrl` is the cooperative-abandon capability recorded by
+//     `pr.persist-round`/`pr.persist-escalation`/`pr.finalize` (EscalationIn.abandonUrl,
+//     PrPersistRoundIn.abandonUrl, PrFinalizeIn.abandonUrl) — a forged echo
+//     redirects the abandon token persisted for a human.
+//   * `abandonBrief` feeds the `appendPrompt` input of the NEXT agent task
+//     (`=(if (abandonBrief = null) then "" else abandonBrief)`) — a non-string
+//     echo makes that later prompt mapping carry a non-string / wrong brief.
+// The snapshot/restore guard pins both on all three agent tasks. (The reserved
+// dotted `io.nanobpm.agentTask` envelope was DECLINED — it has no FEEL-path
+// access and a backtick-escaped restore, untested on this engine, would null the
+// fleet-critical repository envelope; see the PR discussion.)
+
+test("a review-round agent echoing abandonUrl/abandonBrief cannot clobber the seeded capability or brief", async () => {
+  const { engine } = await boot({
+    responses: {
+      "senior:pr-review": {
+        status: "addressed",
+        summary: "fixed",
+        abandonUrl: "https://evil.test/abandon?token=forged",
+        abandonBrief: 42,
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.abandonUrl, "https://hooks.test/abandon?token=seed", "seeded abandonUrl must survive the agent's forged echo");
+  assertEquals(vars.abandonBrief, "\n\n---\nAbort if cancelled: curl …", "seeded abandonBrief must survive the agent's non-string echo");
+});
+
+test("an adversarial-review agent echoing abandonUrl/abandonBrief cannot alter them", async () => {
+  const { engine } = await boot({
+    vars: { advMax: 1 },
+    responses: {
+      "senior:adversarial-review": {
+        adversarialFindings: "",
+        adversarialSummary: "clean",
+        abandonUrl: "https://evil.test/abandon?token=forged",
+        abandonBrief: 42,
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.abandonUrl, "https://hooks.test/abandon?token=seed", "abandonUrl must be unchanged");
+  assertEquals(vars.abandonBrief, "\n\n---\nAbort if cancelled: curl …", "abandonBrief must be unchanged");
+});
+
+test("a scope-classify agent echoing abandonUrl/abandonBrief cannot alter them", async () => {
+  const { engine, processInstanceKey } = await boot({
+    responses: {
+      "senior:pr-review": { status: "converged", summary: "done" },
+      "senior:scope-classify": {
+        scopeBlocked: false,
+        scopeBlockReason: "",
+        abandonUrl: "https://evil.test/abandon?token=forged",
+        abandonBrief: 42,
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(await variableValue(engine, processInstanceKey, "abandonUrl"), "https://hooks.test/abandon?token=seed", "abandonUrl must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "abandonBrief"), "\n\n---\nAbort if cancelled: curl …", "abandonBrief must be unchanged");
+});

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;