@nanobpm/nano-workforce 0.200.9 → 0.201.1

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.201.1](https://github.com/nanobpm/nano-workforce/compare/v0.201.0...v0.201.1) (2026-10-07)
+
+### Bug Fixes
+
+* **delivery-graph:** actionable node escalations — node-local agent results, retry-node, inputs preflight ([#863](https://github.com/nanobpm/nano-workforce/issues/863)) ([50f7595](https://github.com/nanobpm/nano-workforce/commit/50f7595f3156b2e1e9d52e30e87d3e1c22951dc8)), closes [nano-bpm#1335](https://github.com/nanobpm/nano-bpm/issues/1335) [nano-bpm#1334](https://github.com/nanobpm/nano-bpm/issues/1334) [nano-bpm#1336](https://github.com/nanobpm/nano-bpm/issues/1336) [nanobpm/nano-workforce#866](https://github.com/nanobpm/nano-workforce/issues/866) [nano-bpm#1336](https://github.com/nanobpm/nano-bpm/issues/1336) [nano-bpm#1334](https://github.com/nanobpm/nano-bpm/issues/1334) [nano-bpm#946](https://github.com/nanobpm/nano-bpm/issues/946) [#543](https://github.com/nanobpm/nano-workforce/issues/543) [#866](https://github.com/nanobpm/nano-workforce/issues/866) [#778](https://github.com/nanobpm/nano-workforce/issues/778) [#772](https://github.com/nanobpm/nano-workforce/issues/772) [#772](https://github.com/nanobpm/nano-workforce/issues/772) [#461](https://github.com/nanobpm/nano-workforce/issues/461) [#876](https://github.com/nanobpm/nano-workforce/issues/876)
+
+## [0.201.0](https://github.com/nanobpm/nano-workforce/compare/v0.200.9...v0.201.0) (2026-10-06)
+
+### Features
+
+* **convergence:** escalate non-converging same-surface review churn ([#870](https://github.com/nanobpm/nano-workforce/issues/870)) ([#875](https://github.com/nanobpm/nano-workforce/issues/875)) ([307505b](https://github.com/nanobpm/nano-workforce/commit/307505b3e9603129c3ad101b29dc1f10992f038e))
+
+### Bug Fixes
+
+* **delivery-graph:** bind escalation value to emit, fail closed on null gate target, default node SLA ([#876](https://github.com/nanobpm/nano-workforce/issues/876)) ([ff6f3d0](https://github.com/nanobpm/nano-workforce/commit/ff6f3d0f191b641c13e460ac03c8ecfa075026f4)), closes [#872](https://github.com/nanobpm/nano-workforce/issues/872) [#872](https://github.com/nanobpm/nano-workforce/issues/872) [#872](https://github.com/nanobpm/nano-workforce/issues/872) [owner/repo#N](https://github.com/owner/repo/issues/N) [#872](https://github.com/nanobpm/nano-workforce/issues/872) [#872](https://github.com/nanobpm/nano-workforce/issues/872)
+
 ## [0.200.9](https://github.com/nanobpm/nano-workforce/compare/v0.200.8...v0.200.9) (2026-10-05)
 
 ### Bug Fixes

package/SPEC.md

@@ -372,6 +372,41 @@ Notes:
   poller does not solicit a spurious review against the still-running round. The
   round cap and the review-wait timeout remain the outer safety nets.
 
+- **Non-converging same-surface churn guard (issue #870).** The no-progress guard
+  above catches a round that pushed NOTHING. Churn is the opposite failure mode: a
+  loop where EVERY round pushes a commit (so the head advances and the round
+  legitimately "progresses") yet never reaches a fixed point — a contested surface
+  (e.g. a fail-closed analyzer whose bypass forms are unbounded) keeps producing new
+  findings in the SAME file round after round, and the loop runs to `maxRounds`
+  without a human ever being asked to make the scope call. So on a head-advancing
+  `addressed` round, BEFORE parking for the next review, `pr.progress-check` reads
+  the PR's durable `rounds` history (`app/roundChurn.ts` `detectChurn`, the single
+  canonical detector) and escalates when the trailing run of CONSECUTIVE `addressed`
+  rounds is at least `CHURN_WINDOW` (4) long AND some single file appears in EVERY
+  round of that window. Requiring the SAME file across the whole window keeps normal
+  convergence — findings that move between areas and trend down — from escalating
+  early. The file names are mined from each round's free-text `summary` (URL spans
+  stripped, so a cited link is never mistaken for a repo path). When it fires, the
+  round routes to the SAME human escalation path the no-advance guard uses (`gw-husk`
+  → `persist-escalation-noprogress`) carrying a `noProgressReason:"churn"` SCOPE
+  question — it never parks at `waiting_review`. Two invariants keep the signal
+  honest across runs and resumes:
+    - **Run-scoped history.** The history read is filtered by the job's
+      `process_instance_key` (the `rounds` table is run-scoped — migration 102), so a
+      prior run's retained rows never leak into this run's window. A legacy NULL-key
+      row is dropped (fail-OPEN: dropping a row only ever reduces the churn signal).
+    - **Churn-reset watermark.** A churn escalation writes no `blocked` round
+      (`recordRound=false`) and the human-answer resume re-enters the SAME numeric
+      round (the counter only advances at the review-wait gateway), so the escalating
+      round number is persisted as `pull_requests.churn_escalated_round`
+      (migration 117, cleared on re-open with the rest of the per-run state).
+      `detectChurn` drops every round at or before that watermark, so the human's
+      scope decision restarts the churn clock: churn can only fire again after a
+      fresh `CHURN_WINDOW` of same-file rounds accumulates past the decision, exactly
+      as a recorded `needs_input`/`blocked` round would restart it.
+    A head that cannot be read, and a history read that throws, both fail OPEN (no
+    churn escalation) — a transient GitHub/datasource hiccup never fabricates one.
+
 - **Stale-output reset on round entry (issue #822).** `pr.capture-head` — the
   single task every entry into `review-round` routes through first (from `Start`,
   the review-loop re-enter, the human-answer resume, the husk auto-retry, and the
@@ -1004,6 +1039,159 @@ decision. The target behaviour is an **autonomy ladder**:
 A human escalation is then reserved for its one true case: **two slices that each pass
 but encode incompatible decisions about a shared contract** — a genuine design call.
 
+## 13.3 Delivery-graph node escalation — Continue / Retry / reset (PR #863)
+
+The delivery-graph compiler (`app/deliveryGraphCompiler.ts`, ADR 0005) compiles each
+`agent`/`connector` node to a `start → serviceTask → end` subProcess guarded by a
+**bounded `=nodeTimeout` boundary**. On timeout (or, for an `agent`, on a broken
+producer contract — issue #731) the stalled node parks on a **human-completable
+escalation user task** (`delivery-human-task__<el>__esc`, and the agent-only
+`__contract` twin), surfaced in the Tasks inbox and answerable by a human or an agent
+(ADR 0046). Every such escalation names **two exits** (the `delivery-escalation` form's
+`decision` select):
+
+- **Continue** (`decision="continue"`, the default) completes the node as resolved. If
+  the node declares **exactly one** emit **and that emit is a downstream-required fact**,
+  the form presents a typed-value field and maps
+  the operator-supplied `value` onto the node's emit-source var (`factSourceVar`), so the
+  subProcess output publishes the same `<el>_<fact>` a normal completion would —
+  letting work finished out of band (a draft PR the stalled agent already opened) be
+  handed onward instead of threading a null downstream. This applies to **both** `agent`
+  and `connector` emits: a connector has no producer-contract gate, so its resume keys
+  off the node's **own** declared `emits` (emit source = the fact's own name), never the
+  agent-only gate metadata. The single-emit boundary is a hard cardinality rule: the
+  form captures ONE value, so a node declaring **zero** emits has nothing to resume (the
+  field stays blank) and a node declaring **two or more** emits is **not** value-resumable
+  — one value cannot satisfy multiple distinct typed facts without corrupting them.
+  **The value is also inert for a node with no *required* (downstream-consumed) resume
+  target** — the resume keys off the **required** emit set, not the raw declared set, so a
+  node whose facts nothing downstream reads has no required resume target and its `value` is
+  discarded (there is nothing to publish it to). This covers a node that declares **zero**
+  emits, exactly **one** routing-only/unconsumed emit, or **several** routing-only/unconsumed
+  emits alike: because the required resume set (`resumeEmits`) is empty, **no post-escalation
+  validation gate is compiled at all**, so **Continue simply proceeds past the node to its
+  default (fallback) branch** — there is nothing to re-park (`serviceBodyLines` /
+  `escalationTaskLines` add the `validTarget` gate only when `resumeEmits` is non-empty). The
+  fail-closed validation gate exists **only** for a node that still owes a **required** emit:
+  there, on Continue it **fails closed and loops
+  back to the escalation** (it does NOT write nulls and does NOT advance to a fallback branch)
+  — **Retry this step** is the only way to actually produce the facts, except that a node
+  declaring exactly **one** emit — that single declared emit being its only required resume
+  target — may instead satisfy it by entering the coerced `value` (the value field stays inert
+  for a node declaring two or more emits even when only one is required, matching
+  `declaredEmits.length === 1 && emits.length === 1` in the compiler).
+  (A **wait** gate owing **two or more**
+  emits is a special case: it has no Retry exit and its single value field can resume
+  none of them, so its escalation grows **no** validation gate at all and Continue simply
+  acknowledges and proceeds to the node end — see issue #863 — rather than looping forever.)
+  Because the form
+  captures `value` as textfield **text**, the single-emit resume **coerces/validates it to
+  the emit's declared type** before publishing (`escalationResumeValueFeel`): a `boolean`
+  emit accepts `"true"`/`"false"` **case-insensitively and surrounding-whitespace-trimmed**
+  (the validity gate and the coercion share one `lower case(trim(string(value)))`
+  normalization, so a value one accepts the other can never convert differently) and
+  publishes a real boolean, a `number` emit parses via `number(trim(string(value)))`, and
+  any other (text-valued) type passes through. An **invalid** entry
+  publishes `null` — the defined failure path — so a required-emit producer gate escalates
+  and a guarded split takes its default rather than routing on a mistyped value (a raw
+  `"true"` string would silently skip a `= true` guard).
+- **Retry this step** (`decision="retry"`) re-runs the node. A none intermediate throw
+  event (never a scriptTask) resets the node-local scratch — the decision, the captured
+  `value`/`escalationNote`, and (for an agent) the **full declared result set**
+  (`AGENT_RESULT_LOCAL_VARS` — the self-reported `status`/`summary`/… **and** every other
+  node-local result field such as `transcriptUrl`, `agentCheckpoint`, and the PR aliases)
+  — or, **for a connector**, its fixed result metadata (`CONNECTOR_RESULT_LOCAL_VARS` —
+  `connectorOutcome`/`connectorDedupeKey`/`connectorDetail`) — plus the previous attempt's
+  emits — and appends the operator's `escalationNote` to the agent
+  prompt as guidance for the next attempt (re-derived from the runner-seeded
+  `nodeInputs.<el>.appendPrompt` baseline, so consecutive retries never accumulate stale
+  guidance). The guidance control is the escalation-specific `escalationNote`, never the
+  plain `note`: `note` is a worker **result** field (`plan.md` returns one) that
+  nearest-scope propagation lands in the same subProcess scope, so reading it would feed a
+  worker-produced note back as "operator guidance" on a retry submitted without one. Clearing
+  the whole declared set (not just the status fields) stops a retried
+  worker that omits an optional field from republishing the previous attempt's value
+  downstream or surfacing it in the next escalation.
+
+All retry/reset targets are **node-local** (declared on the subProcess by
+`ioMappingLines`), so a node's result vars never leak to the root and two parallel nodes
+declaring the same emit never cross-publish — with a few deliberate publish-onward
+exceptions, all written under node-unique or intentionally-shared names rather than the
+raw result var. The **outward data** exceptions: each declared emit is republished to the
+root as `<el>_<fact>` (node-unique, so siblings never collide), and an agent's
+`transcriptUrl` is propagated back to the root under the shared `transcriptUrl` name so
+Nano Explorer can render the run→transcript link (app/deliveryGraphCompiler.ts:1872-1877).
+That one shared name means parallel agents can overwrite the root `transcriptUrl` —
+acceptable, since it is a display-only correlation link, not a result a downstream node
+binds. In addition, the per-node **control signals** `<el>_contractMet` (the agent
+contract-gate's proceed flag) and `<el>_retryRequested` (the per-escalation retry gate's
+route flag) are **also root-scoped** — their gateways live outside the node's subProcess
+and so cannot read node scope, and the `<el>_`-prefixed, node-unique names can never
+collide across parallel nodes. So the node-local rule governs a node's *result/emit scratch*;
+these node-unique control booleans are intentionally published to root so the routing
+gateways can read them on either engine's scope semantics. A **preflight `assert`** on the inner leaf
+task's input fails LOUD (raising an incident naming the missing `nodeInputs.<el>`)
+before any job exists when the runner-seeded config was lost — see the `KNOWN
+LIMITATION` in `serviceBodyLines` (fail-loud-only, nano-workforce#866). Resolving that
+incident re-evaluates **only the leaf's inputs** — the subProcess-level config mappings
+(`prompt`/`appendPrompt`/`nodeTimeout`, connector `target`/`payload`/`dedupeKey`) ran once
+at subProcess entry and are **not** re-mapped on a leaf resolve, so the node would
+activate **unconfigured**. The in-subprocess **"Retry this step"** loop does **not**
+help here either: it loops directly back to the inner service task (to reset the
+node-local scratch), bypassing the subProcess entry mappings, so it too leaves the
+config null. **Recovery therefore requires re-entering the sub-process from OUTSIDE —
+relaunch/re-enter the node so its subProcess input mappings re-evaluate against the
+restored `nodeInputs`** — not merely resolving the incident or using "Retry this step".
+The correct in-model fix is to run this check at sub-process *entry* (Camunda parity,
+nano-bpm#1336); until then the preflight fails loud so the node never runs blind
+*without* an incident, and the operator re-enters the sub-process to recover.
+
+Because an `agent`/`connector` node's emit source **is the fact's own name**, declared
+node-local in the same subProcess scope as the escalation form controls and the node's
+seeded config, a fact name is not fully unrestricted: `validateDeliveryGraph` rejects an
+emit named after a **reserved delivery variable** (`reservedDeliveryFactNames(kind)`,
+app/deliveryGraph.ts) fail-closed at authoring time. The reserved set is **kind-aware**
+(issue #863 review): the **escalation controls** (`decision`/`value`/`escalationNote` — an escalation
+Continue would overwrite the fact, publishing `<el>_decision="continue"` instead of the
+agent's routing value) and the shared late-binding/preflight **scaffolding**
+(`boundFacts`/`nodeInputs`/`nodeInputsPresent`) are reserved for **every** kind, while a
+**config variable** is reserved only for the kind whose own config it is — and only for
+`agent`/`connector`, the kinds whose emit source is the fact's own name (the retry reset's
+clear-the-emits pass would null the node's own configuration, so the retried node activates
+unconfigured). A `wait`/`human` emit's source is a fixed intermediate (`detail`/
+`humanEmitValue`/…), never the fact's own name, so those kinds reserve only the escalation
+controls + scaffolding — a `wait` emitting `target` or a `human` emitting `prompt` is
+allowed. The node-local **result** fields
+(`AGENT_RESULT_LOCAL_VARS`/`CONNECTOR_RESULT_LOCAL_VARS`) are deliberately **not**
+reserved — with **one exception**: an agent emitting `pr` (the canonical
+`agent → connector[converge] → wait[pr]` shape) writes the same node-local value the
+result field holds, and the retry reset correctly clears both — reserving them would
+forbid that flagship pattern. The exception is the agent completion-control **`status`**:
+the producer status gate reads that same node-local field as the node's completion status
+and accepts only `done`/`opened`/`skipped`, so an agent emit named `status` carrying any
+other routing value (`approved`, …) always escalates, and `status="done"` can never take an
+`approved` branch — the emit contract and the gate conflict. `status` is therefore reserved
+for an **`agent`** (a connector has no producer status gate, so a connector `status` emit
+stays allowed); the rest of the result set remains unreserved.
+
+A **`human` node's required emit is gated fail-closed on completion** (PR #863 review,
+thread r4198662345). A human node has no worker self-report to producer-gate on, but its
+single emit can be a downstream-**required** fact — and the captured value is coerced and
+validated to the emit's declared type (`coerceFactValueFeel`), so an invalid entry becomes
+`null`. Without a completion gate the node ended and the unconditional edge activated the
+consumer with a `null` required fact. The compiler therefore grows a **completion gate**
+when the node's single emit is downstream-required: the user task's own output mapping
+computes a node-unique validity flag (`resumeValidVar`) from the *raw* captured field via
+the **same** per-type `resumeValueCondition` grammar the escalation resume enforces
+(presence included, so a blank required entry is invalid), and a post-task exclusive
+gateway routes a **valid** completion to the node end while an **invalid** one loops back
+to the human task for re-entry — the human analogue of the escalation resume's fail-closed
+re-park (a human node has no separate escalation twin to re-park onto). The gate is grown
+**only** when the single emit is required: a routing-only/unconsumed emit keeps the direct
+`task → end` flow (its `null` simply takes a guarded split's deadlock-safe default, exactly
+like the escalation resume's no-required-target case), and a no-emit acknowledgement node
+has nothing to validate.
+
 ## 14. Open questions / future
 
 - **Provisioning the existing PR branch** — resolved: the `c8ctl` host-git

package/app/agentCompletion.test.ts

@@ -18,6 +18,7 @@ import {
   completeEscalationAsAgent,
   completeEscalationAsHuman,
   completeUserTaskAttributed,
+  escalationFormId,
   latestCompletion,
   revertAgentCompletion,
   type TaskCompletion,
@@ -884,6 +885,57 @@ test("validateEscalationVariables derives its contract from the canonical .form
   assertEquals(validateEscalationVariables("some-other-task", { whatever: 1 }), null);
 });
 
+test("validateEscalationVariables enforces the `decision` select on a delivery-graph service-escalation twin (retry-node)", async () => {
+  // A delivery-graph service-node escalation twin (`…__esc`/`…__contract`) ALWAYS renders the fixed
+  // `delivery-escalation` form, whose `decision` select is {continue, retry}. The canonical completers
+  // must therefore reject a present-but-invalid `decision` (e.g. an agent/direct-API typo `retrry`),
+  // instead of silently computing `retryRequested=false` and taking the deadlock-safe Continue default
+  // — which would skip the node (PR #863 review — MEDIUM "Validate decision values" advisory).
+  const escTwin = "delivery-human-task__n1__esc";
+  const contractTwin = "delivery-human-task__n2__contract";
+  // present-but-invalid decision → rejected on BOTH twin kinds
+  assert(validateEscalationVariables(escTwin, { decision: "retrry" }) !== null, "invalid decision rejected on __esc twin");
+  assert(validateEscalationVariables(contractTwin, { decision: "nope" }) !== null, "invalid decision rejected on __contract twin");
+  // valid decisions pass
+  assertEquals(validateEscalationVariables(escTwin, { decision: "retry" }), null);
+  assertEquals(validateEscalationVariables(escTwin, { decision: "continue" }), null);
+  // decision OMITTED → still valid (defaults to Continue); the generic-form wait-escalation twins, which
+  // never submit `decision`, must not be false-rejected (the form has no required fields).
+  assertEquals(validateEscalationVariables(escTwin, { value: "something", escalationNote: "n" }), null);
+  // the bare per-node human task (NOT a twin) stays unenforced — it renders a different form per node.
+  assertEquals(validateEscalationVariables("delivery-human-task__n1", { decision: "retrry" }), null);
+  // a node literally named `esc` has base id `delivery-human-task__esc` — NOT misread as a twin.
+  assertEquals(validateEscalationVariables("delivery-human-task__esc", { decision: "retrry" }), null);
+});
+
+test("escalationFormId derives the COMPILED form per twin kind — wait-gate twins get the generic form, not the retry form (PR #863 review)", () => {
+  // Regression guard (Copilot thread app/agentCompletion.ts:186): the bare `__esc` suffix is shared by a
+  // service-node timeout twin (retry-capable → `delivery-escalation`) AND a `wait`-gate twin (no retry
+  // path → `delivery-human-generic`). Inferring one form from the suffix misclassified the wait gate, so
+  // the #461 Tasks-inbox `form_key` fallback rendered a bogus "Retry this step" the wait process silently
+  // ignores. The compiler now stamps a `__wait` kind marker into the wait twin's id so the form is
+  // DERIVED from the id.
+  // service-node twins → retry-capable escalation form
+  assertEquals(escalationFormId("delivery-human-task__n1__esc"), "delivery-escalation");
+  assertEquals(escalationFormId("delivery-human-task__n2__contract"), "delivery-escalation");
+  // wait-gate twin (kind marker) → select-less generic form
+  assertEquals(escalationFormId("delivery-human-task__gate__esc__wait"), "delivery-human-generic");
+  // a bare per-node human task (variable form per node) has no static contract
+  assertEquals(escalationFormId("delivery-human-task__n1"), undefined);
+  // a node literally named `esc`/`esc__wait` is NOT misread as a twin (needs a non-empty base before the suffix)
+  assertEquals(escalationFormId("delivery-human-task__esc"), undefined);
+  assertEquals(escalationFormId("delivery-human-task__esc__wait"), undefined);
+});
+
+test("validateEscalationVariables: a wait-gate twin is validated against the generic form (no `decision` select to enforce)", () => {
+  // The wait-gate twin renders the select-less generic form, so a `decision` value is out of contract
+  // there — but the generic form declares no `decision` allowed-set, so the completer does not enforce
+  // one (the wait process ignores `decision` entirely; there is no retry path to guard).
+  const waitTwin = "delivery-human-task__gate__esc__wait";
+  assertEquals(validateEscalationVariables(waitTwin, { value: "pkg@1.2.3" }), null, "a value-only wait-gate resume is valid");
+  assertEquals(validateEscalationVariables(waitTwin, {}), null, "the generic form has no required fields");
+});
+
 test("feature-escalation demands non-blank answer on the answer path, but not on the hidden abandon path", async () => {
   // resolution=answer shows the conditional `answer` field, which is required → blank/missing rejected.
   assert(

package/app/agentCompletion.ts

@@ -24,7 +24,7 @@ import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient, GatewayDataSource } from "@nanobpm/urban";
 import { invalidateAdjudication, invalidateAdjudicationByCompletion } from "./adjudications.ts";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
-import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
+import { DELIVERY_HUMAN_ELEMENT, ESCALATION_FORM, GENERIC_HUMAN_FORM, isDeliveryEscalationTwin, isDeliveryHumanElement, isDeliveryWaitEscalationTwin } from "./deliveryHuman.ts";
 import { ACP_PERMISSION_ELEMENT, EMPTY_PLAN_ELEMENT, PR_MERGE_APPROVAL_ELEMENT, READINESS_ESCALATION_ELEMENT, READINESS_ESCALATION_PF_ELEMENT } from "./userTasks.ts";
 
 const now = () => new Date().toISOString();
@@ -165,17 +165,32 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   // contract is enforced instead by `bindHumanEmits` against the node's declared `emits[]` (binds are
   // validated, not stringly — Decision 3/4), so `validateEscalationVariables` leaves it unenforced
   // (returns `null`) and the completer accepts the captured form variables for the emit binder to type.
+  // (Its SERVICE-node escalation TWINS — `…__esc`/`…__contract` — are different: they render a FIXED
+  // form, so `escalationFormId` maps them to `ESCALATION_FORM` via `isDeliveryEscalationTwin` rather
+  // than listing each per-node id here.)
 };
 
 /** The fixed `.form` linkage (a `zeebe:formDefinition formId`) that governs a fixed-form escalation
- *  kind's completion, or `undefined` for a kind with no static form (the delivery-graph `human` node,
- *  which renders DIFFERENT forms per node — its `formKey` only ever comes from the engine at runtime).
+ *  kind's completion, or `undefined` for a kind with no static form (the per-node delivery-graph `human`
+ *  task, which renders DIFFERENT forms per node — its `formKey` only ever comes from the engine at
+ *  runtime). A delivery-graph SERVICE-node escalation TWIN (`…__esc`/`…__contract`), by contrast, ALWAYS
+ *  renders the fixed {@link ESCALATION_FORM} — a strict superset of the generic form — so it DOES carry a
+ *  static contract here (via {@link isDeliveryEscalationTwin}): this is what lets the canonical completers
+ *  reject a present-but-invalid `decision` (continue/retry) on a retry-node escalation, while leaving the
+ *  select-less generic-form twins unaffected (the form has no required fields, so they never false-reject).
  *  Exposed so the Tasks-inbox poller can denormalise a row's `form_key` from this SAME single source of
  *  truth when the raw `/v2/user-tasks/search` result omits the engine-resolved key (issue #461) — the
  *  REST gateway addresses a deployed form by value whether that value is a deploy key or an authored
  *  form id, so this id resolves the same deployed `.form` the completer validates against. */
 export function escalationFormId(elementId: string): string | undefined {
-  return ESCALATION_FORM_BY_ELEMENT[elementId];
+  // Derive the twin's COMPILED form from its id rather than inferring one form from the shared `__esc`
+  // suffix: a `wait`-gate twin (`…__esc__wait`, kind marker stamped by the compiler) renders the
+  // select-less GENERIC_HUMAN_FORM (no retry path); a service-node `__esc`/`__contract` twin renders the
+  // retry-capable ESCALATION_FORM. Mapping the wait twin to ESCALATION_FORM would denormalise a bogus
+  // "Retry this step" onto its Tasks row (the wait process silently ignores `decision`) whenever the
+  // engine omits `formKey` (PR #863 review, app/agentCompletion.ts:186).
+  if (isDeliveryWaitEscalationTwin(elementId)) return GENERIC_HUMAN_FORM;
+  return ESCALATION_FORM_BY_ELEMENT[elementId] ?? (isDeliveryEscalationTwin(elementId) ? ESCALATION_FORM : undefined);
 }
 
 /** A field's `conditional.hide` rule, parsed from the FEEL subset the `.form` files use
@@ -261,7 +276,7 @@ export function validateEscalationVariables(
   elementId: string,
   variables: Record<string, unknown>,
 ): string | null {
-  const formId = ESCALATION_FORM_BY_ELEMENT[elementId];
+  const formId = escalationFormId(elementId);
   if (!formId) return null;
   const { required, allowed, hideWhen } = formContract(formId);
   for (const key of required) {

package/app/contracts.ts

@@ -559,6 +559,15 @@ export const WIRE_CONTRACTS = {
       "The engine-native AgentInstance/AgentHistory READ path (issue #745/#747, umbrella #746 — the CONSUMER half of the PRODUCER `agentTask.agentDefinition` marker). The Cockpit HISTORICAL transcript + per-turn/instance metrics are sourced from the engine read model through the SINGLE engine-read seam — `@nanobpm/urban`'s `EngineClient.searchAgentInstances`/`searchAgentInstanceHistory`/`getAgentInstance` (added in urban 0.93 / nanobpm/nano-ide#563; the escalation's option (a) — NO `orchestration-cluster-api-js` fork / no second broker-REST client, so the read path is exercised by the testkit WASM double, which records read-as-absence — an empty list / null — while a live engine validates the behavioural parity). ONE narrow reader (`AgentHistoryReader`) + ONE projection (`listAgentInstances`/`readAgentHistory`) in app/agentic/agent-history.ts, served by `GET /agentic/agent-instances` + `GET /agentic/agent-instances/{agentInstanceKey}/history`. Correlation keys are the AGENT-INSTANCE / PROCESS-INSTANCE / ELEMENT-INSTANCE keys (the same #544 per-occupancy element-instance handle the relay correlation uses) — NEVER the slash-bearing `job:<jobKey>` relay stream id, so the #744 gateway-proxy bug class is moot for settled history. The token-granular relay stays the LIVE overlay only (settled history = engine, live tail = relay). Advisory read-only (ADR 0056): it observes the engine read model, never activates/completes a job or gates a sequence flow. The wire shapes (`AgentInstance`/`AgentInstanceList`/`AgentHistoryRecord`/`AgentHistory` + the metrics shapes) are declared in openapi.yaml and reuse the `@nanobpm/agentic/transcript` parity conversation grammar the transcript store already models. Consume this ONE read path — do not add a second agent-history client or a synonym endpoint.",
     shape: "GET /agentic/agent-instances[?processInstanceKey&rootProcessInstanceKey&elementId&status] → AgentInstanceList; GET /agentic/agent-instances/{agentInstanceKey}/history[?role&loopIteration&elementInstanceKey] → AgentHistory",
   },
+  "deliveryGraph.workerResult": {
+    category: "wire",
+    name: "deliveryGraph.workerResult",
+    owner: "app/deliveryGraph.ts",
+    semantics:
+      "The delivery-graph worker-completion RESULT envelope (issue #863) — the canonical set of variable names a fleet worker (agent/connector) or an escalation completion returns on a delivery node's job, which the deliveryGraph compiler declares node-LOCAL on the node's subProcess (and clears on retry) so a parallel node never overwrites a sibling's result and a retry never reads a stale one. Three sibling sets, all exported from app/deliveryGraph.ts (the validator's home, so the reserved-fact-name set derives from them without an import cycle): `AGENT_RESULT_LOCAL_VARS` (status/summary/question/output/error/pr/prUrl/pullRequest/branch/commits/exitCode/next_steps/issue/completed/pushed/truncated/agentCheckpoint/transcriptUrl/delta/approved/findings/commentUrl/hasDeviations/slicesMet/slicesReduced/slicesNotVerified/deviationsRaised/deviationsUnraised, plus the prompt-contract outputs dependsOn/adversarialFindings/adversarialSummary/scopeBlocked/scopeBlockReason/tasks/result/conflicts/failing/note), `CONNECTOR_RESULT_LOCAL_VARS` (connectorOutcome/connectorDedupeKey/connectorDetail), and `ESCALATION_LOCAL_VARS` (decision/value/escalationNote — the escalation-completion controls; the retry-guidance note is `escalationNote`, NOT the plain `note`, which is a plan.md WORKER result field that would otherwise be fed back as operator guidance on a note-less retry). These are job-completion outputs and escalation-form variables, NOT message payloads, so the scalar-only message-envelope rule does not apply (array-typed fields like dependsOn/tasks/conflicts/failing are legal here). A new worker/escalation result field MUST be added to the matching set here — never re-declared as a synonym list in the compiler or a worker — or it leaks to the shared root scope.",
+    shape:
+      "AGENT_RESULT_LOCAL_VARS: readonly string[] (28 base + 10 prompt-contract outputs); CONNECTOR_RESULT_LOCAL_VARS: readonly ['connectorOutcome','connectorDedupeKey','connectorDetail']; ESCALATION_LOCAL_VARS: readonly ['decision','value','escalationNote']",
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {