@nanobpm/nano-workforce 0.179.1 → 0.180.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.180.0](https://github.com/nanobpm/nano-workforce/compare/v0.179.2...v0.180.0) (2026-09-04)
+
+### Features
+
+* **delivery-graph:** gate agent-node completion on producer status + required emits ([#735](https://github.com/nanobpm/nano-workforce/issues/735)) ([a765e93](https://github.com/nanobpm/nano-workforce/commit/a765e937dc16f3b8f9dd1e1dedb489be697435e0)), closes [#731](https://github.com/nanobpm/nano-workforce/issues/731) [#731](https://github.com/nanobpm/nano-workforce/issues/731) [#731](https://github.com/nanobpm/nano-workforce/issues/731)
+
+## [0.179.2](https://github.com/nanobpm/nano-workforce/compare/v0.179.1...v0.179.2) (2026-09-04)
+
+### Code Refactoring
+
+* drop redundant testkit engine-client shim in e2e ([#734](https://github.com/nanobpm/nano-workforce/issues/734)) ([8ea7ccd](https://github.com/nanobpm/nano-workforce/commit/8ea7ccd5c38a2b0e363cac74b126dd86bee0f0b1)), closes [#336](https://github.com/nanobpm/nano-workforce/issues/336)
+
 ## [0.179.1](https://github.com/nanobpm/nano-workforce/compare/v0.179.0...v0.179.1) (2026-09-04)
 
 ### Bug Fixes

package/app/deliveryGraphCompiler.test.ts

@@ -30,12 +30,13 @@ async function compileFail(graph: unknown) {
 }
 
 /** The sub-process element id of the PLANNED human user task in a compiled graph — i.e. the
- * delivery-human-task element that is NOT a bounded node's __esc timeout twin. Returns "" if none. */
+ * delivery-human-task element that is NOT a bounded node's escalation twin (`__esc` timeout or
+ * `__contract` producer-gate, issue #731). Returns "" if none. */
 function humanTaskSubEl(bpmn: string): string {
   const parts = bpmn.split('<bpmn:userTask id="delivery-human-task__');
   for (let k = 1; k < parts.length; k++) {
     const id = parts[k].slice(0, parts[k].indexOf('"'));
-    if (!id.endsWith("__esc")) return id;
+    if (!id.endsWith("__esc") && !id.endsWith("__contract")) return id;
   }
   return "";
 }
@@ -293,6 +294,15 @@ function escBlockForNode(bpmn: string, nodeId: string): string {
   return bpmn.slice(start, bpmn.indexOf("</bpmn:userTask>", start));
 }
 
+/** Slice a compiled BPMN to a node's escalation user task body by twin suffix (`esc` timeout or
+ * `contract` producer-gate, issue #731). */
+function escBlockForNodeSuffix(bpmn: string, nodeId: string, suffix: "esc" | "contract"): string {
+  const esc = `delivery-human-task__${elementForNode(bpmn, nodeId)}__${suffix}`;
+  const start = bpmn.indexOf(`<bpmn:userTask id="${esc}"`);
+  assert(start !== -1, `escalation task ${esc} for node ${nodeId} exists`);
+  return bpmn.slice(start, bpmn.indexOf("</bpmn:userTask>", start));
+}
+
 test("#514 Defect A: a capability wait-gate escalation surfaces the probe's last detail, target/match, and observed releases so it is self-diagnosing", async () => {
   const r = await compileOk(CAP_GATE);
   const esc = escBlockForNode(r.bpmn, "n2");
@@ -775,3 +785,92 @@ test("a wait node's onTimeout: fail is rejected at compile with a path-qualified
   assert(hit, `expected a path-qualified onTimeout error, got ${JSON.stringify(errors)}`);
   assert(hit?.message.includes("#978"), `the error names the blocking engine issue, got ${hit?.message}`);
 });
+
+// Issue #731 — the producer-contract gate. An `agent` node's job completing is NOT the node
+// succeeding: a producer that returns a non-terminal `status` (the instance-10746 `in_progress`) or
+// omits a declared emit consumed downstream as a required data dependency must escalate AT the
+// producer, not thread a null/incomplete result into a consumer two nodes downstream. The routing-only
+// emit (referenced only by an edge `when` guard) stays optional — omit ⇒ default branch.
+
+// The canonical `agent → connector[converge-merge]` shape: `open` opens the PR and emits `pr`, which
+// `land` binds as its connector `payload.pr` (a required DATA dependency, threaded on the fact edge).
+const PRODUCER_GATE = {
+  name: "producer gate",
+  nodes: [
+    { id: "open", kind: "agent", agent: { jobType: "senior:feature" }, emits: [{ name: "pr", type: "pr" }] },
+    { id: "land", kind: "connector", connector: { target: "converge-merge", payload: { pr: "open.pr" }, dedupeKey: "land-1" } },
+  ],
+  edges: [{ from: "open.pr", to: "land" }],
+};
+
+test("#731 producer status gate: an agent node inserts a post-completion contract gate that escalates a non-terminal status AT the producer", async () => {
+  const r = await compileOk(PRODUCER_GATE);
+  const el = elementForNode(r.bpmn, "open");
+  // The agent body is no longer `task → end`: the task feeds an exclusive `_gate` whose default routes
+  // a broken producer to a SECOND (contract) escalation task distinct from the `__esc` timeout twin.
+  assert(
+    r.bpmn.includes(`<bpmn:exclusiveGateway id="${el}_gate" name="producer contract met?" default="${el}_g1">`),
+    "the agent task feeds a producer-contract exclusive gate",
+  );
+  assert(r.bpmn.includes(`<bpmn:sequenceFlow id="${el}_i1" sourceRef="${el}_task" targetRef="${el}_gate" />`), "the task flows into the gate, not straight to end");
+  assert(r.bpmn.includes(`<bpmn:userTask id="delivery-human-task__${el}__contract"`), "a producer-contract escalation task exists, distinct from the __esc timeout twin");
+  assert(
+    r.bpmn.includes(`<bpmn:sequenceFlow id="${el}_g1" name="contract broken" sourceRef="${el}_gate" targetRef="delivery-human-task__${el}__contract" />`),
+    "the gate's default (contract-broken) flow parks the producer on its contract escalation",
+  );
+  // The success flow proceeds only on a terminal-success status (or an absent/null status); an
+  // `in_progress`/`blocked`/`failed` self-report falls through to the default → escalation.
+  const g0 = r.bpmn.match(new RegExp(`<bpmn:sequenceFlow id="${el}_g0"[^>]*>(.*?)</bpmn:sequenceFlow>`, "s"));
+  assert(g0, "the contract-met success flow exists");
+  assert(g0![1].includes('list contains(["done", "opened", "skipped"], status)'), "the success flow gates on the terminal-success status allowlist");
+  assert(g0![1].includes("not(is defined(status)) or status = null"), "an absent/null status is not itself the failure mode — it still proceeds");
+  // The contract escalation's read-only context names the node and its reported status (#731).
+  const esc = escBlockForNodeSuffix(r.bpmn, "open", "contract");
+  assert(esc.includes("did not satisfy its producer contract"), "the contract escalation explains WHY it parked");
+  assert(esc.includes("Reported status="), "the context surfaces the actual reported status");
+});
+
+test("#731 required-emit gate: a producer's declared emit consumed as a required data dependency adds a non-null gate clause and a resumable escalation NAMING the fact", async () => {
+  const r = await compileOk(PRODUCER_GATE);
+  const el = elementForNode(r.bpmn, "open");
+  const g0 = r.bpmn.match(new RegExp(`<bpmn:sequenceFlow id="${el}_g0"[^>]*>(.*?)</bpmn:sequenceFlow>`, "s"));
+  assert(g0, "the contract-met success flow exists");
+  // `pr` is threaded to `land`'s connector payload as a required data dependency — so the gate proceeds
+  // only when it is actually populated non-null (a null `pr`, as in instance 10746, escalates here).
+  assert(g0![1].includes("(is defined(pr) and pr != null)"), "a required-emit non-null clause gates the success flow on the populated fact");
+  const esc = escBlockForNodeSuffix(r.bpmn, "open", "contract");
+  assert(esc.includes("Required emit &apos;pr&apos;"), "the escalation NAMES the required fact that was not emitted");
+  // Resumable (#514 Defect-B mirror): a human/agent supplies the missing fact, mapped onto the agent
+  // emit source var (fact name), so the subProcess output ioMapping republishes `<el>_pr` non-null.
+  assert(esc.includes('="typed"') && esc.includes('target="emitMode"'), "the contract escalation PRESENTS its value field (resumable)");
+  assert(/source="=if \(is defined\(value\)\) then value else null" target="pr"/.test(esc), "the operator's value maps onto the required emit's source var");
+});
+
+test("#731 routing-only emits stay optional: a fact referenced ONLY by an edge `when` guard is NOT gated as a required emit (omit ⇒ default branch)", async () => {
+  // `classify` emits `result` used ONLY for guarded routing (`when`/`equals` + a default) — never
+  // threaded as a fact-qualified `from` data dependency. The producer gate must NOT require it non-null.
+  const graph = {
+    name: "routing only",
+    nodes: [
+      { id: "classify", kind: "agent", agent: { jobType: "senior:feature" }, emits: [{ name: "result", type: "string" }] },
+      { id: "migrate", kind: "connector", connector: { target: "npm:install", dedupeKey: "m-1" } },
+      { id: "release", kind: "connector", connector: { target: "npm:publish", dedupeKey: "r-1" } },
+    ],
+    edges: [
+      { from: "classify", to: "migrate", when: "classify.result", equals: "breaking" },
+      { from: "classify", to: "release", default: true },
+    ],
+  };
+  const r = await compileOk(graph);
+  const el = elementForNode(r.bpmn, "classify");
+  const g0 = r.bpmn.match(new RegExp(`<bpmn:sequenceFlow id="${el}_g0"[^>]*>(.*?)</bpmn:sequenceFlow>`, "s"));
+  assert(g0, "the contract-met success flow exists");
+  // The status gate is still present, but there is NO `result` non-null clause — routing stays optional.
+  assert(g0![1].includes("list contains"), "the status gate is still present for the agent node");
+  assert(!g0![1].includes("result"), `a routing-only emit is NOT gated as a required data dependency, got: ${g0![1]}`);
+  // The contract escalation for a status-only gate is inert (no emit resume field).
+  const esc = escBlockForNodeSuffix(r.bpmn, "classify", "contract");
+  assert(esc.includes('="none"') && esc.includes('target="emitMode"'), "a status-only contract escalation keeps its emit field hidden");
+  // The guarded split that routes `result` downstream is untouched (default branch preserved).
+  assert(r.bpmn.includes('=classify_result = "breaking"') || r.bpmn.includes(`${el}_result = "breaking"`), "the routing guard on the emitted fact is preserved");
+});

package/app/deliveryGraphCompiler.ts

@@ -90,6 +90,26 @@ function escalationTaskElement(element: string): string {
   return `${DELIVERY_HUMAN_ELEMENT}__${element}__esc`;
 }
 
+/** The BPMN element id an `agent` node's PRODUCER-CONTRACT escalation user task carries (issue #731) —
+ * distinct from the `__esc` timeout twin so a node can carry both a bounded-timeout escalation AND a
+ * post-completion contract-gate escalation without an id collision. Same human-completable convention
+ * (`delivery-human-task__…` → recognised by `isDeliveryHumanElement`, routed onto the Tasks inbox), so
+ * a producer that finishes without doing its job escalates AT that node and is answerable by a human
+ * OR an agent. */
+function contractEscalationTaskElement(element: string): string {
+  return `${DELIVERY_HUMAN_ELEMENT}__${element}__contract`;
+}
+
+/** The self-reported completion statuses an `agent` node's job may return that count as a TERMINAL
+ * SUCCESS and are allowed to route their result onward (issue #731). Everything else — the pathological
+ * `in_progress` an agent that delegated/returned-before-finishing reports (instance 10746), a `blocked`/
+ * `failed`/`escalated` give-up, or any unrecognised free-formed status — fails the producer status gate
+ * and escalates AT the node instead of threading an incomplete result into a downstream consumer. An
+ * ABSENT/null status passes the gate (a status-less completion — an older fleet worker or a bare test
+ * stub — is not itself the failure mode; the required-emit gate still catches a missing data fact).
+ * Sorted for the compiler's byte-identical-output determinism. */
+const AGENT_TERMINAL_SUCCESS_STATUSES: readonly string[] = ["done", "opened", "skipped"];
+
 /** A never-reached exhaustiveness guard: `compileNode`'s `switch` covers every allowlisted kind, so
  * the closed union narrows to `never` here. If a future kind is added to the vocabulary without a
  * compiler arm, `tsc` flags this call — the compile-time half of the trust bound. */
@@ -532,7 +552,24 @@ export async function compileDeliveryGraphSemantic(
     list.sort((a, b) => byCodeUnit(a.producerElement, b.producerElement) || byCodeUnit(a.fact, b.fact));
   }
 
-  const semanticBpmn = renderBpmn(typed, wirings, numberedFlows, startForkGateway, endJoinGateway, boundInputsByElement);
+  // Producer-side required-emit gate (issue #731): the set of a producer's declared emit names that are
+  // consumed as a REQUIRED DATA DEPENDENCY downstream — i.e. threaded on a FACT-QUALIFIED edge
+  // (`from: "<node>.<fact>"`) into a consumer's connector `payload`/probe `target`. This is the SAME
+  // `<producerElement>_<fact>` wiring `boundInputsByElement` derives, keyed by the PRODUCER element so a
+  // node can gate its own completion on populating every fact a sibling depends on. A ROUTING emit
+  // (referenced only by an edge `when` guard, never as a fact-qualified `from`) is deliberately absent
+  // here — those stay optional (omit ⇒ default branch). Grouped by producer element; only set
+  // membership is ever queried downstream, so the sets carry no ordering guarantee.
+  const requiredEmitsByElement = new Map<string, Set<string>>();
+  for (const edge of resolvedEdges) {
+    if (edge.fromFact === undefined) continue;
+    const producerEl = mustGet(elementById, edge.fromNode);
+    const set = requiredEmitsByElement.get(producerEl) ?? new Set<string>();
+    set.add(edge.fromFact);
+    requiredEmitsByElement.set(producerEl, set);
+  }
+
+  const semanticBpmn = renderBpmn(typed, wirings, numberedFlows, startForkGateway, endJoinGateway, boundInputsByElement, requiredEmitsByElement);
   const diagram = renderMermaid(typed, wirings, resolvedEdges, elementById);
   const resolved = buildResolved(typed, wirings, resolvedEdges, producersById);
   const humanNodes = buildHumanNodes(nodes);
@@ -698,6 +735,11 @@ function buildSideEffects(nodes: readonly DeliveryNode[]): DeliverySideEffect[]
   return effects;
 }
 
+/** Shared empty required-emits set for nodes with no required emits — reused instead of allocating a
+ * fresh `new Set()` per such node while rendering. Safe because `requiredEmits` is only ever read
+ * (`ReadonlySet`). */
+const EMPTY_REQUIRED_EMITS: ReadonlySet<string> = new Set<string>();
+
 /** Render the compiled one-shot BPMN process definition (compile-to-native). Deterministic — element
  * order is fixed (start, gateways, nodes sorted, end) and every id is positional. */
 function renderBpmn(
@@ -707,6 +749,7 @@ function renderBpmn(
   startForkGateway: string | undefined,
   endJoinGateway: string | undefined,
   boundInputsByElement: ReadonlyMap<string, BoundInput[]>,
+  requiredEmitsByElement: ReadonlyMap<string, ReadonlySet<string>>,
 ): string {
   // Precompute incoming/outgoing flow-id maps once (single pass over flows) so BPMN rendering stays
   // linear in the number of flows instead of O(elements * flows) from repeated full-array filtering.
@@ -779,7 +822,15 @@ function renderBpmn(
     if (w.joinGateway) {
       lines.push(...gateway(w.joinGateway, w.joinExclusive, `join into ${w.node.id}`));
     }
-    lines.push(renderNodeElement(w, incoming(w.element), outgoing(w.element), boundInputsByElement.get(w.element) ?? []));
+    lines.push(
+      renderNodeElement(
+        w,
+        incoming(w.element),
+        outgoing(w.element),
+        boundInputsByElement.get(w.element) ?? [],
+        requiredEmitsByElement.get(w.element) ?? EMPTY_REQUIRED_EMITS,
+      ),
+    );
     if (w.forkGateway) {
       lines.push(...gateway(w.forkGateway, w.forkExclusive, `fan out of ${w.node.id}`));
     }
@@ -835,6 +886,7 @@ function renderNodeElement(
   incoming: readonly string[],
   outgoing: readonly string[],
   boundInputs: readonly BoundInput[],
+  requiredEmits: ReadonlySet<string>,
 ): string {
   const el = w.element;
   const name = escapeXml(`${w.node.kind}: ${w.node.id}`);
@@ -843,7 +895,7 @@ function renderNodeElement(
     ...outgoing.map((id) => `      <bpmn:outgoing>${id}</bpmn:outgoing>`),
   ];
   const io = ioMappingLines(w, boundInputs);
-  const inner = innerBodyLines(w);
+  const inner = innerBodyLines(w, requiredEmits);
   const lines = [
     `    <bpmn:subProcess id="${el}" name="${name}">`,
     ...flowRefs,
@@ -965,12 +1017,18 @@ function ioMappingLines(w: NodeWiring, boundInputs: readonly BoundInput[]): stri
  * the S3 scheduled user-task + generic form + SLA. Each is a single-entry / single-exit subgraph with
  * a bounded timeout that escalates onto a human-completable user task (or, for `human`, records an
  * escalated outcome). */
-function innerBodyLines(w: NodeWiring): string[] {
+function innerBodyLines(w: NodeWiring, requiredEmits: ReadonlySet<string>): string[] {
   const el = w.element;
   const node = w.node;
   switch (node.kind) {
-    case "agent":
-      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], node.agent.jobType);
+    case "agent": {
+      // Issue #731: an `agent` node gates its own completion on a producer contract — a terminal-success
+      // self-reported `status` AND a non-null value for every declared emit a downstream consumer binds
+      // as a required data dependency. A broken producer (returns `in_progress`, or omits a required
+      // emit) escalates AT this node instead of threading an incomplete result onward.
+      const contractGate = { requiredEmits: normaliseEmits(node).filter((f) => requiredEmits.has(f.name)) };
+      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], node.agent.jobType, contractGate);
+    }
     case "connector":
       return serviceBodyLines(el, node.id, `type="${DELEGATE_TASK_TYPE.connector}"`, [], `connector → ${node.connector.target}`);
     case "wait":
@@ -986,12 +1044,57 @@ function innerBodyLines(w: NodeWiring): string[] {
  * escalates the stalled node onto a human-completable user task. `taskDefAttr` is the pre-rendered
  * `type="…"` attribute; `taskProps` are optional `<zeebe:property>` envelope lines; `descriptor`
  * names the stalled work (job type / connector target) for the escalation task's context line (#499). */
+/** The FEEL boolean an `agent` node's producer-contract gate (issue #731) evaluates on its `_gate`
+ * exclusive split's SUCCESS flow: the completion proceeds onward only when the self-reported `status`
+ * is a terminal success (or absent/null) AND every required-data-dependency emit is populated non-null.
+ * Reads the job's returned variables from the subProcess scope (the emit source var for an agent fact
+ * is the fact's own name — see {@link factSourceVar}). When it is false the split's DEFAULT flow routes
+ * to the contract-escalation task instead. */
+function agentContractProceedCondition(requiredEmits: readonly DeliveryFact[]): string {
+  const statusList = `[${AGENT_TERMINAL_SUCCESS_STATUSES.map((s) => feelStr(s)).join(", ")}]`;
+  const statusOk = `(not(is defined(status)) or status = null or list contains(${statusList}, status))`;
+  const emitClauses = requiredEmits.map((f) => `(is defined(${f.name}) and ${f.name} != null)`);
+  return `=${[statusOk, ...emitClauses].join(" and ")}`;
+}
+
+/** The read-only context line seeded onto an `agent` node's producer-contract escalation (issue #731),
+ * so the human/agent unsticking it sees WHY it parked — the node, its job type, the actual reported
+ * status, and, per required emit, whether it arrived. Turns the instance-10746 failure (a silent null
+ * thread + two mis-attributed CONSUMER incidents) into one correctly-attributed PRODUCER escalation. */
+function agentContractContextFeel(nodeId: string, descriptor: string, requiredEmits: readonly DeliveryFact[]): string {
+  const statuses = AGENT_TERMINAL_SUCCESS_STATUSES.join("/");
+  const head = feelStr(
+    `Node ${nodeId} (${descriptor}) completed but did not satisfy its producer contract — a producer must ` +
+      `self-report a terminal-success status (${statuses}) and populate every emit a downstream node requires ` +
+      "before its result routes onward. Reported status=",
+  );
+  let feel = `=${head} + (if (is defined(status) and status != null) then string(status) else "(none)") + "."`;
+  for (const f of requiredEmits) {
+    const present = `(is defined(${f.name}) and ${f.name} != null)`;
+    feel += ` + " Required emit '${f.name}': " + (if ${present} then "present" else "MISSING (null)") + "."`;
+  }
+  return feel;
+}
+
+/** `agent`/`connector` body: `start → serviceTask → end`, with a bounded `=nodeTimeout` boundary that
+ * escalates the stalled node onto a human-completable user task. `taskDefAttr` is the pre-rendered
+ * `type="…"` attribute; `taskProps` are optional `<zeebe:property>` envelope lines; `descriptor`
+ * names the stalled work (job type / connector target) for the escalation task's context line (#499).
+ *
+ * `contractGate` (agent only, issue #731) inserts a PRODUCER post-condition between the task and the
+ * end: an exclusive split whose SUCCESS flow ({@link agentContractProceedCondition}) proceeds only on a
+ * terminal-success `status` AND non-null required emits, and whose DEFAULT flow parks a broken producer
+ * on a SECOND (contract) escalation task — distinct from the `__esc` timeout twin. That escalation is
+ * RESUMABLE with the node's required emits (a human/agent supplies the missing fact, which the
+ * subProcess output mapping then publishes as `<el>_<fact>`), mirroring the #514 Defect-B wait resume.
+ * Omitted for a `connector` (no self-reported status contract), whose body stays `task → end`. */
 function serviceBodyLines(
   el: string,
   nodeId: string,
   taskDefAttr: string,
   taskProps: readonly string[],
   descriptor: string,
+  contractGate?: { requiredEmits: readonly DeliveryFact[] },
 ): string[] {
   const esc = escalationTaskElement(el);
   const taskExt =
@@ -1009,7 +1112,19 @@ function serviceBodyLines(
           `          <zeebe:taskDefinition ${taskDefAttr} />`,
           "        </bpmn:extensionElements>",
         ];
-  return [
+  const timeoutEscalation = escalationTaskLines(
+    esc,
+    nodeId,
+    [`${el}_i2`],
+    `${el}_i3`,
+    escalationContextFeel(
+      nodeId,
+      descriptor,
+      "nodeTimeout",
+      "; in-flight work may already exist — check for a draft PR or partial state before retrying or reassigning.",
+    ),
+  );
+  const head = [
     `      <bpmn:startEvent id="${el}_start"><bpmn:outgoing>${el}_i0</bpmn:outgoing></bpmn:startEvent>`,
     `      <bpmn:serviceTask id="${el}_task" name="${escapeXml(nodeId)}">`,
     ...taskExt,
@@ -1020,21 +1135,49 @@ function serviceBodyLines(
     `        <bpmn:outgoing>${el}_i2</bpmn:outgoing>`,
     `        <bpmn:timerEventDefinition id="${el}_ted"><bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=nodeTimeout</bpmn:timeDuration></bpmn:timerEventDefinition>`,
     "      </bpmn:boundaryEvent>",
-    ...escalationTaskLines(
-      esc,
-      nodeId,
-      [`${el}_i2`],
-      `${el}_i3`,
-      escalationContextFeel(
-        nodeId,
-        descriptor,
-        "nodeTimeout",
-        "; in-flight work may already exist — check for a draft PR or partial state before retrying or reassigning.",
-      ),
-    ),
-    `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i1</bpmn:incoming><bpmn:incoming>${el}_i3</bpmn:incoming></bpmn:endEvent>`,
+    ...timeoutEscalation,
+  ];
+
+  if (contractGate === undefined) {
+    return [
+      ...head,
+      `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i1</bpmn:incoming><bpmn:incoming>${el}_i3</bpmn:incoming></bpmn:endEvent>`,
+      flow(`${el}_i0`, `${el}_start`, `${el}_task`),
+      flow(`${el}_i1`, `${el}_task`, `${el}_end`),
+      flow(`${el}_i2`, `${el}_be`, esc),
+      flow(`${el}_i3`, esc, `${el}_end`),
+    ];
+  }
+
+  // Producer-contract gate (issue #731): task → gate → (proceed | contract-escalation) → end.
+  const contractEsc = contractEscalationTaskElement(el);
+  const emits = contractGate.requiredEmits;
+  const proceedCondition = agentContractProceedCondition(emits);
+  const contractEscalation = escalationTaskLines(
+    contractEsc,
+    nodeId,
+    [`${el}_g1`],
+    `${el}_g2`,
+    agentContractContextFeel(nodeId, descriptor, emits),
+    // Resumable when the producer owes a required emit: a human/agent supplies the missing fact, which
+    // the subProcess output ioMapping then publishes as `<el>_<fact>` (agent emit source = fact name),
+    // so the downstream consumer late-binds a real value instead of the null that poisoned it (#731).
+    emits.length > 0 ? { resume: { kind: "agent" as const, emits } } : undefined,
+  );
+  return [
+    ...head,
+    `      <bpmn:exclusiveGateway id="${el}_gate" name="producer contract met?" default="${el}_g1">`,
+    `        <bpmn:incoming>${el}_i1</bpmn:incoming>`,
+    `        <bpmn:outgoing>${el}_g0</bpmn:outgoing>`,
+    `        <bpmn:outgoing>${el}_g1</bpmn:outgoing>`,
+    "      </bpmn:exclusiveGateway>",
+    ...contractEscalation,
+    `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_g0</bpmn:incoming><bpmn:incoming>${el}_i3</bpmn:incoming><bpmn:incoming>${el}_g2</bpmn:incoming></bpmn:endEvent>`,
     flow(`${el}_i0`, `${el}_start`, `${el}_task`),
-    flow(`${el}_i1`, `${el}_task`, `${el}_end`),
+    flow(`${el}_i1`, `${el}_task`, `${el}_gate`),
+    `      <bpmn:sequenceFlow id="${el}_g0" name="contract met" sourceRef="${el}_gate" targetRef="${el}_end"><bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">${proceedCondition}</bpmn:conditionExpression></bpmn:sequenceFlow>`,
+    `      <bpmn:sequenceFlow id="${el}_g1" name="contract broken" sourceRef="${el}_gate" targetRef="${contractEsc}" />`,
+    flow(`${el}_g2`, contractEsc, `${el}_end`),
     flow(`${el}_i2`, `${el}_be`, esc),
     flow(`${el}_i3`, esc, `${el}_end`),
   ];

package/e2e/agent-answerable.e2e.ts

@@ -26,7 +26,6 @@ import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
-import { asEngineClient } from "./support/engine-client.ts";
 import {
   completeEscalationAsAgent,
   latestCompletion,
@@ -142,7 +141,7 @@ describe("agent-answerable escalations (U6 — same form, agent completer, attri
 
         // Complete AS AN AGENT through the host-side completer — the same typed `{resolution, answer}`
         // a human submits through the inbox, only the caller differs.
-        const r = await completeEscalationAsAgent(app.db, asEngineClient(app.engine), {
+        const r = await completeEscalationAsAgent(app.db, app.engine, {
           userTaskKey: task.userTaskKey,
           agentId: "senior:answer-bot",
           variables: { resolution: "answer", answer: "use v2" },

package/e2e/convergence-escalation.e2e.ts

@@ -29,7 +29,6 @@ import { after, before, describe, test } from "node:test";
 import { fileURLToPath } from "node:url";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { pollUserTasks } from "../app/service.ts";
-import { asEngineClient } from "./support/engine-client.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const DB_DIR = mkdtempSync(join(tmpdir(), "nwf-u4-"));
@@ -159,7 +158,7 @@ describe("nano-workforce PR review-loop escalation (U4 userTask)", () => {
     // denormalised `open_escalation_*` pointer is written or read. That read model is projected by
     // `pollUserTasks` (part of the imperative main.ts poll loop the testkit does not run), so drive it
     // explicitly (mirrors feature-run.e2e.ts) to project the parked `wait-answer` task first.
-    await pollUserTasks(app.db, asEngineClient(app.engine));
+    await pollUserTasks(app.db, app.engine);
     const status = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
     assert.equal(status.status, 200, "the status endpoint responds");
     const statusRow = status.body.prs.find((p) => p.prKey === prKey);
@@ -198,7 +197,7 @@ describe("nano-workforce PR review-loop escalation (U4 userTask)", () => {
     // reconciles away, so no open escalation lingers on the status endpoint once answered + resumed.
     // Re-run the projection (as the durable poller would) so the closed task's read-model row is
     // deleted before re-reading /status.
-    await pollUserTasks(app.db, asEngineClient(app.engine));
+    await pollUserTasks(app.db, app.engine);
     const afterStatus = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
     const afterRow = afterStatus.body.prs.find((p) => p.prKey === prKey);
     if (afterRow) {

package/e2e/delivery-graph.e2e.ts

@@ -185,6 +185,67 @@ describe("delivery-graph runner — engine-native execution (S4)", () => {
     assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the late-bound wait resolved and the graph reached End");
   });
 
+  test("#731 producer contract gate: an agent that completes with status=in_progress and a null required emit escalates AT the producer, does NOT thread null downstream, and resumes", async () => {
+    const app = track(await boot(freshDir()));
+
+    // The instance-10746 failure mode: the agent's job COMPLETES, but it broke its node contract —
+    // it self-reports `status: "in_progress"` and never opened the PR, so its required `pr` emit is
+    // null. Before #731 this threaded `open_pr = null` through to the connector, which then failed with
+    // a mis-attributed CONSUMER incident. The producer gate must instead park THIS node.
+    let agentFired = 0;
+    await app.engine.registerWorker("senior:demo", async () => {
+      agentFired++;
+      return { status: "in_progress", summary: "delegated to a background agent; PR not opened." };
+    });
+    let connectorFired = 0;
+    await app.engine.registerWorker(
+      "pr.delivery-connector",
+      async (job) => {
+        connectorFired++;
+        const vars = job.variables as Record<string, unknown>;
+        const { target, payload, boundFacts } = readConnectorInput(vars as Parameters<typeof readConnectorInput>[0]);
+        const dedupeKey = connectorDedupeKey({
+          dedupeKey: (vars.dedupeKey as string | null | undefined) ?? null,
+          processInstanceKey: job.processInstanceKey ?? null,
+          elementId: job.elementId ?? null,
+        });
+        return await dispatchConnector(app.db, { dedupeKey: dedupeKey ?? "x", target, payload, boundFacts }, new Date().toISOString());
+      },
+      { fetchVariables: ["boundFacts", "target", "dedupeKey", "payload"] },
+    );
+
+    const graph: DeliveryGraph = {
+      name: "e2e producer gate",
+      nodes: [
+        { id: "open", kind: "agent", agent: { jobType: "senior:demo" }, emits: [{ name: "pr", type: "pr" }] },
+        { id: "land", kind: "connector", connector: { target: "slack", payload: { pr: "open.pr" }, dedupeKey: "land-731" } },
+      ],
+      edges: [{ from: "open.pr", to: "land" }],
+    };
+
+    const run = await runDeliveryGraph(app.engine, graph, { escalationSlaTimeout: "PT1H", repoless: true });
+    assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
+    await app.settle();
+
+    // The agent job fired and COMPLETED — but the node did NOT succeed: it parked on its producer
+    // contract escalation, the graph never reached End, and the downstream connector never fired on null.
+    assert.equal(agentFired, 1, "the agent node's job fired and completed");
+    assert.ok(!takenFlows(app).some((f) => f.endsWith("->End")), "the broken producer did NOT thread its result to End");
+    assert.equal(connectorFired, 0, "the downstream connector never fired on a null required emit");
+    const open = await app.engine.searchUserTasks({ state: "CREATED" });
+    const contract = open.find((t) => t.elementId?.startsWith("delivery-human-task__") && t.elementId?.endsWith("__contract"));
+    assert.ok(contract, `the producer escalates AT its node on its __contract task, got ${JSON.stringify(open.map((t) => t.elementId))}`);
+
+    // Resumable (the issue's manual unblock): a human/agent supplies the eventually-created PR on the
+    // contract task; the subProcess output mapping republishes `open_pr` non-null and the connector runs.
+    await app.engine.completeUserTask(contract.userTaskKey, { value: "owner/repo#42", humanOutcome: "completed" });
+    await app.settle();
+    assert.equal(connectorFired, 1, "resuming the contract escalation with the missing PR unblocks the downstream connector");
+    const rows = await deliveryConnectorDispatches(app.db).find({ dedupe_key: "land-731" });
+    assert.equal(rows.length, 1, "the connector fired exactly once after resume");
+    assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the resumed producer's result reaches End");
+  });
+
   test("resume never double-fires: an at-least-once redelivery of the connector dedupes", async () => {
     const app = track(await boot(freshDir()));
     // The connector fired once above's-style; here prove the idempotency directly against the ledger a

package/e2e/feature-run.e2e.ts

@@ -23,7 +23,6 @@ import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
-import { asEngineClient } from "./support/engine-client.ts";
 import { pollUserTasks } from "../app/service.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -208,7 +207,7 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
         // read-model (issue #332 dropped the denormalised `feature_runs.blocked_user_task_key` pointer),
         // so `pollUserTasks` projects the parked `feature-blocked` task onto `user_tasks` by reading the
         // engine directly — no per-run column write.
-        await pollUserTasks(app.db, asEngineClient(app.engine));
+        await pollUserTasks(app.db, app.engine);
         const inboxRow = await app.db
           .table<{ user_task_key: string; element_id: string }>("user_tasks", "user_task_key")
           .findOne({ user_task_key: task!.userTaskKey });
@@ -233,7 +232,7 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
 
         // A further poll pass is an idempotent no-op — the task is completed, so the read-model row is
         // reconciled away and a terminal run is not a candidate.
-        await pollUserTasks(app.db, asEngineClient(app.engine));
+        await pollUserTasks(app.db, app.engine);
         assert.equal((await featureRow(app, featureKey)).status, "blocked");
       },
     );
@@ -385,7 +384,7 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
 
         // The poller projects the parked task onto the Tasks inbox `user_tasks` read-model by reading
         // the engine directly, sourcing the question from the `feature_escalations` audit log.
-        await pollUserTasks(app.db, asEngineClient(app.engine));
+        await pollUserTasks(app.db, app.engine);
         const inboxRow = await app.db
           .table<{ user_task_key: string; element_id: string; question: string | null }>("user_tasks", "user_task_key")
           .findOne({ user_task_key: task!.userTaskKey });
@@ -414,7 +413,7 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
         assert.equal(settled.status, "opened", "the resumed run opened its PR");
 
         // A further poll pass reconciles the completed task's read-model row away.
-        await pollUserTasks(app.db, asEngineClient(app.engine));
+        await pollUserTasks(app.db, app.engine);
         const gone = await app.db
           .table<{ user_task_key: string }>("user_tasks", "user_task_key")
           .findOne({ user_task_key: task!.userTaskKey });

package/e2e/retire-escalation-subsystem.e2e.ts

@@ -26,7 +26,6 @@ import { after, before, describe, test } from "node:test";
 import { fileURLToPath } from "node:url";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { pollUserTasks } from "../app/service.ts";
-import { asEngineClient } from "./support/engine-client.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const DB_DIR = mkdtempSync(join(tmpdir(), "nwf-u7-"));
@@ -237,7 +236,7 @@ describe("retire escalation subsystem (U7 — destructive contract phase)", () =
     // written. That read model is projected by `pollUserTasks` (part of the imperative main.ts poll
     // loop the testkit does not run), so drive it explicitly (mirrors feature-run.e2e.ts) to project
     // the parked `wait-answer` task before reading /status.
-    await pollUserTasks(app.db, asEngineClient(app.engine));
+    await pollUserTasks(app.db, app.engine);
     const status = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
     const statusRow = status.body.prs.find((p) => p.prKey === prKey);
     assert.equal(statusRow?.status, "escalated", "the PR reads as escalated");
@@ -265,7 +264,7 @@ describe("retire escalation subsystem (U7 — destructive contract phase)", () =
     // No addressed escalation lingers — the completed task's `user_tasks` row reconciles away. Re-run
     // the projection (as the durable poller would) so the closed task's read-model row is deleted
     // before re-reading /status.
-    await pollUserTasks(app.db, asEngineClient(app.engine));
+    await pollUserTasks(app.db, app.engine);
     const afterStatus = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
     const afterRow = afterStatus.body.prs.find((p) => p.prKey === prKey);
     if (afterRow) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.179.1",
+  "version": "0.180.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/e2e/support/engine-client.ts

@@ -1,33 +0,0 @@
-import type { EngineClient } from "@nanobpm/urban";
-import type { TestApp } from "@nanobpm/urban-testkit";
-
-// `@nanobpm/urban-testkit`'s `WasmEngineClient` has historically lagged urban's `EngineClient`
-// interface: a method lands on the real seam a release or two before the testkit fake grows it. Both
-// guards below defensively COMPLETE the contract for any method the *installed* testkit hasn't
-// implemented yet — each is an idempotent `if (typeof … !== "function")`, so it no-ops the moment a
-// testkit release ships the real method (no version pins to drift). Scoped to the test harness;
-// production adapters (`SdkEngineClient`) implement both for real.
-//
-//  - `getForm` (urban 0.49.0, ADR 0062): the original instance of this lag. Now implemented by the
-//    currently pinned testkit, so this guard is a no-op there; kept as defence against version skew.
-//    These hermetic flows drive completion directly and never resolve a form schema, so the fallback
-//    returns `null` — the documented "no matching form" path.
-//  - `openUserTasks` (issue #294 moved the pollers onto it): the CURRENT gap — the pinned testkit has
-//    `searchUserTasks` but not the open-task-scoped `openUserTasks`, so a poller call throws
-//    `not a function` (swallowed by the poller's try/catch) and the read-model denormalisation
-//    silently no-ops. Polyfill it as `searchUserTasks({ state: "CREATED" })` — byte-for-byte what
-//    urban's real `SdkEngineClient.openUserTasks` does, so the two cannot drift. Fix: nano-workforce
-//    #309; categorical (testkit) fix upstream in nanobpm/nano-ide#341.
-export function asEngineClient(engine: TestApp["engine"]): EngineClient {
-  const e = engine as unknown as EngineClient & {
-    getForm?: EngineClient["getForm"];
-    openUserTasks?: EngineClient["openUserTasks"];
-  };
-  if (typeof e.getForm !== "function") {
-    e.getForm = async () => null;
-  }
-  if (typeof e.openUserTasks !== "function") {
-    e.openUserTasks = (filter) => e.searchUserTasks({ ...filter, state: "CREATED" });
-  }
-  return e;
-}