@nanobpm/nano-workforce 0.140.0 → 0.142.0

package/app/deliveryGraph.test.ts

@@ -731,3 +731,114 @@ test("a wait node's onTimeout: fail is rejected (unsupported-on-timeout) while c
   assertEquals(validateDeliveryGraph(waitWith("continue")), []);
   assertEquals(validateDeliveryGraph(waitWith("escalate")), []);
 });
+
+// ── Pass 4 (#548): converge/wait PR late-binding ──────────────────────────────────────────────────
+
+/** The canonical no-literal converge shape: `open` emits a `pr` fact, both the converge connector and
+ * the pr-wait reference it (`open.pr`) on incoming fact edges. */
+function noLiteralConverge(overrides?: {
+  connectorPr?: unknown;
+  waitTarget?: string;
+  openEmitsPr?: boolean;
+  edges?: { from: string; to: string }[];
+}) {
+  const emits = overrides?.openEmitsPr === false ? [{ name: "pr", type: "url" }] : [{ name: "pr", type: "pr" }];
+  const connector =
+    "connectorPr" in (overrides ?? {})
+      ? { target: "converge-merge", payload: { pr: overrides?.connectorPr } }
+      : { target: "converge-merge", payload: { pr: "open.pr" } };
+  return {
+    name: "no-literal converge",
+    nodes: [
+      { id: "open", kind: "agent", agent: { jobType: "senior:feature", prompt: "open a PR" }, emits },
+      { id: "land", kind: "connector", connector },
+      { id: "merged", kind: "wait", wait: { kind: "pr", target: overrides?.waitTarget ?? "open.pr", match: { prState: "merged" } } },
+    ],
+    edges: overrides?.edges ?? [
+      { from: "open.pr", to: "land" },
+      { from: "open.pr", to: "merged" },
+    ],
+  };
+}
+
+test("#548 a converge connector + pr-wait that reference a threaded `pr` fact validate", () => {
+  assertEquals(validateDeliveryGraph(noLiteralConverge()), []);
+});
+
+test("#548 a LITERAL owner/repo#N PR on both the connector and the wait validates (no binding needed)", () => {
+  const g = noLiteralConverge({ connectorPr: "acme/repo#12", waitTarget: "acme/repo#12", edges: [{ from: "open", to: "land" }, { from: "land", to: "merged" }] });
+  assertEquals(validateDeliveryGraph(g), []);
+});
+
+test("#548 a PR reference that is NOT threaded by a fact edge is rejected (unbound-pr)", () => {
+  // The connector/wait name `open.pr`, but the edges carry only a plain completion dependency — the
+  // `pr` fact never flows in, so it can never late-bind.
+  const g = noLiteralConverge({ edges: [{ from: "open", to: "land" }, { from: "land", to: "merged" }] });
+  const errs = validateDeliveryGraph(g);
+  const unbound = errs.filter((e) => e.code === "unbound-pr");
+  assertEquals(unbound.length, 2, `both consumers are unbound: ${JSON.stringify(errs)}`);
+  assert(unbound.some((e) => e.path === "nodes[1].connector.payload.pr"));
+  assert(unbound.some((e) => e.path === "nodes[2].wait.target"));
+});
+
+test("#548 a PR reference to a non-`pr`-typed fact is rejected (unbound-pr)", () => {
+  const g = noLiteralConverge({ openEmitsPr: false }); // `open` emits `pr` as a `url`, not `pr`
+  const err = hasCode(validateDeliveryGraph(g), "unbound-pr");
+  assert(err.message.includes("must reference a `pr`-typed fact") || err.message.includes('"url"'), err.message);
+});
+
+test("#548 a PR reference to an undeclared fact is rejected (unbound-pr)", () => {
+  // `open` emits no facts, but the connector references `open.pr`.
+  const g = {
+    name: "undeclared ref",
+    nodes: [
+      { id: "open", kind: "agent", agent: { jobType: "j", prompt: "p" } },
+      { id: "land", kind: "connector", connector: { target: "converge", payload: { pr: "open.pr" } } },
+    ],
+    edges: [{ from: "open", to: "land" }],
+  };
+  const err = hasCode(validateDeliveryGraph(g), "unbound-pr");
+  assert(err.message.includes("does not declare"), err.message);
+});
+
+test("#548 a converge connector that OMITS payload.pr auto-binds a single threaded `pr` fact", () => {
+  const g = {
+    name: "omitted auto-bind",
+    nodes: [
+      { id: "open", kind: "agent", agent: { jobType: "senior:feature", prompt: "open" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "land", kind: "connector", connector: { target: "converge-merge" } },
+    ],
+    edges: [{ from: "open.pr", to: "land" }],
+  };
+  assertEquals(validateDeliveryGraph(g), []);
+});
+
+test("#548 a converge connector with NO PR at all is rejected (unbound-pr)", () => {
+  const g = {
+    name: "no pr",
+    nodes: [
+      { id: "open", kind: "agent", agent: { jobType: "j", prompt: "p" } },
+      { id: "land", kind: "connector", connector: { target: "converge-merge" } },
+    ],
+    edges: [{ from: "open", to: "land" }],
+  };
+  const err = hasCode(validateDeliveryGraph(g), "unbound-pr");
+  assert(err.message.includes("has no target PR"), err.message);
+});
+
+test("#548 a converge connector with MULTIPLE incoming `pr` facts is rejected as ambiguous (unbound-pr)", () => {
+  const g = {
+    name: "ambiguous pr",
+    nodes: [
+      { id: "a", kind: "agent", agent: { jobType: "j", prompt: "p" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "b", kind: "agent", agent: { jobType: "j", prompt: "p" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "land", kind: "connector", connector: { target: "converge-merge" } },
+    ],
+    edges: [
+      { from: "a.pr", to: "land" },
+      { from: "b.pr", to: "land" },
+    ],
+  };
+  const err = hasCode(validateDeliveryGraph(g), "unbound-pr");
+  assert(err.message.includes("disambiguate"), err.message);
+});

package/app/deliveryGraph.ts

@@ -19,6 +19,8 @@
 // Every error carries a JSON-path-qualified `path` (`nodes[2].kind`, `edges[1].from`, …) so the
 // caller can point the author straight at the offending input.
 
+import { isConvergeTarget } from "./convergeTargets.ts";
+
 /** The CLOSED node-kind allowlist (ADR 0005 Decision 2) — the trust boundary. Extensible only by a
  * deliberate ADR/PR (add the openapi variant + a case here), never by a graph author. Kept as the
  * single source of truth for "which kinds are legal" so the validator and any future compiler agree. */
@@ -30,8 +32,11 @@ export type DeliveryNodeKind = (typeof DELIVERY_NODE_KINDS)[number];
 /** The CLOSED emitted-fact type allowlist (ADR 0005 Decision 3/4) — mirrors the `DeliveryFact.type`
  * enum in `openapi.yaml`. Kept as the single source of truth so the semantic validator rejects an
  * untyped/unknown fact type even when the OpenAPI shape validator is bypassed (a directly-invoked
- * delegate), since later compilation/execution steps rely on this allowlist. */
-export const DELIVERY_FACT_TYPES = ["string", "number", "boolean", "artifact", "version", "url"] as const;
+ * delegate), since later compilation/execution steps rely on this allowlist. `pr` (issue #548) is the
+ * PR-reference type an `agent` node emits for the PR it opened (`owner/repo#N`), so a downstream
+ * `connector[converge*]` / `wait[pr]` node LATE-BINDS its target PR from that fact instead of a
+ * hardcoded literal (the canonical `agent → connector[converge-merge] → wait[pr, merged]` shape). */
+export const DELIVERY_FACT_TYPES = ["string", "number", "boolean", "artifact", "version", "url", "pr"] as const;
 
 /** An emitted fact's declared `type`, narrowed to the closed allowlist. */
 export type DeliveryFactType = (typeof DELIVERY_FACT_TYPES)[number];
@@ -84,7 +89,8 @@ export type DeliveryGraphErrorCode =
   | "multiple-defaults"
   | "non-exhaustive-split"
   | "exclusive-merge-parity"
-  | "unsupported-on-timeout";
+  | "unsupported-on-timeout"
+  | "unbound-pr";
 
 /** A single semantic validation failure. `path` is a JSON-path-qualified pointer at the offending
  * input (`nodes[2].kind`, `edges[1].from`, `nodes[0].emits[1].name`), `message` is human-actionable,
@@ -280,6 +286,19 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
   // validation (pass 3) reads to enforce that a `when` references a SCALAR fact.
   const nodeFacts = new Map<string, Set<string>>();
   const nodeFactTypes = new Map<string, Map<string, DeliveryFactType>>();
+  // #548 PR late-binding: the converge-connector / pr-wait nodes whose target PR must resolve to a
+  // literal `owner/repo#N` OR a threaded upstream `pr` fact. Collected in pass 1, validated in pass 4
+  // once the incoming fact edges are known — so an author who references a `pr` fact that isn't
+  // actually threaded (or isn't `pr`-typed) is rejected at COMPILE, not left to fail closed at runtime.
+  const prBindConsumers: {
+    path: string;
+    field: "connector.payload.pr" | "wait.target";
+    id: string;
+    // The authored PR ref: the connector's `payload.pr` or the wait's `target`. `undefined` when
+    // absent (a connector may omit it and auto-bind the single incoming `pr` fact; a wait's `target`
+    // is a required field reported missing elsewhere).
+    authored: string | undefined;
+  }[] = [];
   nodes.forEach((rawNode, i) => {
     const path = `nodes[${i}]`;
     if (!isRecord(rawNode)) {
@@ -358,6 +377,26 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
             code: "unsupported-on-timeout",
           });
         }
+        // #548: register a converge-connector / pr-wait as a PR-binding consumer (pass 4 validates the
+        // binding once edges are resolved). Only when the id is usable so pass 4 can key by node id.
+        if (typeof id === "string" && id.length > 0) {
+          if (kind === "connector" && typeof config.target === "string" && isConvergeTarget(config.target)) {
+            const payload = isRecord(config.payload) ? config.payload : undefined;
+            prBindConsumers.push({
+              path,
+              field: "connector.payload.pr",
+              id,
+              authored: payload !== undefined && typeof payload.pr === "string" ? payload.pr : undefined,
+            });
+          } else if (kind === "wait" && config.kind === "pr") {
+            prBindConsumers.push({
+              path,
+              field: "wait.target",
+              id,
+              authored: typeof config.target === "string" ? config.target : undefined,
+            });
+          }
+        }
       }
     } else if (rawNode.human !== undefined && !isRecord(rawNode.human)) {
       // `human` config is OPTIONAL (formKey/prompt both resolve to a generic fallback in S3), but
@@ -472,6 +511,9 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
   }
   // consumer (`to`) → set of upstream node ids (`from`'s node) — the dependency direction.
   const adjacency = new Map<string, Set<string>>();
+  // #548: consumer (`to`) → the resolved fact edges threaded INTO it (`<node>.<fact>` refs + declared
+  // types), so pass 4 can confirm a converge/wait PR reference is actually threaded and `pr`-typed.
+  const incomingFactRefs = new Map<string, { ref: string; factName: string; factType: DeliveryFactType | undefined }[]>();
   // Resolved, well-formed edges captured for the guard/topology pass (pass 3). Only edges whose BOTH
   // endpoints resolve are kept — a dangling/self edge is already reported and must not reach pass 3.
   const guardEdges: {
@@ -556,6 +598,13 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
       const ups = adjacency.get(to) ?? new Set<string>();
       ups.add(nodeId);
       adjacency.set(to, ups);
+      // #548: record a resolved, DECLARED fact edge so pass 4 can confirm a converge/wait PR reference
+      // is actually threaded into its consumer (and is `pr`-typed).
+      if (fact !== undefined && upstreamFacts.has(fact)) {
+        const refs = incomingFactRefs.get(to) ?? [];
+        refs.push({ ref: `${nodeId}.${fact}`, factName: fact, factType: nodeFactTypes.get(nodeId)?.get(fact) });
+        incomingFactRefs.set(to, refs);
+      }
       guardEdges.push({
         index: i,
         fromNode: nodeId,
@@ -570,14 +619,119 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
   });
 
   collectCycle(adjacency, errors);
-  // Pass 3: guard (S7) semantics — only when the graph is otherwise structurally sound (every edge
-  // resolved, no cycle). A malformed base graph is reported first; guard analysis assumes a DAG.
+  // Passes 3 & 4 assume an otherwise structurally-sound graph (every edge resolved, no cycle) — a
+  // malformed base graph is reported first, and guard/binding analysis assumes a DAG with resolved
+  // fact edges. Both run under the SAME soundness snapshot so a pass-3 guard error can't suppress a
+  // pass-4 binding error (they are independent classes and should surface together).
   if (errors.length === 0) {
+    // Pass 3: guard (S7) semantics.
     validateGuardedEdges(guardEdges, nodeFactTypes, errors);
+    // Pass 4 (#548): converge/wait PR late-binding — a referenced PR fact must be threaded + `pr`-typed.
+    validatePrBindings(prBindConsumers, incomingFactRefs, nodeFacts, nodeFactTypes, errors);
   }
   return errors;
 }
 
+/** Pass 4 (#548) — validate that every converge-connector / pr-wait node can resolve its target PR.
+ * A converge/wait node needs a PR to enroll or poll; it may name it three ways (mirroring the runtime
+ * `resolveConvergePr` / the wait compiler `context put` late-bind):
+ *   • a LITERAL `owner/repo#N` — never `<node>.<fact>`-shaped, so it resolves to no graph node and is
+ *     accepted here (the worker/probe validates the literal at runtime);
+ *   • a fact REFERENCE `<node>.pr` — REQUIRES that the referenced node declares a `pr`-typed fact of
+ *     that name AND that a fact edge actually threads it into this consumer (else it can never bind);
+ *   • OMITTED (connectors only) — auto-binds the single incoming `pr` fact, else the single incoming
+ *     fact; rejected when there is no PR to bind or the choice is ambiguous.
+ * Rejecting these at compile (fail closed, path-qualified) turns a silent runtime "requires payload.pr"
+ * / unparseable-target failure into an actionable authoring error. */
+function validatePrBindings(
+  consumers: readonly {
+    path: string;
+    field: "connector.payload.pr" | "wait.target";
+    id: string;
+    authored: string | undefined;
+  }[],
+  incomingFactRefs: ReadonlyMap<string, { ref: string; factName: string; factType: DeliveryFactType | undefined }[]>,
+  nodeFacts: ReadonlyMap<string, ReadonlySet<string>>,
+  nodeFactTypes: ReadonlyMap<string, ReadonlyMap<string, DeliveryFactType>>,
+  errors: DeliveryGraphError[],
+): void {
+  for (const c of consumers) {
+    const incoming = incomingFactRefs.get(c.id) ?? [];
+    const errPath = `${c.path}.${c.field}`;
+    if (c.authored !== undefined) {
+      // `resolveFrom` returns a `fact` iff the reference's prefix is an existing node — so a real PR
+      // literal (`owner/repo#N`, no node-qualified dot) resolves to no fact and passes through.
+      const resolved = resolveFrom(c.authored, nodeFacts);
+      if (resolved.fact === undefined) continue; // a literal — validated at runtime.
+      const ref = `${resolved.nodeId}.${resolved.fact}`;
+      const declaredType = nodeFactTypes.get(resolved.nodeId)?.get(resolved.fact);
+      if (declaredType === undefined) {
+        errors.push({
+          path: errPath,
+          message:
+            `${c.id}'s PR reference "${c.authored}" points at fact "${resolved.fact}" that node ` +
+            `"${resolved.nodeId}" does not declare in its \`emits[]\``,
+          code: "unbound-pr",
+        });
+      } else if (declaredType !== "pr") {
+        errors.push({
+          path: errPath,
+          message:
+            `${c.id}'s PR reference "${c.authored}" resolves to a "${declaredType}" fact — a converge/` +
+            "wait PR binding must reference a `pr`-typed fact",
+          code: "unbound-pr",
+        });
+      } else if (!incoming.some((f) => f.ref === ref)) {
+        errors.push({
+          path: errPath,
+          message:
+            `${c.id}'s PR reference "${ref}" is not threaded into it — add a fact edge ` +
+            `{ from: "${ref}", to: "${c.id}" } so the emitted PR late-binds`,
+          code: "unbound-pr",
+        });
+      }
+      continue;
+    }
+    // OMITTED. Only a connector may omit its PR (auto-bind); a wait's `target` is a required field
+    // already reported missing elsewhere, so skip it here to avoid a duplicate error.
+    if (c.field !== "connector.payload.pr") continue;
+    const prNamed = incoming.filter((f) => f.factName === "pr");
+    if (prNamed.length === 1) {
+      if (prNamed[0].factType !== "pr") {
+        errors.push({
+          path: errPath,
+          message:
+            `converge connector "${c.id}" auto-binds its single incoming \`pr\` fact, but that fact is ` +
+            `typed "${prNamed[0].factType}" — declare it as \`pr\` or set connector.payload.pr explicitly`,
+          code: "unbound-pr",
+        });
+      }
+    } else if (prNamed.length === 0 && incoming.length === 1) {
+      if (incoming[0].factType !== "pr") {
+        errors.push({
+          path: errPath,
+          message:
+            `converge connector "${c.id}" would auto-bind its single incoming fact "${incoming[0].ref}", ` +
+            `but it is typed "${incoming[0].factType}", not \`pr\` — thread a \`pr\` fact or set ` +
+            "connector.payload.pr to a literal or `<node>.pr` reference",
+          code: "unbound-pr",
+        });
+      }
+    } else {
+      errors.push({
+        path: errPath,
+        message:
+          prNamed.length === 0
+            ? `converge connector "${c.id}" has no target PR — set connector.payload.pr to a literal ` +
+              '"owner/repo#N" or a "<node>.pr" reference, or thread a single `pr` fact edge into it'
+            : `converge connector "${c.id}" has ${prNamed.length} incoming \`pr\` facts — disambiguate ` +
+              'by setting connector.payload.pr to the specific "<node>.pr" reference',
+        code: "unbound-pr",
+      });
+    }
+  }
+}
+
 /** True when a guard `equals` literal's JSON type matches the referenced fact's declared scalar type. */
 function equalsMatchesFactType(equals: unknown, factType: DeliveryGuardScalarType): boolean {
   switch (factType) {

package/app/deliveryGraphCompiler.test.ts

@@ -252,7 +252,7 @@ test("#514 Defect A: a capability wait-gate escalation surfaces the probe's last
   // Discrete diagnostic task variables the form/agent can bind directly.
   assert(esc.includes('target="probeDetail"'), "the escalation surfaces the probe's last detail as a discrete variable");
   assert(esc.includes('target="observedReleases"'), "the escalation surfaces the observed candidate releases");
-  assert(/source="=nodeInputs\.[^"]+\.probe\.target" target="probeTarget"/.test(esc), "the escalation surfaces the resolved probe target");
+  assert(/source="=if \(is defined\(probe\.target\)\) then probe\.target else nodeInputs\.[^"]+\.probe\.target" target="probeTarget"/.test(esc), "the escalation surfaces the resolved (late-bound) probe target");
   assert(/source="=nodeInputs\.[^"]+\.probe\.match" target="probeMatch"/.test(esc), "the escalation surfaces the resolved probe match");
 });
 
@@ -423,6 +423,56 @@ test("converge-merge worked graph: agent → connector[converge-merge] → wait[
   assert(!r.sideEffects.some((s) => s.nodeId === "merged"), "the wait gate is not a side effect");
 });
 
+test("#548 no-literal converge shape: an emitted `pr` fact late-binds the connector (boundFacts) AND the wait target (context put)", async () => {
+  // The canonical `agent → connector[converge-merge] → wait[pr, merged]` shape carrying NO hardcoded PR
+  // number: `open` emits the PR it opened as a typed `pr` fact, and both downstream consumers reference
+  // it (`open.pr`) on incoming fact edges. The compiler must (a) publish the fact as `<open>_pr`, (b)
+  // thread it into the connector's `boundFacts` input, and (c) rewrite the wait's probe target via
+  // `context put` to poll the late-bound PR.
+  const graph = {
+    name: "no-literal converge",
+    nodes: [
+      {
+        id: "open",
+        kind: "agent",
+        agent: { jobType: "senior:feature", prompt: "Implement and open a PR." },
+        emits: [{ name: "pr", type: "pr" }],
+      },
+      { id: "land", kind: "connector", connector: { target: "converge-merge", payload: { pr: "open.pr" } } },
+      { id: "merged", kind: "wait", wait: { kind: "pr", target: "open.pr", match: { prState: "merged" } } },
+    ],
+    edges: [
+      { from: "open.pr", to: "land" },
+      { from: "open.pr", to: "merged" },
+    ],
+  };
+  const r = await compileOk(graph);
+  const openEl = r.resolved.edges.find((e) => e.from === "open.pr")?.fromNode;
+  assertEquals(openEl, "open", "the fact edge resolves to the `open` producer node");
+  // (a) the producer publishes its declared `pr` emit into a flat `<element>_pr` parent variable.
+  assert(/target="[^"]*_pr"/.test(r.bpmn), "the agent's `pr` emit is published as `<element>_pr`");
+  // (b) the connector receives the fact list — its `boundFacts` input names the `pr` fact + producer.
+  assert(/target="boundFacts"/.test(r.bpmn), "the connector is threaded a boundFacts input");
+  assert(/name: "pr"/.test(r.bpmn), "the boundFacts entry names the `pr` fact");
+  // (c) the wait probe target is late-bound via `context put`, not the raw `open.pr` reference literal.
+  assert(/context put\([^)]*\.probe, "target",/.test(r.bpmn), "the wait probe target is rewritten via context put");
+  assert(!/target="owner\/repo#/.test(r.bpmn), "no hardcoded PR literal is compiled into the graph");
+});
+
+test("a wait node with a LITERAL pr target compiles the probe unchanged (no spurious context put)", async () => {
+  const graph = {
+    name: "literal target",
+    nodes: [
+      { id: "open", kind: "agent", agent: { jobType: "senior:feature", prompt: "open a PR" } },
+      { id: "merged", kind: "wait", wait: { kind: "pr", target: "acme/repo#7", match: { prState: "merged" } } },
+    ],
+    edges: [{ from: "open", to: "merged" }],
+  };
+  const r = await compileOk(graph);
+  assert(!/context put/.test(r.bpmn), "a literal target is not wrapped in a context put rewrite");
+  assert(/source="=nodeInputs\.[^"]+\.probe" target="probe"/.test(r.bpmn), "the probe is seeded directly from nodeInputs");
+});
+
 test("resolved edges carry the resolved fromNode and the referenced fact", async () => {
   const r = await compileOk(RELEASE_RUNBOOK);
   const factEdge = r.resolved.edges.find((e) => e.from === "watch-b.mergedSha");

package/app/deliveryGraphCompiler.ts

@@ -822,12 +822,30 @@ function ioMappingLines(w: NodeWiring, boundInputs: readonly BoundInput[]): stri
       // threads null rather than raising a FEEL error.
       inputs.push({ source: guarded(TRANSCRIPT_URL_BASE_VAR), target: TRANSCRIPT_URL_BASE_VAR });
       break;
-    case "wait":
+    case "wait": {
       inputs.push({ source: cfg("gateKey"), target: "gateKey" });
-      inputs.push({ source: cfg("probe"), target: "probe" });
+      // #548 late-binding: when the authored probe `target` is a `<node>.<fact>` reference to an
+      // upstream emitted fact threaded on an incoming edge, rewrite the seeded probe's `target` to the
+      // OBSERVED value via FEEL `context put`, so the canonical `agent → connector[converge-merge] →
+      // wait[pr, merged]` shape polls the PR the agent opened with NO hardcoded literal. A plain literal
+      // target (a real `owner/repo#N` is never `<node>.<fact>`-shaped) can't match a bound ref, so it
+      // passes through unchanged. Guarded (`is defined`) so an as-yet-unobserved fact keeps the
+      // authored value rather than raising a FEEL error.
+      const boundTarget = boundInputs.find((b) => `${b.fromNode}.${b.fact}` === node.wait.target);
+      if (boundTarget) {
+        const varName = `${boundTarget.producerElement}_${boundTarget.fact}`;
+        const probeRef = cfg("probe").slice(1);
+        inputs.push({
+          source: `=context put(${probeRef}, "target", if (is defined(${varName})) then ${varName} else ${probeRef}.target)`,
+          target: "probe",
+        });
+      } else {
+        inputs.push({ source: cfg("probe"), target: "probe" });
+      }
       inputs.push({ source: cfg("probeTimeout"), target: "probeTimeout" });
       inputs.push({ source: cfg("probePollEvery"), target: "probePollEvery" });
       break;
+    }
     case "human":
       inputs.push({ source: cfg("escalationSlaTimeout"), target: "escalationSlaTimeout" });
       inputs.push({ source: cfg("escalationAssignee"), target: "escalationAssignee" });
@@ -983,7 +1001,7 @@ function waitBodyLines(el: string, node: Extract<DeliveryNode, { kind: "wait" }>
   const diagnosticInputs = [
     { source: "=if (is defined(detail)) then detail else null", target: "probeDetail" },
     { source: "=if (is defined(observed)) then observed else null", target: "observedReleases" },
-    { source: `=nodeInputs.${el}.probe.target`, target: "probeTarget" },
+    { source: `=if (is defined(probe.target)) then probe.target else nodeInputs.${el}.probe.target`, target: "probeTarget" },
     { source: `=nodeInputs.${el}.probe.match`, target: "probeMatch" },
   ];
   return [

package/db/migrations/086_agentic_correlation_element_instance.sql

@@ -0,0 +1,21 @@
+-- Key the durable agent correlation on the ELEMENT INSTANCE, not just the static BPMN element id
+-- (#544, Stage 1 of transcript↔process-run correlation; ADR 0006 §4b intersection, #464).
+--
+-- `078_agentic_correlation.sql` records `element_id` — the STATIC BPMN id — which is ambiguous across
+-- a looping / retried job: the same activity id occupies many distinct element instances over a
+-- process instance's life, so a transcript keyed only by `element_id` cannot say WHICH occupancy a
+-- token was in. `element_instance_key` is the engine's per-occupancy handle (the same one Nano
+-- Explorer addresses runtime position by, and the one Camunda keys its agent model on), resolved from
+-- the agent job's `jobKey` via the engine element-instance wait-state read (nano-ide#473's binding).
+--
+-- Expand-and-contract: this is the EXPAND step — a nullable, additive column alongside the retained
+-- `element_id` (kept during the transition, never dropped here). NULL for pre-#544 rows and whenever
+-- the (advisory, best-effort) resolution did not land, so it never gates a BPMN sequence flow.
+--
+-- Single source of truth: the durable table's canonical DDL is `AGENTIC_CORRELATION_SCHEMA_SQL` in
+-- `app/agentic/correlation-store.ts` (applied idempotently at store construction). This migration
+-- brings an already-078-migrated DB up to that same effective shape; a drift-guard test
+-- (`correlation-store.test.ts`) pins the migrated schema (078 + 086) to the canonical DDL so the two
+-- can never diverge.
+ALTER TABLE agentic_correlation ADD COLUMN element_instance_key TEXT;
+CREATE INDEX IF NOT EXISTS ix_agentic_correlation_element_instance ON agentic_correlation (element_instance_key);

package/docs/adr/0005-agent-authored-delivery-graphs.md

@@ -113,9 +113,11 @@ The closed set (extensible only by a deliberate ADR/PR, never by graph authors):
 > PR back to `converging`. `submitPr`'s own `prKey` idempotency additionally makes a resumed re-perform
 > double-safe on a still-live row. This retires the manual `land-*` human gate whose only job was "go run convergence
 > yourself" — the canonical shape is now `agent (opens PR) → connector[converge-merge] →
-> wait[pr, merged]` with no human node. The payload is `{ pr, convergeOnly?, dependsOn? }`; the MVP
-> sources `pr` as a literal (auto-emitting it from the `agent` node as a typed `pr` fact is a deferred
-> follow-up). Other connector targets remain the forward-declared stub.
+> wait[pr, merged]` with no human node. The payload is `{ pr, convergeOnly?, dependsOn? }`; the `pr`
+> may be a literal `owner/repo#N`, a `<node>.pr` fact reference late-bound from an upstream `agent`
+> node's emitted `pr` fact, or omitted to auto-bind the single incoming `pr` fact (issue #548 —
+> shipped: the connector resolves it via `resolveConvergePr`, and the `wait[pr]` target is late-bound
+> in the compiler via FEEL `context put`). Other connector targets remain the forward-declared stub.
 
 Crucially, **execution stays engine-native**: each node kind is a real, already-deployed
 sub-process / call activity (`readiness-gate`, a user task, the implementation task, a connector

package/docs/agent-guide.md

@@ -597,28 +597,41 @@ into the PR's merge-stage dependency set. The enrollment is idempotent (the conn
 at-least-once dedupe fence **plus** `submitPr`'s own `prKey` idempotency), so a graph resume /
 redelivery never double-enrolls.
 
-**Canonical shape** — the agent opens the PR, the connector enrolls it, and a `wait[pr, merged]`
-gate binds `mergedSha` when it lands, with **no human node**:
+**Canonical shape** — the agent opens the PR, emits it as a typed **`pr` fact**, and the connector
+and `wait[pr, merged]` gate **late-bind** that fact (no hardcoded PR number, no human node). The
+author never knows the PR number at compose time, so reference it by fact:
 
 ```json
 {
   "name": "open → converge+merge → wait merged",
   "nodes": [
     { "id": "open", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "prompt": "Implement the change in acme/repo and open a PR." } },
+      "agent": { "jobType": "senior:feature", "prompt": "Implement the change in acme/repo and open a PR." },
+      "emits": [ { "name": "pr", "type": "pr" } ] },
     { "id": "land", "kind": "connector",
-      "connector": { "target": "converge-merge", "payload": { "pr": "acme/repo#123" } } },
+      "connector": { "target": "converge-merge", "payload": { "pr": "open.pr" } } },
     { "id": "merged", "kind": "wait",
-      "wait": { "kind": "pr", "target": "acme/repo#123", "match": { "prState": "merged" }, "onTimeout": "escalate" } }
+      "wait": { "kind": "pr", "target": "open.pr", "match": { "prState": "merged" }, "onTimeout": "escalate" } }
   ],
   "edges": [
-    { "from": "open", "to": "land" },
-    { "from": "land", "to": "merged" }
+    { "from": "open.pr", "to": "land" },
+    { "from": "open.pr", "to": "merged" }
   ]
 }
 ```
 
-> **Follow-up (not shipped):** the MVP sources the connector's `pr` as a **literal**. Auto-emitting
-> the opened PR from the `agent` node as a typed `pr` fact (so the connector/`wait` bind it instead of
-> a literal) is a later slice — not required for the graph above.
+The `pr` fact is threaded along the **fact-qualified edges** (`open.pr → land`, `open.pr → merged`) —
+those edges are what carry the observed PR into each consumer, so they are **required** when you
+reference `open.pr` (the validator rejects a reference with no threading edge, `unbound-pr`). Three
+ways to name the target PR:
+
+- **fact reference** `"<node>.pr"` — late-bound from the upstream `agent`'s emitted `pr` fact (the
+  shape above). The referenced fact must be declared **`pr`-typed** and threaded on an incoming edge.
+- **omitted** (connector only) — `payload` without a `pr` auto-binds the **single** incoming `pr`
+  fact, so `"connector": { "target": "converge-merge" }` works when exactly one `pr` fact flows in.
+- **literal** `"owner/repo#N"` — still accepted for a PR you already know (a real ref is never
+  `<node>.pr`-shaped, so it never collides with a reference).
+
+`senior:feature` already returns the PR it opened, so declaring `emits: [{ "name": "pr", "type": "pr" }]`
+on the agent node is all it takes to publish it (issue #548).
 

package/e2e/delivery-graph.e2e.ts

@@ -155,6 +155,36 @@ describe("delivery-graph runner — engine-native execution (S4)", () => {
     assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the graph reached its End event");
   });
 
+  test("#548 wait target LATE-BINDS from an upstream fact via FEEL `context put` (engine-native)", async () => {
+    const app = track(await boot(freshDir()));
+
+    // The agent emits a `cmd` fact whose OBSERVED value is the deterministic green probe command
+    // ("true"). The downstream wait references that fact as its probe `target` (`a.cmd`) — the compiler
+    // rewrites the seeded probe's target via FEEL `context put`, so the probe polls the LATE-BOUND
+    // value, not a hardcoded literal. This is the exact mechanism the canonical `agent →
+    // connector[converge-merge] → wait[pr, merged]` shape uses to poll the PR the agent opened (#548).
+    await app.engine.registerWorker("senior:demo", async () => ({ cmd: "true" }));
+
+    const graph: DeliveryGraph = {
+      name: "e2e wait late-bind",
+      nodes: [
+        { id: "a", kind: "agent", agent: { jobType: "senior:demo" }, emits: [{ name: "cmd", type: "string" }] },
+        { id: "w", kind: "wait", wait: { kind: "command", target: "a.cmd", poll: { everyMs: 5, backoff: "fixed" } } },
+      ],
+      edges: [{ from: "a.cmd", to: "w" }],
+    };
+
+    const run = await runDeliveryGraph(app.engine, graph, { probeTimeout: "PT2S" });
+    assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
+    await app.settle();
+
+    // The wait's probe ran the LATE-BOUND command "true" (green) — had `context put` not resolved the
+    // `a.cmd` reference to "true", the probe would have run the literal "a.cmd" (a probe escape the
+    // hermetic seam records + fails on), and the gate would never have resolved. The graph reaching End
+    // proves the wait released its ready branch off the late-bound target.
+    assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the late-bound wait resolved and the graph reached 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/main.ts

@@ -20,6 +20,7 @@
 import { Server } from "node:http";
 import { createNanoSdkEngineClient, runFromEnv, selectHost } from "@nanobpm/urban";
 import { type AgenticChannelHandle, mountAgenticChannel } from "./app/agentic/channel.ts";
+import { makeElementInstanceResolver } from "./app/agentic/element-instance.ts";
 import { announceEngine, resolveEngineAddress } from "./app/enginePreflight.ts";
 import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
 import { envVar } from "./app/version.ts";
@@ -79,6 +80,11 @@ if (httpServer instanceof Server) {
       secret: agenticSecret ?? "",
       secure,
       data: app.data,
+      // #544: advisory, read-only element-instance resolution over the shared engine's wait-state
+      // read model, so the relay slice can key a captured agent session on the element INSTANCE it
+      // occupied (unambiguous across a looping / retried job), not just the static element id. A
+      // narrow closure — the agentic families never hold the engine handle itself.
+      resolveElementInstance: makeElementInstanceResolver(engine),
       log: app.log,
     });
     if (!secure) {