@nanobpm/nano-workforce 0.142.0 → 0.143.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.143.0](https://github.com/nanobpm/nano-workforce/compare/v0.142.0...v0.143.0) (2026-08-25)
+
+### Features
+
+* **delivery-graph:** idempotency preflight on agent nodes ([#551](https://github.com/nanobpm/nano-workforce/issues/551)) ([#552](https://github.com/nanobpm/nano-workforce/issues/552)) ([f16fa6d](https://github.com/nanobpm/nano-workforce/commit/f16fa6d32336fdd025b810ba763403b352986937)), closes [979/#980](https://github.com/979/nano-workforce/issues/980) [#506](https://github.com/nanobpm/nano-workforce/issues/506)
+
 ## [0.142.0](https://github.com/nanobpm/nano-workforce/compare/v0.141.0...v0.142.0) (2026-08-25)
 
 ### Features

package/app/deliveryRunner.test.ts

@@ -11,7 +11,7 @@
 // proven end-to-end in `e2e/delivery-graph.e2e.ts`.
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
-import { prepareDeliveryGraph, runDeliveryGraph } from "./deliveryRunner.ts";
+import { prepareDeliveryGraph, renderIdempotencyPreamble, runDeliveryGraph } from "./deliveryRunner.ts";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
 
 const GRAPH: DeliveryGraph = {
@@ -70,7 +70,9 @@ test("nodeInputs seeds the exact per-kind fields each node's subProcess ioMappin
   const byField = (pred: (v: Record<string, unknown>) => boolean) => Object.values(inputs).find((v) => pred(v as Record<string, unknown>)) as Record<string, unknown> | undefined;
 
   const agent = byField((v) => v.jobType === "senior:feature");
-  assertEquals(agent, { jobType: "senior:feature", appendPrompt: "un-draft + merge #B", timeout: "PT10M" });
+  // Every agent node's appendPrompt is prefixed with the idempotency preflight (#551), then the
+  // authored prompt (this node declares no emits, so the emit contract adds nothing).
+  assertEquals(agent, { jobType: "senior:feature", appendPrompt: renderIdempotencyPreamble() + "un-draft + merge #B", timeout: "PT10M" });
 
   const wait = byField((v) => "gateKey" in v);
   assertEquals(wait?.gateKey, "run-7:n3");
@@ -135,20 +137,60 @@ test("agent node classifier-emit contract (#506): a declared `emits` threads the
   };
   const p = await prepareOk(graph);
   const agents = Object.values(p.nodeInputs).filter((v) => "jobType" in v) as Array<Record<string, unknown>>;
-  const adopt = agents.find((v) => String(v.appendPrompt).startsWith("adopt the package"));
-  const plain = agents.find((v) => String(v.appendPrompt).startsWith("just implement it"));
+  const adopt = agents.find((v) => String(v.appendPrompt).includes("adopt the package"));
+  const plain = agents.find((v) => String(v.appendPrompt).includes("just implement it"));
 
-  // The emit-declaring node keeps its authored prompt AND gains the emit contract naming its fact.
+  // The emit-declaring node keeps its authored prompt AND gains the emit contract naming its fact,
+  // both AFTER the unconditional idempotency preflight (#551).
   assert(adopt, "the emit-declaring agent node must be seeded");
   const adoptPrompt = String(adopt?.appendPrompt);
-  assert(adoptPrompt.startsWith("adopt the package"), "the authored prompt is preserved as the prefix");
+  assert(adoptPrompt.startsWith(renderIdempotencyPreamble()), "the idempotency preflight leads every agent prompt");
+  assert(adoptPrompt.includes("adopt the package"), "the authored prompt is preserved after the preflight");
   assert(adoptPrompt.includes("Classifier emit contract"), `the emit contract must be threaded in, got: ${adoptPrompt}`);
   assert(adoptPrompt.includes("`result`") && adoptPrompt.includes("(string)"), "the declared fact name + type must be surfaced to the agent");
   assert(adoptPrompt.includes("breaking | compatible"), "the fact's optional description rides the contract");
   assert(adoptPrompt.includes("AGENT_RESULT_FILE"), "the contract names the completion channel the fact rides");
 
-  // A node that declares NO facts is untouched — appendPrompt is exactly the authored prompt.
-  assertEquals(plain?.appendPrompt, "just implement it");
+  // A node that declares NO facts still carries the preflight, then exactly the authored prompt — the
+  // emit contract contributes nothing.
+  assertEquals(plain?.appendPrompt, renderIdempotencyPreamble() + "just implement it");
+});
+
+
+test("agent node idempotency preflight (#551): every agent prompt leads with adopt-and-report guidance; non-agent nodes are untouched", async () => {
+  // #551: a delivery agent node dispatches a raw retry-carrying `senior:feature` job with no
+  // PR-existence guard, so a re-dispatch opened a DUPLICATE PR (instance 43077 n0 → #979/#980). The
+  // fix threads an unconditional idempotency preflight into every agent node's `appendPrompt` telling
+  // the agent to CHECK for an existing claim/open PR and ADOPT-AND-REPORT it rather than open a second.
+  // Pin: (a) both agent nodes lead with the preflight regardless of emits, (b) it names the check +
+  // the adopt-and-report contract, and (c) wait/human/connector nodes never carry it.
+  const graph: DeliveryGraph = {
+    name: "idempotency",
+    nodes: [
+      { id: "emitter", kind: "agent", agent: { jobType: "senior:feature", prompt: "do X" }, emits: [{ name: "result", type: "string" }] },
+      { id: "plain", kind: "agent", agent: { jobType: "senior:feature", prompt: "do Y" } },
+      { id: "gate", kind: "wait", wait: { kind: "pr", target: "owner/repo#1", match: { prState: "merged" } } },
+    ],
+    edges: [{ from: "emitter", to: "plain" }, { from: "plain", to: "gate" }],
+  };
+  const p = await prepareOk(graph);
+  const preamble = renderIdempotencyPreamble();
+
+  // Every agent node leads with the preflight, ahead of its authored prompt (and any emit contract).
+  const agents = Object.values(p.nodeInputs).filter((v) => "jobType" in v) as Array<Record<string, unknown>>;
+  assertEquals(agents.length, 2, "both agent nodes are seeded");
+  for (const a of agents) {
+    const prompt = String(a.appendPrompt);
+    assert(prompt.startsWith(preamble), "the preflight is the leading prefix of every agent prompt");
+    assert(prompt.includes("Idempotency preflight"), "the preflight heading is present");
+    assert(prompt.includes("DO NOT open a second PR") || prompt.includes("do not open a second"), "it forbids a duplicate PR");
+    assert(prompt.includes("adopt and report"), "it names the adopt-and-report contract");
+  }
+
+  // The preflight is unconditional but AGENT-ONLY — a wait node's seed carries no prompt at all.
+  const wait = Object.values(p.nodeInputs).find((v) => "gateKey" in v) as Record<string, unknown> | undefined;
+  assert(wait, "the wait node is seeded");
+  assert(!("appendPrompt" in wait!), "a non-agent node never carries the agent idempotency preflight");
 });
 
 

package/app/deliveryRunner.ts

@@ -178,6 +178,48 @@ function rewriteProcessId(bpmn: string, processDefinitionId: string): string {
     .replace(`bpmnElement="${DELIVERY_GRAPH_PROCESS_ID}"`, `bpmnElement="${processDefinitionId}"`);
 }
 
+/** The idempotency preflight prepended to EVERY `agent` node's `appendPrompt` (issue #551). A delivery
+ * agent node dispatches a raw `senior:feature` job with no `feature_runs` idempotency row and no
+ * PR-existence guard, and the job carries retries — so an idle/timeout re-dispatch hands the SAME
+ * "implement #N" prompt to another worker, who (in a fresh worktree, blind to the first) opens a SECOND
+ * PR on the same issue. That is exactly how instance 43077's node n0 (`Magikcraft/nano-bpm#977`) spawned
+ * the #979/#980 duplicate. The advisory AGENTS.md claim protocol did not prevent it because nothing tells
+ * the *agent* to look first. This block does: a preflight that makes the agent **adopt-and-report** an
+ * existing PR instead of opening a duplicate. Adopt-and-report (not "escalate") because a delivery agent
+ * node has NO in-band escalate route — an in-flight agent can only complete (job done) or fail (which
+ * raises an incident, the stuck state we are avoiding); adopting completes the completion-barrier node
+ * cleanly, with no duplicate and no incident. Fixed wording (no derived data), so identical graphs still
+ * compile+seed deterministically; it is unconditional because every agent node that opens a PR is exposed
+ * to the same re-dispatch race. This is an advisory guard — the categorical fix (an engine-level
+ * preflight guard, or routing the node through the idempotent feature cell) is tracked as a follow-up. */
+export function renderIdempotencyPreamble(): string {
+  return [
+    "## Idempotency preflight (delivery graph) — check BEFORE you implement",
+    "",
+    "This node may be re-dispatched (a retry after a timeout) or run in parallel with another worker.",
+    "BEFORE you write ANY code, confirm nobody is already delivering the issue you were asked to implement:",
+    "",
+    "1. Read that issue's comments for an existing **claim** (a comment beginning `Claimed —`, an",
+    "   assignee, or a referenced in-progress branch/worktree).",
+    "2. List the repository's OPEN pull requests for one that already references the issue (a `Closes",
+    "   #N`, the issue number in its title/body, or a branch named for it).",
+    "",
+    "If an existing claim OR an open PR already covers this issue, DO NOT open a second PR — a duplicate",
+    "PR is a defect: it splits review and collides in the same files. Instead **adopt and report**:",
+    "complete WITHOUT making any changes and return the EXISTING PR as your result — put it in your `pr`",
+    "field (a URL or `owner/repo#N`) and complete with your normal success status, with a `summary` that",
+    "names the PR you adopted. This satisfies the node cleanly; a downstream door (or a human) drives the",
+    "existing PR the rest of the way.",
+    "",
+    "Only implement — and open your own PR — when NO claim and NO open PR exist for the issue.",
+    "",
+    "---",
+    "",
+    "",
+  ].join("\n");
+}
+
+
 /** Render the classifier-emit contract appended to an `agent` node's `appendPrompt` (issue #506) — the
  * instruction that turns a declared `emits[]` into completion variables a downstream guarded split (S7)
  * can route on. A `senior:*` fleet agent completes with the Output-contract envelope (`status`,
@@ -231,7 +273,7 @@ function buildNodeInput(
       // truth. A no-emit node appends nothing, so a plain implementation node is unchanged.
       const basePrompt = node.agent.prompt ?? "";
       const emits = Array.isArray(node.emits) ? node.emits.map((f) => ({ ...f })) : [];
-      return { jobType: node.agent.jobType, appendPrompt: basePrompt + renderEmitContract(emits), timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
+      return { jobType: node.agent.jobType, appendPrompt: renderIdempotencyPreamble() + basePrompt + renderEmitContract(emits), timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
     }
     case "wait": {
       const probe = parseProbe(node.wait);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.142.0",
+  "version": "0.143.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",