@nanobpm/nano-workforce 0.201.0 → 0.201.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

package/SPEC.md

@@ -1039,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 = {

package/app/deliveryGraph.test.ts

@@ -480,6 +480,178 @@ test("invalid-fact-name: an emitted fact name over the openapi 128-char cap is r
   assertEquals(err.path, "nodes[0].emits[0].name");
 });
 
+test("invalid-fact-name: an emit named after an escalation control (`decision`/`value`/`escalationNote`) is rejected — a Continue would overwrite the fact (r4181027093)", () => {
+  // Regression guard (PR #863 Copilot High, thread r4181027093): an agent/connector emit's source is the
+  // fact's own name, declared node-local in the SAME scope as the escalation form's `decision`/`value`/
+  // `escalationNote`. An agent emitting `decision` that reaches a contract escalation has its fact overwritten by
+  // the form completion (`decision="continue"`), so the subProcess publishes `<el>_decision="continue"`
+  // instead of the agent's routing value. The validator must reject the whole class fail-closed.
+  // (`note` is NOT an escalation control — it is a plan.md worker RESULT field; the retry-guidance
+  // control is the worker-unwritable `escalationNote`, PR #863 "Previously missed" deliveryGraphCompiler.ts:2156.)
+  for (const name of ["decision", "value", "escalationNote"]) {
+    const errors = validateDeliveryGraph({
+      nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name, type: "string" }] }],
+    });
+    const err = hasCode(errors, "invalid-fact-name");
+    assertEquals(err.path, "nodes[0].emits[0].name", `emit '${name}' is rejected`);
+    assert(err.message.includes("reserved"), `emit '${name}' names the reserved collision, got: ${err.message}`);
+  }
+});
+
+test("invalid-fact-name: an emit named after a connector config variable (`target`/`payload`/`dedupeKey`/`nodeTimeout`) is rejected — a Retry would null the config (r4181027147)", () => {
+  // Regression guard (PR #863 Copilot High, thread r4181027147): the retry reset clears every declared
+  // emit source var; a connector emitting `target`/`payload`/`dedupeKey`/`nodeTimeout` (also subProcess
+  // config vars) has them NULLED without re-entering the input mappings, so the retried connector
+  // activates unconfigured. Reject the collision at authoring time.
+  for (const name of ["target", "payload", "dedupeKey", "nodeTimeout"]) {
+    const errors = validateDeliveryGraph({
+      nodes: [{ id: "c", kind: "connector", connector: { target: "slack:#a" }, emits: [{ name, type: "string" }] }],
+    });
+    const err = hasCode(errors, "invalid-fact-name");
+    assertEquals(err.path, "nodes[0].emits[0].name", `connector emit '${name}' is rejected`);
+  }
+});
+
+test("invalid-fact-name: an emit named after shared late-binding/preflight scaffolding is rejected (boundFacts/nodeInputs/nodeInputsPresent)", () => {
+  // The reserved set also covers the shared subProcess scaffolding that lives in the emit's scope.
+  for (const name of ["boundFacts", "nodeInputs", "nodeInputsPresent"]) {
+    const errors = validateDeliveryGraph({
+      nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name, type: "string" }] }],
+    });
+    const err = hasCode(errors, "invalid-fact-name");
+    assertEquals(err.path, "nodes[0].emits[0].name", `emit '${name}' is rejected`);
+  }
+});
+
+test("a node-local RESULT field is NOT a reserved emit name — an agent may emit `pr` (the canonical converge shape)", () => {
+  // Guard against over-reserving (PR #863 design): the result sets (AGENT_RESULT_LOCAL_VARS /
+  // CONNECTOR_RESULT_LOCAL_VARS) are NOT reserved — an agent emitting `pr` writes the same node-local
+  // value the result field holds, and the retry reset correctly clears both. Reserving them would
+  // forbid the flagship `agent → connector[converge] → wait[pr]` pattern.
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "open", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "pr", type: "pr" }] }],
+  });
+  assertEquals(errors.length, 0, `an agent emitting 'pr' validates, got: ${JSON.stringify(errors)}`);
+});
+
+test("invalid-fact-name: an AGENT emit named `status` is reserved — the producer gate reads that node-local field as its completion status", () => {
+  // Regression guard (PR #863 Copilot Medium "Previously missed", deliveryGraph.ts:418): the result-set
+  // exemption was too broad for an agent emit named `status`. The producer status gate
+  // (`agentContractProceedCondition`) interprets that same node-local field as the completion status and
+  // accepts only `done`/`opened`/`skipped`, while the emit contract may require a different routing
+  // value — `status="approved"` always escalates, and `status="done"` can never take an `approved`
+  // branch. Unlike an aligned result fact such as `pr` (whose emit value and result field agree),
+  // `status` is CONSTRAINED by the gate, so the two uses conflict. Reserve the agent completion-control
+  // `status` while continuing to allow aligned result facts such as `pr`.
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "status", type: "string" }] }],
+  });
+  const err = hasCode(errors, "invalid-fact-name");
+  assertEquals(err.path, "nodes[0].emits[0].name", "an agent emitting 'status' is rejected");
+  assert(err.message.includes("reserved"), `emit 'status' names the reserved collision, got: ${err.message}`);
+  // A CONNECTOR has no producer status gate, so its `status` emit collides with nothing — allowed.
+  const connector = validateDeliveryGraph({
+    nodes: [{ id: "c", kind: "connector", connector: { target: "slack:#a" }, emits: [{ name: "status", type: "string" }] }],
+  });
+  assertEquals(connector.length, 0, `a connector emitting 'status' validates (no producer gate), got: ${JSON.stringify(connector)}`);
+});
+
+test("invalid-fact-name is KIND-AWARE: an agent may emit a connector-only config name (`target`), and vice versa (r4181322008)", () => {
+  // Regression guard (PR #863 Copilot Medium, thread r4181322008): the reserved set reserves only the
+  // node's OWN kind's config. An agent seeds no `target`/`payload`/`dedupeKey` (connector-only), so an
+  // agent emitting `target` collides with nothing; symmetrically a connector seeds no `jobType`/
+  // `appendPrompt` (agent-only). Only the shared `nodeTimeout` is reserved for both.
+  const agentTarget = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "target", type: "string" }] }],
+  });
+  assertEquals(agentTarget.length, 0, `an agent emitting 'target' validates, got: ${JSON.stringify(agentTarget)}`);
+  const connectorJobType = validateDeliveryGraph({
+    nodes: [{ id: "c", kind: "connector", connector: { target: "slack:#a" }, emits: [{ name: "jobType", type: "string" }] }],
+  });
+  assertEquals(connectorJobType.length, 0, `a connector emitting 'jobType' validates, got: ${JSON.stringify(connectorJobType)}`);
+  // …but each kind's OWN config is still reserved (the collision is real there).
+  const agentAppend = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "appendPrompt", type: "string" }] }],
+  });
+  assertEquals(hasCode(agentAppend, "invalid-fact-name").path, "nodes[0].emits[0].name", "an agent emitting its OWN config 'appendPrompt' is rejected");
+  const connectorTarget = validateDeliveryGraph({
+    nodes: [{ id: "c", kind: "connector", connector: { target: "slack:#a" }, emits: [{ name: "target", type: "string" }] }],
+  });
+  assertEquals(hasCode(connectorTarget, "invalid-fact-name").path, "nodes[0].emits[0].name", "a connector emitting its OWN config 'target' is rejected");
+});
+
+test("invalid-fact-name does NOT apply a config restriction to wait/human emits, whose source is a fixed intermediate (r4181322008)", () => {
+  // A wait/human emit's source is NOT the fact's own name (factSourceVar maps it to `detail`/
+  // `humanEmitValue`/…), so its config vars can't collide with an emit source — a wait emitting
+  // `target`/`probe` or a human emitting `prompt`/`emitMode` is fine. Only the escalation
+  // controls + shared scaffolding stay reserved for these kinds.
+  const waitTarget = validateDeliveryGraph({
+    nodes: [{ id: "w", kind: "wait", wait: { kind: "github-check", target: "o/r@main" }, emits: [{ name: "target", type: "string" }, { name: "probe", type: "string" }] }],
+  });
+  assertEquals(waitTarget.length, 0, `a wait emitting 'target'/'probe' validates, got: ${JSON.stringify(waitTarget)}`);
+  // `prompt`/`emitMode` are not reserved for a human node. Assert each as its OWN single-emit human node
+  // — a two-emit human node with no form is separately rejected (`human-unroutable-emits`, thread
+  // deliveryGraphCompiler.ts:1859), which would otherwise mask the reserved-name intent under test here.
+  const humanPrompt = validateDeliveryGraph({
+    nodes: [
+      { id: "h1", kind: "human", human: { prompt: "do it" }, emits: [{ name: "prompt", type: "string" }] },
+      { id: "h2", kind: "human", human: { prompt: "do it" }, emits: [{ name: "emitMode", type: "string" }] },
+    ],
+  });
+  assertEquals(humanPrompt.length, 0, `a human emitting 'prompt'/'emitMode' validates, got: ${JSON.stringify(humanPrompt)}`);
+  // …but the escalation controls + scaffolding are STILL reserved for wait/human.
+  const humanDecision = validateDeliveryGraph({
+    nodes: [{ id: "h", kind: "human", human: { prompt: "do it" }, emits: [{ name: "decision", type: "string" }] }],
+  });
+  assertEquals(hasCode(humanDecision, "invalid-fact-name").path, "nodes[0].emits[0].name", "a human emitting 'decision' (escalation control) is still rejected");
+  const waitScaffold = validateDeliveryGraph({
+    nodes: [{ id: "w", kind: "wait", wait: { kind: "github-check", target: "o/r@main" }, emits: [{ name: "nodeInputs", type: "string" }] }],
+  });
+  assertEquals(hasCode(waitScaffold, "invalid-fact-name").path, "nodes[0].emits[0].name", "a wait emitting 'nodeInputs' (scaffolding) is still rejected");
+});
+
+test("human-unroutable-emits: a human node emitting ≥2 facts with no form is rejected — no static form captures them (thread deliveryGraphCompiler.ts:1859)", () => {
+  // Class guard (PR #863 Copilot High): a human form captures ONE value and a human node has no Retry
+  // path, so a node emitting two or more facts with no explicit `human.formKey` resolves to the
+  // agent-router — no static form holds them — and completing its form would publish null for the
+  // uncapturable emits. Reject the class at authoring time rather than silently starve consumers.
+  const twoScalars = validateDeliveryGraph({
+    nodes: [{ id: "h", kind: "human", human: { prompt: "do it" }, emits: [{ name: "a", type: "string" }, { name: "b", type: "string" }] }],
+  });
+  assertEquals(hasCode(twoScalars, "human-unroutable-emits").path, "nodes[0].emits", "two non-artifact emits with no form are rejected");
+  // The carve-out the finding cites: one scalar + one artifact — the generic form has no resolvedArtifact
+  // control and the publish form no value control, so NO static form captures both. Also rejected.
+  const scalarPlusArtifact = validateDeliveryGraph({
+    nodes: [{ id: "h", kind: "human", human: { prompt: "do it" }, emits: [{ name: "verdict", type: "string" }, { name: "report", type: "artifact" }] }],
+  });
+  assertEquals(hasCode(scalarPlusArtifact, "human-unroutable-emits").path, "nodes[0].emits", "one scalar + one artifact with no form is rejected");
+  // An explicit `human.formKey` is NOT a workaround: the compiled human task's ioMapping reads only the
+  // fixed `value`/`resolvedArtifact`/`note` controls (humanBodyLines), never a bespoke form's per-fact
+  // fields, so a ≥2-emit explicit-form node would STILL publish null for every non-artifact emit.
+  // Reject it too (PR #863 Copilot High, thread r4184443511) — the only correct shape is single-emit
+  // human nodes.
+  const explicitForm = validateDeliveryGraph({
+    nodes: [{ id: "h", kind: "human", human: { prompt: "do it", formKey: "bespoke-multi" }, emits: [{ name: "a", type: "string" }, { name: "b", type: "string" }] }],
+  });
+  assertEquals(hasCode(explicitForm, "human-unroutable-emits").path, "nodes[0].emits", "an explicit human.formKey does NOT make a ≥2-emit node capturable — the ioMapping cannot read its bespoke fields");
+  // Single-emit human nodes are capturable → NOT rejected (the guard must not over-reject).
+  const singleScalar = validateDeliveryGraph({
+    nodes: [{ id: "h", kind: "human", human: { prompt: "do it" }, emits: [{ name: "verdict", type: "string" }] }],
+  });
+  assertEquals(singleScalar.filter((e) => e.code === "human-unroutable-emits").length, 0, "a single non-artifact emit is capturable (generic form)");
+  const singleArtifact = validateDeliveryGraph({
+    nodes: [{ id: "h", kind: "human", human: { prompt: "do it" }, emits: [{ name: "art", type: "artifact" }] }],
+  });
+  assertEquals(singleArtifact.filter((e) => e.code === "human-unroutable-emits").length, 0, "a single artifact emit is capturable (publish form)");
+});
+
+test("a non-reserved emit name still validates (the reserved guard does not over-reject)", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "verdict", type: "string" }, { name: "targetRef", type: "string" }] }],
+  });
+  assertEquals(errors.length, 0, `a non-reserved emit name passes, got: ${JSON.stringify(errors)}`);
+});
+
 test("fact-name `resumeValid` is NOT reserved — a user emit may use it (PR #876 review: the resume-validation gate's flag is an internal compiler-generated var, not a user fact name, so reserving `resumeValid` would needlessly break recompilation of durable rows that already carry a fact of that name)", () => {
   const errors = validateDeliveryGraph({
     nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" }, emits: [{ name: "resumeValid", type: "boolean" }] }],
@@ -722,6 +894,85 @@ test("invalid-job-type: an `agent.jobType` carrying attribute whitespace (LF) is
   hasCode(errors, "invalid-job-type");
 });
 
+test("invalid-form-key: a `human.formKey` carrying an XML-1.0-invalid character is rejected, not silently rewritten into a different executable form id (PR #863 review)", () => {
+  // `human.formKey` is emitted VERBATIM as the executable `<zeebe:formDefinition formId=…>` (it resolves
+  // a deployed `.form` by value). An XML-1.0-forbidden control char would be STRIPPED by the attribute
+  // sanitiser — resolving a DIFFERENT (wrong) form — so it must be rejected, exactly like `agent.jobType`.
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "step", kind: "human", human: { formKey: "my-form\u0001x" } }],
+    edges: [],
+  });
+  hasCode(errors, "invalid-form-key");
+});
+
+test("invalid-form-key: a `human.formKey` carrying attribute whitespace (LF) is rejected — XML attribute-value normalization would fold it to a space, resolving a different form (PR #863 review)", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "step", kind: "human", human: { formKey: "my\nform" } }],
+    edges: [],
+  });
+  hasCode(errors, "invalid-form-key");
+});
+
+test("invalid-form-key: a PRESENT-but-non-string `human.formKey` is rejected, not silently dropped to a generated form (PR #863 review — fail-open class)", () => {
+  // The class: a non-string optional config value bypasses the `typeof === "string"`-gated validators
+  // and is silently accepted, so the compiler falls back to a generated form instead of the author's
+  // declared executable `<zeebe:formDefinition formId=…>` key. Every non-string shape must fail closed.
+  for (const bad of [42, {}, [], true]) {
+    const errors = validateDeliveryGraph({
+      nodes: [{ id: "step", kind: "human", human: { formKey: bad } }],
+      edges: [],
+    });
+    hasCode(errors, "invalid-form-key");
+  }
+});
+
+test("credential-in-form-key: a URL-/credential-shaped `human.formKey` is REJECTED — it is baked verbatim into the executable `<zeebe:formDefinition formId=…>`, so an embedded credential would leak into the compiled BPMN the preview door returns (PR #863 review)", () => {
+  // whole-value URL carrying a `?token=` query (no userinfo needed to be a leak risk)
+  const whole = validateDeliveryGraph({
+    nodes: [{ id: "step", kind: "human", human: { formKey: "https://evil.example/f.form?token=secret" } }],
+    edges: [],
+  });
+  const err = hasCode(whole, "credential-in-form-key");
+  assert(!err.message.includes("token=secret"), `the credential-in-form-key message must redact the query token, got: ${err.message}`);
+  // embedded `//user:pass@host` past an otherwise plausible token
+  hasCode(
+    validateDeliveryGraph({
+      nodes: [{ id: "step", kind: "human", human: { formKey: "my-form //user:pass@evil.example/f" } }],
+      edges: [],
+    }),
+    "credential-in-form-key",
+  );
+  // explicit-scheme embedded URL with a `?token=` query
+  hasCode(
+    validateDeliveryGraph({
+      nodes: [{ id: "step", kind: "human", human: { formKey: "my-form https://evil.example/f?token=secret" } }],
+      edges: [],
+    }),
+    "credential-in-form-key",
+  );
+  // scheme-relative `//host?token=` authority
+  hasCode(
+    validateDeliveryGraph({
+      nodes: [{ id: "step", kind: "human", human: { formKey: "my-form //evil.example/f?token=secret" } }],
+      edges: [],
+    }),
+    "credential-in-form-key",
+  );
+});
+
+test("human.formKey: a clean form id (and a blank/absent one) passes the formKey gates", () => {
+  for (const formKey of ["my-custom-form", "  ", undefined]) {
+    assertEquals(
+      validateDeliveryGraph({
+        nodes: [{ id: "step", kind: "human", human: formKey === undefined ? {} : { formKey } }],
+        edges: [],
+      }).filter((e) => e.code === "invalid-form-key" || e.code === "credential-in-form-key"),
+      [],
+      `formKey ${JSON.stringify(formKey)} must pass the formKey gates`,
+    );
+  }
+});
+
 test("invalid-job-type: a clean `agent.jobType` (no XML-invalid characters, no attribute whitespace) passes validation", () => {
   assertEquals(
     validateDeliveryGraph({