@nanobpm/nano-workforce 0.179.2 → 0.181.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.181.0](https://github.com/nanobpm/nano-workforce/compare/v0.180.0...v0.181.0) (2026-09-04)
+
+### Features
+
+* delivery-graph MCP DX — interleaved sequence gates, paginated guide sections, stage-supersede visibility ([#741](https://github.com/nanobpm/nano-workforce/issues/741)) ([6f10e8a](https://github.com/nanobpm/nano-workforce/commit/6f10e8a25721645af4e5f932f2cbaa9ad6025b70)), closes [#740](https://github.com/nanobpm/nano-workforce/issues/740) [#460](https://github.com/nanobpm/nano-workforce/issues/460) [#740](https://github.com/nanobpm/nano-workforce/issues/740)
+
+## [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

package/app/agentGuide.test.ts

@@ -10,9 +10,11 @@ import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import {
   GUIDE_SECTIONS,
+  GUIDE_SECTION_PAGE_DEFAULT,
   guideToc,
   renderAgentGuide,
   renderGuideSection,
+  renderGuideSectionChunk,
   splitGuideSections,
 } from "./agentGuide.ts";
 
@@ -105,6 +107,91 @@ test("an unknown section id resolves to undefined (the op turns that into a 400)
   assertEquals(renderGuideSection("does-not-exist", "https://x/app/api"), undefined);
 });
 
+// ── Paginated section retrieval (issue #740) ────────────────────────────────────────────────────
+
+test("renderGuideSectionChunk: paging through a section reassembles it exactly, chunk by chunk", () => {
+  const base = "https://x/app/api";
+  const full = renderGuideSection("delivery-graphs", base)!;
+  const totalChars = Array.from(full).length;
+  const PAGE = 4000;
+  let start = 0;
+  let assembled = "";
+  let pages = 0;
+  let lastTotal = -1;
+  // Follow the nextStart cursor until it is null — the classic pagination loop.
+  for (;;) {
+    const chunk = renderGuideSectionChunk("delivery-graphs", base, start, PAGE)!;
+    assert(chunk, "a known section must page");
+    assert(Array.from(chunk.instructions).length <= PAGE, "a page must be bounded by the window");
+    assertEquals(chunk.start, start);
+    assertEquals(chunk.totalLength, totalChars);
+    if (lastTotal !== -1) assertEquals(chunk.totalLength, lastTotal);
+    lastTotal = chunk.totalLength;
+    assembled += chunk.instructions;
+    pages++;
+    if (chunk.nextStart === null) break;
+    start = chunk.nextStart;
+    assert(pages < 100, "pagination must terminate");
+  }
+  assert(pages > 1, "a large section must span multiple pages at this window");
+  assertEquals(assembled, full, "the reassembled pages must equal the whole section");
+});
+
+test("renderGuideSectionChunk: a window past the end returns an empty last page with nextStart null", () => {
+  const base = "https://x/app/api";
+  const full = renderGuideSection("orient", base)!;
+  const total = Array.from(full).length;
+  const chunk = renderGuideSectionChunk("orient", base, total + 500, 100)!;
+  assertEquals(chunk.start, total);
+  assertEquals(chunk.length, 0);
+  assertEquals(chunk.instructions, "");
+  assertEquals(chunk.nextStart, null);
+});
+
+test("renderGuideSectionChunk: the first page of a fitting section equals the whole section (nextStart null)", () => {
+  const base = "https://x/app/api";
+  const full = renderGuideSection("orient", base)!;
+  const chunk = renderGuideSectionChunk("orient", base, 0, GUIDE_SECTION_PAGE_DEFAULT)!;
+  // `orient` fits well under the default page, so one page carries it whole with no continuation.
+  assertEquals(chunk.instructions, full);
+  assertEquals(chunk.nextStart, null);
+});
+
+test("renderGuideSectionChunk: a zero-length window on a non-empty section terminates (nextStart null, no loop)", () => {
+  const base = "https://x/app/api";
+  const full = renderGuideSection("delivery-graphs", base)!;
+  assert(Array.from(full).length > 0, "precondition: the section has content");
+  // A caller (or a direct invoker bypassing the op's `length >= 1` validation) that asks for a
+  // zero-length window gets an empty page — but `nextStart` MUST be null so a "page until nextStart
+  // is null" loop cannot spin forever on a cursor that never advances.
+  const chunk = renderGuideSectionChunk("delivery-graphs", base, 0, 0)!;
+  assertEquals(chunk.start, 0);
+  assertEquals(chunk.length, 0);
+  assertEquals(chunk.instructions, "");
+  assertEquals(chunk.nextStart, null);
+});
+
+test("renderGuideSectionChunk: an unknown section id is undefined (the op turns that into a 400)", () => {
+  assertEquals(renderGuideSectionChunk("does-not-exist", "https://x/app/api", 0, 100), undefined);
+});
+
+test("renderGuideSectionChunk: chunk boundaries never split a multi-byte character", () => {
+  const base = "https://x/app/api";
+  const full = renderGuideSection("delivery-graphs", base)!;
+  // Page at every 1-char window across a stretch that contains the guide's arrows/emoji; each
+  // reassembled result must round-trip losslessly (no U+FFFD replacement from a split code point).
+  let assembled = "";
+  let start = 0;
+  for (let i = 0; i < 200 && start < Array.from(full).length; i++) {
+    const chunk = renderGuideSectionChunk("delivery-graphs", base, start, 7)!;
+    assembled += chunk.instructions;
+    if (chunk.nextStart === null) break;
+    start = chunk.nextStart;
+  }
+  assert(!assembled.includes("\uFFFD"), "no replacement characters — code points were never split");
+  assertEquals(assembled, Array.from(full).slice(0, Array.from(assembled).length).join(""));
+});
+
 test("no content regression: each section body is a verbatim slice of the raw guide", () => {
   // Rendering keys examples to an instance; the UN-substituted section bodies must be exact
   // substrings of the authored doc, so the addressable surface never rewrites guide content.

package/app/agentGuide.ts

@@ -174,3 +174,64 @@ export function renderGuideSection(id: string, apiBase: string): string | undefi
   const base = apiBase.replace(/\/+$/, "");
   return section.body.replaceAll("__BASE__", base).replaceAll("__ENGINE__", resolveEngineBase());
 }
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// Paginated section retrieval (issue #740).
+//
+// The addressable guide exists to avoid the ~43KB monolith, but a single section can ITSELF overflow
+// a typical MCP tool-result limit — `delivery-graphs` alone renders to ~25KB, the one section an
+// author most needs. So a section is additionally retrievable in BOUNDED CHUNKS via a `start`/`length`
+// window with a `nextStart` continuation cursor. Offsets are UNICODE CHARACTER (code-point) offsets —
+// NOT raw byte offsets — so a chunk boundary never splits a multi-byte character (the arrows/emoji in
+// the guide) into mojibake. A plain `renderGuideSection` (no window) is untouched, so existing
+// `section=<id>` calls that already fit stay byte-for-byte identical.
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/** The default window size (characters) when a caller engages pagination without an explicit
+ *  `length` — comfortably under a typical MCP tool-result limit so a single page never overflows. */
+export const GUIDE_SECTION_PAGE_DEFAULT = 12_000;
+
+/** One page of a section's markdown: the `instructions` slice plus the cursor state so a caller can
+ *  page through with `nextStart` until it is `null`. Offsets/lengths are CHARACTER counts. */
+export interface GuideSectionChunk {
+  readonly instructions: string;
+  /** The (clamped) character offset this page starts at. */
+  readonly start: number;
+  /** The number of characters actually returned in this page. */
+  readonly length: number;
+  /** The total number of characters in the fully-rendered section. */
+  readonly totalLength: number;
+  /** The character offset to pass as `start` for the next page, or `null` when this is the last page. */
+  readonly nextStart: number | null;
+}
+
+/** Render a bounded WINDOW of a single section's markdown for a given app control-API base, with
+ *  `__BASE__`/`__ENGINE__` substituted exactly as {@link renderGuideSection} does. `start` and
+ *  `length` are CHARACTER offsets (clamped to the section bounds; a non-positive `length` yields an
+ *  empty page). Returns `undefined` for an unknown id (the caller turns that into a 400). */
+export function renderGuideSectionChunk(
+  id: string,
+  apiBase: string,
+  start: number,
+  length: number,
+): GuideSectionChunk | undefined {
+  const full = renderGuideSection(id, apiBase);
+  if (full === undefined) return undefined;
+  const chars = Array.from(full);
+  const total = chars.length;
+  const from = Math.min(Math.max(0, Math.trunc(start)), total);
+  const take = Math.max(0, Math.trunc(length));
+  const slice = chars.slice(from, from + take);
+  const end = from + slice.length;
+  return {
+    instructions: slice.join(""),
+    start: from,
+    length: slice.length,
+    totalLength: total,
+    // Only advance when this page actually consumed characters. A zero-length window (`length <= 0`)
+    // returns an empty page that made NO progress, so it must terminate the cursor (`null`) rather
+    // than hand back a `nextStart` equal to `start` — a non-advancing cursor would loop a caller
+    // that pages until `nextStart` is null forever.
+    nextStart: slice.length > 0 && end < total ? end : null,
+  };
+}

package/app/deliveryGraph.ts

@@ -164,7 +164,7 @@ const GRAPH_NAME_MAX_LENGTH = 255;
  * like the library import/save doors' `graphJson`, where the schema never touches the parsed value)
  * would otherwise let an oversized-but-compilable graph reach the layout/compiler and be persisted —
  * both violating the declared contract and exposing the import path to avoidable CPU/memory growth. */
-const GRAPH_MAX_NODES = 256;
+export const GRAPH_MAX_NODES = 256;
 const GRAPH_MAX_EDGES = 1024;
 const NODE_MAX_EMITS = 32;
 

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`),
   ];