@nanobpm/nano-workforce 0.141.0 → 0.142.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.142.0](https://github.com/nanobpm/nano-workforce/compare/v0.141.0...v0.142.0) (2026-08-25)
+
+### Features
+
+* **delivery-graph:** late-bind converge/wait PR from an emitted `pr` fact ([#548](https://github.com/nanobpm/nano-workforce/issues/548)) ([#550](https://github.com/nanobpm/nano-workforce/issues/550)) ([dbb3aab](https://github.com/nanobpm/nano-workforce/commit/dbb3aabfe8aeaa9951d2ce9f5a2b732eaa99748b))
+
 ## [0.141.0](https://github.com/nanobpm/nano-workforce/compare/v0.140.0...v0.141.0) (2026-08-25)
 
 ### Features

package/app/convergeTargets.ts

@@ -0,0 +1,30 @@
+// The converge-enrollment connector-target vocabulary (ADR 0005, issue #500) — the SINGLE, dependency-
+// free source of truth for the `converge` / `converge-merge` literals and their derived semantics.
+// Extracted from `deliveryConnector.ts` so the pure, import-free semantic validator (`deliveryGraph.ts`)
+// can share the exact same predicate WITHOUT pulling in the connector module's urban/data-layer deps —
+// a converge/wait node's late-binding validation (issue #548) must agree with the worker's dispatch
+// branch on what "a converge target" is, and this module is what keeps them from drifting.
+
+/** The review-only converge target: enrolls a PR into the shared convergence loop and STOPS at
+ * `converged` (never hands it to the merge loop). */
+export const CONVERGE_TARGET = "converge";
+
+/** The converge-AND-merge target: enrolls a PR into the shared convergence loop and drives the merge
+ * loop too (the canonical `agent → connector[converge-merge] → wait[pr, merged]` land shape). */
+export const CONVERGE_MERGE_TARGET = "converge-merge";
+
+/** Is `target` one of the converge-enrollment targets (`converge` / `converge-merge`)? The single
+ * predicate the connector worker branches on to route a dispatch into `submitPr`, and the validator
+ * branches on to require a bound/literal PR (issue #548). */
+export function isConvergeTarget(target: string): boolean {
+  return target === CONVERGE_TARGET || target === CONVERGE_MERGE_TARGET;
+}
+
+/** The DEFAULT `convergeOnly` for a converge target: `converge` is review-only (`true` — stop at
+ * `converged`), `converge-merge` drives the merge loop too (`false`). Maps directly onto `submitPr`'s
+ * `convergeOnly` argument. An author may still override it per-dispatch via the connector payload's
+ * `convergeOnly`. Only ever consulted behind `isConvergeTarget`, so a non-converge target's `false`
+ * is unreachable. */
+export function convergeOnlyForTarget(target: string): boolean {
+  return target === CONVERGE_TARGET;
+}

package/app/deliveryConnector.ts

@@ -39,26 +39,14 @@ export const OUTCOME_DELIVERED = "delivered";
  * convergence AND the merge loop; `converge` stops at `converged` (converge-only). This is the "real
  * target dispatch" ADR 0005 deferred as a later slice for the connector I/O surface: a `converge`/
  * `converge-merge` connector IS the "automated, side-effecting outbound action" a connector is
- * defined to be. Named constants so the worker's dispatch branch and the docs/preview can never drift
- * on the literal. */
-export const CONVERGE_TARGET = "converge";
-export const CONVERGE_MERGE_TARGET = "converge-merge";
-
-/** Is `target` one of the converge-enrollment targets (`converge` / `converge-merge`)? The single
- * predicate the worker branches on to route a dispatch into `submitPr` instead of the forward-declared
- * stub. */
-export function isConvergeTarget(target: string): boolean {
-  return target === CONVERGE_TARGET || target === CONVERGE_MERGE_TARGET;
-}
-
-/** The DEFAULT `convergeOnly` for a converge target: `converge` is review-only (`true` — stop at
- * `converged`), `converge-merge` drives the merge loop too (`false`). Maps directly onto `submitPr`'s
- * `convergeOnly` argument (mirroring how `converge-feature` inverts `autoMerge`). An author may still
- * override it per-dispatch via the connector payload's `convergeOnly`. Only ever consulted behind
- * `isConvergeTarget`, so a non-converge target's `false` is unreachable. */
-export function convergeOnlyForTarget(target: string): boolean {
-  return target === CONVERGE_TARGET;
-}
+ * defined to be. The converge-target vocabulary lives in the dependency-free {@link ./convergeTargets.ts}
+ * so the pure validator can share it; re-exported here for the worker's existing import surface. */
+export {
+  CONVERGE_MERGE_TARGET,
+  CONVERGE_TARGET,
+  convergeOnlyForTarget,
+  isConvergeTarget,
+} from "./convergeTargets.ts";
 
 /** One durable dispatch-claim row — the at-most-once ledger entry a connector writes before it acts. */
 export interface DeliveryConnectorDispatchRow extends Record<string, unknown> {
@@ -82,6 +70,29 @@ export interface BoundFact {
   value: unknown;
 }
 
+/** Resolve a converge connector's effective target PR (issue #548), late-binding it from an upstream
+ * `agent` node's emitted `pr` fact so the canonical `agent → connector[converge-merge] → wait` shape
+ * needs NO hardcoded literal. Precedence, given the author-supplied `payload.pr` and the threaded
+ * `boundFacts`:
+ *   • an explicit fact REFERENCE — a `payload.pr` string that exactly matches a threaded fact's
+ *     `<from>.<name>` — resolves to that fact's value (an `owner/repo#N` PR ref emitted upstream);
+ *   • an explicit LITERAL — any other `payload.pr` string — is returned as-is (a real `owner/repo#N`
+ *     is never `<node>.<fact>`-shaped, so it can't collide with a reference), and `parsePr` validates it;
+ *   • OMITTED (`payload.pr` absent) — binds the single incoming fact named `pr` (the canonical emit),
+ *     else the single incoming bound fact when there is exactly one, else stays undefined so
+ *     {@link readConvergeInput} raises its "requires payload.pr" error (fail closed).
+ * Pure + total (no PR parsing here — the caller validates), so it is unit-testable without the engine. */
+export function resolveConvergePr(payloadPr: unknown, boundFacts: readonly BoundFact[]): unknown {
+  if (typeof payloadPr === "string" && payloadPr.trim() !== "") {
+    const ref = boundFacts.find((b) => `${b.from}.${b.name}` === payloadPr.trim());
+    return ref ? ref.value : payloadPr;
+  }
+  const named = boundFacts.filter((b) => b.name === "pr");
+  if (named.length === 1) return named[0].value;
+  if (named.length === 0 && boundFacts.length === 1) return boundFacts[0].value;
+  return payloadPr;
+}
+
 /** The effective dedupe key for a connector dispatch: the author-supplied `connector.dedupeKey` when
  * present, else a graph-derived `<processInstanceKey>:<elementId>` — both STABLE across a re-activation
  * of the same node instance (the engine re-delivers the same job with the same identity), so an

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/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/openapi.yaml

@@ -1361,10 +1361,13 @@ components:
           description: The fact's identifier, referenced downstream as `<nodeId>.<name>`. Must be unique within the node.
         type:
           type: string
-          enum: [string, number, boolean, artifact, version, url]
+          enum: [string, number, boolean, artifact, version, url, pr]
           description: >-
             The fact's declared type. `artifact` is a `pkg@version` handle, `version` a bare version
-            string, `url` a location — mirrors the values `capability`/`pr` probes late-bind.
+            string, `url` a location — mirrors the values `capability`/`pr` probes late-bind. `pr`
+            (issue #548) is a PR reference (`owner/repo#N`) an `agent` node emits for the PR it opened,
+            so a downstream `connector[converge*]`/`wait[pr]` node LATE-BINDS its target PR from the
+            fact instead of a hardcoded literal.
         description:
           type: string
           maxLength: 512

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.141.0",
+  "version": "0.142.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/workers/delivery-connector/worker.test.ts

@@ -123,34 +123,52 @@ test("readConnectorInput: an array payload is rejected (arrays are not plain obj
 
 test("readConvergeInput: parses pr; convergeOnly defaults from the target; dependsOn is optional", () => {
   // `converge-merge` drives the merge loop → convergeOnly defaults false.
-  const merge = readConvergeInput("converge-merge", { pr: "owner/repo#7" });
+  const merge = readConvergeInput("converge-merge", { pr: "owner/repo#7" }, null);
   assertEquals(merge.parsed.prKey, "owner/repo#7");
   assertEquals(merge.convergeOnly, false);
   assertEquals(merge.dependsOn, []);
   // `converge` is review-only → convergeOnly defaults true.
-  const conv = readConvergeInput("converge", { pr: "owner/repo#7" });
+  const conv = readConvergeInput("converge", { pr: "owner/repo#7" }, null);
   assertEquals(conv.convergeOnly, true);
 });
 
 test("readConvergeInput: an explicit payload.convergeOnly overrides the target default; dependsOn threads through", () => {
-  const r = readConvergeInput("converge-merge", { pr: "owner/repo#7", convergeOnly: true, dependsOn: ["owner/repo#5", 42] as unknown as string[] });
+  const r = readConvergeInput("converge-merge", { pr: "owner/repo#7", convergeOnly: true, dependsOn: ["owner/repo#5", 42] as unknown as string[] }, null);
   assertEquals(r.convergeOnly, true, "the explicit boolean wins over the target default");
   assertEquals(r.dependsOn, ["owner/repo#5"], "non-string dependsOn entries are dropped");
 });
 
 test("readConvergeInput: a missing / unparseable pr fails CLOSED (a converge connector with no target PR is meaningless)", () => {
-  assertThrows(() => readConvergeInput("converge-merge", null), Error, "payload.pr");
-  assertThrows(() => readConvergeInput("converge-merge", {}), Error, "payload.pr");
-  assertThrows(() => readConvergeInput("converge", { pr: "not-a-pr" }), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge-merge", null, null), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge-merge", {}, null), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge", { pr: "not-a-pr" }, null), Error, "payload.pr");
 });
 
 test("readConvergeInput: an unparseable pr whose value is not JSON-serializable still fails CLOSED with the intended error (not a serializer TypeError)", () => {
   // `p.pr` is user-controlled payload data; a BigInt (or a circular object) makes JSON.stringify
   // throw, which must NOT mask the intended "requires payload.pr" error.
-  assertThrows(() => readConvergeInput("converge", { pr: 10n as unknown as string }), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge", { pr: 10n as unknown as string }, null), Error, "payload.pr");
   const circular: Record<string, unknown> = {};
   circular.self = circular;
-  assertThrows(() => readConvergeInput("converge", { pr: circular as unknown as string }), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge", { pr: circular as unknown as string }, null), Error, "payload.pr");
+});
+
+test("readConvergeInput: #548 late-binds the PR from an upstream agent's emitted `pr` fact (no literal needed)", () => {
+  const bound = [{ from: "open", name: "pr", value: "owner/repo#42" }];
+  // OMITTED payload.pr → binds the single incoming `pr` fact.
+  assertEquals(readConvergeInput("converge-merge", null, bound).parsed.prKey, "owner/repo#42");
+  assertEquals(readConvergeInput("converge-merge", {}, bound).parsed.prKey, "owner/repo#42");
+  // EXPLICIT reference form → resolves that specific threaded fact.
+  assertEquals(readConvergeInput("converge", { pr: "open.pr" }, bound).parsed.prKey, "owner/repo#42");
+  // A LITERAL still wins as-is even when a bound fact is present (never `<node>.<fact>`-shaped).
+  assertEquals(readConvergeInput("converge", { pr: "owner/repo#9" }, bound).parsed.prKey, "owner/repo#9");
+});
+
+test("readConvergeInput: #548 a dangling reference (no matching bound fact) fails CLOSED", () => {
+  // "open.pr" is reference-shaped but nothing threaded it → falls through to a literal parse, which
+  // rejects (it is not an `owner/repo#N`), so a mis-wired graph never silently enrolls a junk PR.
+  assertThrows(() => readConvergeInput("converge-merge", { pr: "open.pr" }, []), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge-merge", { pr: "open.pr" }, [{ from: "other", name: "pr", value: "o/r#1" }]), Error, "payload.pr");
 });
 
 test("safeStringify: always returns a string, even for values JSON.stringify serializes to undefined (Symbol/undefined/function)", () => {

package/workers/delivery-connector/worker.ts

@@ -15,6 +15,7 @@ import {
   convergeOnlyForTarget,
   dispatchConnector,
   isConvergeTarget,
+  resolveConvergePr,
 } from "../../app/deliveryConnector.ts";
 import { isPrSettled, MAX_ROUNDS, type ParsedPr, parsePr, submitPr } from "../../app/service.ts";
 
@@ -81,19 +82,26 @@ export function safeStringify(value: unknown): string {
  * `convergeOnly` DEFAULTS from the target (`converge` → review-only `true`; `converge-merge` → drive
  * the merge loop `false`) and may be overridden per-dispatch by an explicit boolean. `dependsOn` is an
  * optional list of PR refs unioned into the enrolled PR's merge-stage dependency set (only non-string
- * entries are dropped; `submitPr` itself ignores unparseable refs). Exported for unit coverage — the
- * MVP sources `pr` as a literal (identical to how the `wait: pr` node targets a known PR), so no new
- * fact plumbing is needed to ship. */
+ * entries are dropped; `submitPr` itself ignores unparseable refs). Exported for unit coverage.
+ *
+ * `pr` may be sourced three ways (issue #548), resolved by {@link resolveConvergePr} against the
+ * threaded `boundFacts` BEFORE parsing: a LITERAL `owner/repo#N`, an explicit fact REFERENCE
+ * (`payload.pr: "<upstreamNode>.pr"`), or OMITTED — late-bound from the single incoming `pr` fact an
+ * upstream `agent` node emitted for the PR it opened. This is what lets the canonical
+ * `agent → connector[converge-merge] → wait` shape carry no hardcoded PR number. */
 export function readConvergeInput(
   target: string,
   payload: Record<string, unknown> | null,
+  boundFacts: readonly BoundFact[] | null,
 ): { parsed: ParsedPr; convergeOnly: boolean; dependsOn: string[] } {
   const p = payload ?? {};
-  const parsed = parsePr(p.pr);
+  const prValue = resolveConvergePr(p.pr, boundFacts ?? []);
+  const parsed = parsePr(prValue);
   if (!parsed) {
     throw new Error(
-      `delivery-connector: '${target}' target requires payload.pr as a parseable "owner/repo#N" ` +
-        `(got ${safeStringify(p.pr ?? null)})`,
+      `delivery-connector: '${target}' target requires a target PR — a literal "owner/repo#N" in ` +
+        `payload.pr, an upstream-fact reference (payload.pr: "<node>.pr"), or a threaded \`pr\` fact ` +
+        `bound from an upstream \`agent\` node (got ${safeStringify(prValue ?? null)})`,
     );
   }
   const convergeOnly = typeof p.convergeOnly === "boolean" ? p.convergeOnly : convergeOnlyForTarget(target);
@@ -106,7 +114,7 @@ const handler: AppJobHandler<In, ConnectorDispatchResult> = async (job, app) =>
   // A `converge`/`converge-merge` target enrolls a PR into the shared convergence (+ merge) loop.
   // Parse + validate its payload BEFORE claiming a ledger row, so a misconfigured converge node (no
   // parseable `pr`) fails CLOSED without writing a junk dispatch row it could never act on.
-  const converge = isConvergeTarget(target) ? readConvergeInput(target, payload) : null;
+  const converge = isConvergeTarget(target) ? readConvergeInput(target, payload, boundFacts) : null;
   const dedupeKey = connectorDedupeKey({
     dedupeKey: job.variables.dedupeKey ?? null,
     processInstanceKey: job.processInstanceKey ?? null,