@nanobpm/nano-workforce 0.132.0 → 0.133.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.133.0](https://github.com/nanobpm/nano-workforce/compare/v0.132.0...v0.133.0) (2026-08-24)
+
+### Features
+
+* **delivery-graph:** connector `converge`/`converge-merge` target enrolls a PR via submitPr (retire the manual land gate) ([#501](https://github.com/nanobpm/nano-workforce/issues/501)) ([a24562e](https://github.com/nanobpm/nano-workforce/commit/a24562eb12db8e6f81e6f382e94886a537f16378)), closes [#500](https://github.com/nanobpm/nano-workforce/issues/500)
+
 ## [0.132.0](https://github.com/nanobpm/nano-workforce/compare/v0.131.1...v0.132.0) (2026-08-24)
 
 ### Features

package/app/deliveryConnector.test.ts

@@ -15,10 +15,14 @@ import { join, resolve } from "node:path";
 import type { DataLayer } from "@nanobpm/urban";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import {
+  CONVERGE_MERGE_TARGET,
+  CONVERGE_TARGET,
   connectorDedupeKey,
+  convergeOnlyForTarget,
   type DeliveryConnectorDispatchRow,
   deliveryConnectorDispatches,
   dispatchConnector,
+  isConvergeTarget,
 } from "./deliveryConnector.ts";
 
 const APP_ROOT = resolve(import.meta.dirname, "..");
@@ -84,6 +88,21 @@ test("connectorDedupeKey: author key wins; else derives <processInstanceKey>:<el
   assertEquals(connectorDedupeKey({ processInstanceKey: 12345, elementId: "n3" }), "12345:n3");
 });
 
+test("converge targets: `converge`/`converge-merge` are the enrollment targets; `converge` is review-only", () => {
+  assertEquals(CONVERGE_TARGET, "converge");
+  assertEquals(CONVERGE_MERGE_TARGET, "converge-merge");
+  // Only the two converge literals route into `submitPr`; any other target stays a stub dispatch.
+  assert(isConvergeTarget("converge"));
+  assert(isConvergeTarget("converge-merge"));
+  assert(!isConvergeTarget("slack"));
+  assert(!isConvergeTarget("Converge"));
+  assert(!isConvergeTarget(""));
+  // `convergeOnly` default maps onto `submitPr`'s arg: `converge` stops at converged (true),
+  // `converge-merge` drives the merge loop (false) — mirroring converge-feature's autoMerge inversion.
+  assertEquals(convergeOnlyForTarget("converge"), true);
+  assertEquals(convergeOnlyForTarget("converge-merge"), false);
+});
+
 test("first dispatch delivers exactly once; a redelivery on the same key dedupes and never re-acts", async () => {
   await withApp(async (app) => {
     const at = "2025-01-01T00:00:00.000Z";

package/app/deliveryConnector.ts

@@ -33,6 +33,33 @@ export const DELIVERY_CONNECTOR_TASK_TYPE = "pr.delivery-connector";
 export const OUTCOME_CLAIMED = "claimed";
 export const OUTCOME_DELIVERED = "delivered";
 
+/** The two connector `target`s that enroll an agent-opened PR into the app's SHARED convergence /
+ * merge doors via `submitPr` (issue #500) — the delivery-graph side of the exact seam the feature
+ * cell reuses (`workers/converge-feature`), no duplicated machinery. `converge-merge` drives review
+ * 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;
+}
+
 /** One durable dispatch-claim row — the at-most-once ledger entry a connector writes before it acts. */
 export interface DeliveryConnectorDispatchRow extends Record<string, unknown> {
   id?: number;
@@ -77,16 +104,27 @@ export function connectorDedupeKey(input: {
   return null;
 }
 
-/** The forward-declared connector I/O surface (ADR non-goal — the concrete scheme is deferred). A STUB
- * that "performs" the action by returning a deterministic acknowledgement; a later slice replaces the
- * body with the real transport without touching the idempotency envelope around it. */
-function performConnectorAction(_input: {
+/** The side effect a connector dispatch performs EXACTLY ONCE per dedupe key. It runs only on the claim
+ * winner (or a resumed crashed claim), never on a `deduped` settled redelivery, so a real, non-idempotent
+ * side effect (e.g. `submitPr`, which deliberately re-opens a TERMINAL PR) is fenced by the ledger and
+ * can never double-fire — the reason the enrollment lives HERE rather than unconditionally around the
+ * dispatch. Returns the `detail` recorded on the ledger row. May be async (the real converge enrollment
+ * awaits `submitPr`). Must be idempotent so a resumed crashed claim can safely re-perform it — including
+ * terminal-safe against a NON-idempotent target (the converge action no-ops when its PR already settled,
+ * so a resume can never regress a terminal PR by re-opening it). */
+export type ConnectorAction = (input: {
   target: string;
   payload: Record<string, unknown> | null;
   boundFacts: readonly BoundFact[];
-}): { detail: string } {
+}) => { detail: string } | Promise<{ detail: string }>;
+
+/** The forward-declared connector I/O surface (ADR non-goal — the concrete scheme is deferred). The
+ * DEFAULT `ConnectorAction`: a STUB that "performs" the action by returning a deterministic
+ * acknowledgement; a caller with a real side effect (the converge worker's `submitPr` enrollment) injects
+ * its own action into `dispatchConnector` instead, without touching the idempotency envelope around it. */
+const performConnectorAction: ConnectorAction = (_input) => {
   return { detail: "connector stub — I/O surface forward-declared (ADR 0005 non-goal)" };
-}
+};
 
 /** The result of one connector dispatch attempt. `delivered` — the claim was won and the action fired
  * exactly once; `deduped` — the key was already claimed (an at-least-once redelivery), so the recorded
@@ -107,13 +145,14 @@ async function resumeOrDedupe(
   ledger: ReturnType<typeof deliveryConnectorDispatches>,
   row: DeliveryConnectorDispatchRow,
   input: { dedupeKey: string; target: string; payload?: Record<string, unknown> | null; boundFacts?: readonly BoundFact[] | null },
+  perform: ConnectorAction,
 ): Promise<ConnectorDispatchResult> {
   if (row.outcome === OUTCOME_DELIVERED) {
     return { connectorOutcome: "deduped", connectorDedupeKey: input.dedupeKey, connectorDetail: row.detail ?? "" };
   }
   // Still `claimed` — a prior attempt (sequential or the concurrent-race winner) claimed the key but
   // never recorded delivery. Resume on the existing row rather than dedupe forever on an un-acted claim.
-  const { detail } = performConnectorAction({
+  const { detail } = await perform({
     target: input.target,
     payload: input.payload ?? null,
     boundFacts: input.boundFacts ?? [],
@@ -149,6 +188,7 @@ export async function dispatchConnector(
   data: DataLayer,
   input: { dedupeKey: string; target: string; payload?: Record<string, unknown> | null; boundFacts?: readonly BoundFact[] | null },
   at: string,
+  perform: ConnectorAction = performConnectorAction,
 ): Promise<ConnectorDispatchResult> {
   const ledger = deliveryConnectorDispatches(data);
   const existing = await ledger.findOne({ dedupe_key: input.dedupeKey });
@@ -167,7 +207,7 @@ export async function dispatchConnector(
   if (existing) {
     // A prior attempt recorded (`delivered`) or claimed-but-crashed (`claimed`) this key. Dedupe or
     // resume it on the existing row — the ONE decision shared with the fence-loser path below.
-    return resumeOrDedupe(ledger, existing, input);
+    return resumeOrDedupe(ledger, existing, input, perform);
   }
   let claimId: number | bigint;
   try {
@@ -196,11 +236,11 @@ export async function dispatchConnector(
     // as the sequential path. Deduping a still-`claimed` winner here would complete the job on our ack,
     // so a winner that then crashed would strand the side effect forever (the engine won't redeliver an
     // acked job); resuming closes that gap and is safe because the action is idempotent.
-    if (won) return resumeOrDedupe(ledger, won, input);
+    if (won) return resumeOrDedupe(ledger, won, input, perform);
     return { connectorOutcome: "deduped", connectorDedupeKey: input.dedupeKey, connectorDetail: "" };
   }
   // We alone won the claim — perform the side effect exactly once and record its outcome on our row.
-  const { detail } = performConnectorAction({
+  const { detail } = await perform({
     target: input.target,
     payload: input.payload ?? null,
     boundFacts: input.boundFacts ?? [],

package/app/deliveryGraphCompiler.test.ts

@@ -280,6 +280,29 @@ test("sideEffects: agent + connector only; connector carries its dedupeKey", asy
   assert(!r.sideEffects.some((s) => s.nodeId === "publish"));
 });
 
+test("converge-merge worked graph: agent → connector[converge-merge] → wait[pr,merged] compiles with NO human node (retires the manual land gate, #500)", async () => {
+  const graph = {
+    name: "open → converge+merge → wait merged",
+    nodes: [
+      { id: "open", kind: "agent", agent: { jobType: "senior:feature", prompt: "Implement the change and open a PR." } },
+      { id: "land", kind: "connector", connector: { target: "converge-merge", payload: { pr: "acme/repo#123" } } },
+      { id: "merged", kind: "wait", wait: { kind: "pr", target: "acme/repo#123", match: { prState: "merged" }, onTimeout: "escalate" } },
+    ],
+    edges: [
+      { from: "open", to: "land" },
+      { from: "land", to: "merged" },
+    ],
+  };
+  const r = await compileOk(graph);
+  // The canonical shape has NO human land-* gate — convergence is driven by the connector itself.
+  assertEquals(r.humanNodes.length, 0, "no human node bridges the PR to convergence");
+  // The connector is a side effect, naming its converge-merge target; the wait gate is read-only.
+  const connector = r.sideEffects.find((s) => s.nodeId === "land");
+  assertEquals(connector?.kind, "connector");
+  assert(connector?.description.includes("converge-merge"), "the side-effect names the converge-merge target");
+  assert(!r.sideEffects.some((s) => s.nodeId === "merged"), "the wait gate is not a side effect");
+});
+
 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/service.test.ts

@@ -11,7 +11,9 @@ import { memDataFor } from "../test/worldDb.ts";
 import { withTrackingViews } from "../test/trackingViews.ts";
 import { DurableResumeRegistry } from "./durableResume.ts";
 import { WorldStore } from "./world/index.ts";
-import { abandonClosedPr, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
+import { abandonClosedPr, isPrSettled, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
+import { trackingTargetFor } from "./instanceTracking.ts";
+import type { DataLayer } from "@nanobpm/urban";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -49,6 +51,31 @@ function withGithubOff(run: () => Promise<void>): Promise<void> {
   });
 }
 
+test("isPrSettled reads the derived tracking view — an out-of-band-abandoned PR (base row still converging) is settled", async () => {
+  // The base `pull_requests` row still reads `converging`, but the ADR-0065 derived tracking VIEW
+  // folds the reconciler's out-of-band terminal edge into `derived_status: "abandoned"`. Terminal-edge
+  // classification must read `derived_status`, not the stale base `status`, or a crash-window RESUME
+  // of the delivery-connector enrollment action re-runs `submitPr` against a PR that has actually
+  // already settled (and the ledger detail falsely claims it enrolled).
+  const PR_KEY = "owner/repo#7";
+  const view = trackingTargetFor("pull_requests").view;
+  const base = { pr_key: PR_KEY, status: "converging" };
+  function make(derived: string) {
+    return {
+      table(name: string) {
+        if (name === "pull_requests") return { get: async (k: string) => (k === PR_KEY ? { ...base } : null) };
+        if (name === view) return { get: async (k: string) => (k === PR_KEY ? { ...base, derived_status: derived } : null) };
+        throw new Error(`unexpected table ${name}`);
+      },
+    } as any as DataLayer;
+  }
+  assertEquals(await isPrSettled(make("abandoned"), PR_KEY), true, "out-of-band-abandoned PR is settled via derived_status");
+  assertEquals(await isPrSettled(make("converging"), PR_KEY), false, "a genuinely live PR is not settled");
+  const empty = { table: () => ({ get: async () => null }) } as any as DataLayer;
+  assertEquals(await isPrSettled(empty, PR_KEY), false, "an absent PR row is not settled");
+});
+
+
 test("re-submit of a cancelled PR marks stale open escalations", async () => {
   await withGithubOff(async () => {
     const PR_KEY = "owner/repo#42";

package/app/service.ts

@@ -482,6 +482,21 @@ export async function worldRestoreSha(data: DataLayer, prKey: string): Promise<s
   return lastPushedSha(data, prKey);
 }
 
+/** Whether the `pull_requests` row for `prKey` already exists AND is in a TERMINAL state
+ * (`converged`/`merged`/`abandoned`). Reads the ADR-0065 derived tracking VIEW's `derived_status`
+ * (via `prsTracking`), NOT the base `status`, so an out-of-band-terminated PR — whose base row is
+ * still `converging` but whose reconciled edge is `abandoned` — is correctly seen as settled. The
+ * delivery-connector's converge-enrollment action guards on this so a crash-window RESUME (a
+ * `claimed`-but-not-`delivered` ledger row whose first attempt already enrolled the PR and let it
+ * settle) never re-runs `submitPr` against a settled PR — `submitPr` deliberately RE-OPENS a terminal
+ * row, so an unconditional re-perform would flip the PR back to `converging`, regressing a settled PR.
+ * Reuses the canonical `TERMINAL_STATUSES` so the terminal-safety check can't drift from the one the
+ * loop/incident logic uses. */
+export async function isPrSettled(data: DataLayer, prKey: string): Promise<boolean> {
+  const existing = await prsTracking(data).get(prKey);
+  return !!existing && TERMINAL_STATUSES.includes(existing.derived_status);
+}
+
 /** Register a PR row (if new) and start the convergence process. Idempotent on prKey. Optional
  * `dependsOn` (explicit refs) is unioned with any `Depends-on:` line parsed from the PR body and
  * recorded as the PR's merge-stage dependency set. */

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

@@ -99,6 +99,24 @@ The closed set (extensible only by a deliberate ADR/PR, never by graph authors):
 - **`human`** — a scheduled user task + form (§4).
 - **`connector`** — an automated, side-effecting outbound action (the connector I/O surface).
 
+> **Amendment (issue #500): the connector's first REAL target landed — `converge` / `converge-merge`.**
+> The connector I/O surface shipped in slice S4 with a deliberately forward-declared STUB action
+> (`performConnectorAction`), the real target dispatch deferred to a later slice. That slice is this:
+> a `connector` node whose `target` is **`converge-merge`** (or **`converge`** for converge-only)
+> enrolls its `payload.pr` into the app's shared convergence (+ merge) loop via `submitPr` — the SAME
+> seam the feature cell reuses (`workers/converge-feature`), no duplicated machinery. Enrollment is
+> defined in the worker (it has `app.data`/`app.engine`) but **injected into `dispatchConnector` as the
+> connector's action**, so the existing at-most-once ledger fence wraps the enrollment itself: it fires
+> only on the claim winner (or a resumed crashed claim), and a `deduped` redelivery — a restart / lost
+> ack / graph resume that lands AFTER the PR settled — never re-runs it. That matters because `submitPr`
+> deliberately RE-OPENS a terminal PR; an unfenced re-call would flip a `merged`/`converged`/`abandoned`
+> 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.
+
 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
 invocation). The graph layer owns **scheduling** (which nodes' edges are satisfied → dispatch), not a

package/docs/agent-guide.md

@@ -435,7 +435,7 @@ layer schedules, it does not re-implement execution):
 | `agent` | `agent: { jobType, prompt? }` | a worker runs an agent job type (the fan-out body). **Side-effecting.** | yes |
 | `wait` | `wait: <ReadinessProbe>` | a durable, bounded readiness probe — kind ∈ `http`, `command`, `npm`, `github-check`, `capability`, `pr`. Read-only. | yes (binds observed facts) |
 | `human` | `human?: { formKey?, prompt? }` | a scheduled user task + form (the Tasks inbox, §3). Blocks dependents, SLA-bounded, answerable by a human **or** an agent. | yes |
-| `connector` | `connector: { target, dedupeKey?, payload? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). *(payload is a forward-declared stub.)* | yes |
+| `connector` | `connector: { target, dedupeKey?, payload? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Two **real targets** ship today — **`converge`** and **`converge-merge`** (§9.4); other targets are a forward-declared stub. | yes |
 
 A **`wait` node's `wait` is a `ReadinessProbe` verbatim** (the same shape feature-run
 intake uses): `{ kind, target, onTimeout?, match?, poll? }`. The **`pr` kind** watches an
@@ -559,3 +559,49 @@ To swap the manual PR-#303 path for a **capability** edge instead of a raw `pr`
 the consumer a `wait` node with `kind: "capability"` (resolving *which published
 `pkg@version` first carries the change*) fed by the same `manual-publish.publishedVersion`
 fact — the fact-edge syntax is identical.
+
+### 9.4 Connector targets — drive a PR to convergence + merge (`converge` / `converge-merge`)
+
+A `connector` node with **`target: "converge-merge"`** (or **`"converge"`**) enrolls an
+agent-opened PR into the app's **shared convergence loop** — the *same* enrollment §1 (a
+standalone submit) and a feature run use (`submitPr`), no duplicated machinery. This replaces
+the old habit of bridging an `agent`-opened PR to review with a **human `land-*` gate** whose
+only job was "go run convergence yourself".
+
+- **`converge-merge`** — drive review convergence **and then the merge loop** (the PR merges
+  once converged + green). Equivalent to a submit with `convergeOnly: false`.
+- **`converge`** — **converge-only**: drive review convergence and stop at `converged`, never
+  handing off to the merge loop (equivalent to `convergeOnly: true`).
+
+**Payload:** `{ pr: "owner/repo#123", convergeOnly?: boolean, dependsOn?: string[] }`. `pr` is
+required (a literal `owner/repo#N`, identical to how a `wait: pr` node targets a known PR).
+`convergeOnly` defaults from the target and may be overridden per-node; `dependsOn` is unioned
+into the PR's merge-stage dependency set. The enrollment is idempotent (the connector's
+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**:
+
+```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." } },
+    { "id": "land", "kind": "connector",
+      "connector": { "target": "converge-merge", "payload": { "pr": "acme/repo#123" } } },
+    { "id": "merged", "kind": "wait",
+      "wait": { "kind": "pr", "target": "acme/repo#123", "match": { "prState": "merged" }, "onTimeout": "escalate" } }
+  ],
+  "edges": [
+    { "from": "open", "to": "land" },
+    { "from": "land", "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.
+

package/package.json

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

@@ -4,7 +4,83 @@
 // `payload`/`boundFacts` is coerced to null with a surfaced warning rather than passed through.
 import { test } from "node:test";
 import { assert, assertEquals, assertThrows } from "#test-assert";
-import { readConnectorInput } from "./worker.ts";
+import { PROCESS_ID } from "../../app/service.ts";
+import { withTrackingViews } from "../../test/trackingViews.ts";
+import handler, { readConnectorInput, readConvergeInput, safeStringify } from "./worker.ts";
+
+function memTable(rows: Record<string, unknown>[], key: string) {
+  return {
+    get: (k: unknown) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    all: () => Promise.resolve([...rows]),
+    find: (q: Record<string, unknown>) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    findOne: (q: Record<string, unknown>) =>
+      Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v)) ?? null),
+    insert: (r: Record<string, unknown>) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    update: (k: unknown, patch: Record<string, unknown>) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r);
+    },
+    delete: (k: unknown) => {
+      for (let i = rows.length - 1; i >= 0; i--) if (rows[i][key] === k) rows.splice(i, 1);
+      return Promise.resolve();
+    },
+  };
+}
+
+/** A hermetic `app` over in-memory tables + a createInstance-capturing engine, with the GitHub
+ * transport forced off so `submitPr`'s best-effort meta fetch is skipped. Returns the created
+ * convergence-loop instances so a test can assert the exact enrollment `submitPr` performed. */
+function fakeApp() {
+  const stores: Record<string, { rows: Record<string, unknown>[]; key: string }> = {
+    pull_requests: { rows: [], key: "pr_key" },
+    escalations: { rows: [], key: "id" },
+    pr_dependencies: { rows: [], key: "pr_key" },
+    delivery_connector_dispatches: { rows: [], key: "id" },
+  };
+  const created: { processDefinitionId?: string; variables?: Record<string, unknown> }[] = [];
+  let nextId = 1;
+  const data = {
+    table: withTrackingViews((name: string, key: string) => {
+      const store = stores[name] ?? { rows: [], key };
+      stores[name] ??= store;
+      // The ledger PK is auto-assigned on insert (mimics the RAD Table<T> autoincrement).
+      if (name === "delivery_connector_dispatches") {
+        const base = memTable(store.rows, store.key);
+        return { ...base, insert: (r: Record<string, unknown>) => {
+          const id = nextId++;
+          store.rows.push({ ...r, id });
+          return Promise.resolve(id);
+        } } as ReturnType<typeof memTable>;
+      }
+      return memTable(store.rows, store.key);
+    }),
+  };
+  const engine = {
+    createInstance: (req: { processDefinitionId?: string; variables?: Record<string, unknown> }) => {
+      created.push(req);
+      return Promise.resolve({ processInstanceKey: `PI-${created.length}` });
+    },
+  };
+  const app = { data, engine, log: { info() {}, warn() {}, error() {} } };
+  return { app: app as unknown as Parameters<typeof handler>[1], stores, created };
+}
+
+function withGithubOff(run: () => Promise<void>): Promise<void> {
+  const prevMode = process.env.NANO_PR_GITHUB_TRANSPORT;
+  const prevTok = process.env.GITHUB_TOKEN;
+  process.env.NANO_PR_GITHUB_TRANSPORT = "token"; // no token below -> fetchPrMeta returns null
+  delete process.env.GITHUB_TOKEN;
+  return run().finally(() => {
+    if (prevMode !== undefined) process.env.NANO_PR_GITHUB_TRANSPORT = prevMode;
+    else delete process.env.NANO_PR_GITHUB_TRANSPORT;
+    if (prevTok !== undefined) process.env.GITHUB_TOKEN = prevTok;
+  });
+}
 
 test("readConnectorInput: a blank/missing target fails closed (a connector with no destination is meaningless)", () => {
   for (const target of [undefined, "", "   "]) {
@@ -42,3 +118,165 @@ test("readConnectorInput: an array payload is rejected (arrays are not plain obj
   assertEquals(r.payload, null);
   assertEquals(r.warnings.length, 1);
 });
+
+// --- converge / converge-merge targets: enroll a PR into the shared convergence loop (issue #500) ---
+
+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" });
+  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" });
+  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[] });
+  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");
+});
+
+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");
+  const circular: Record<string, unknown> = {};
+  circular.self = circular;
+  assertThrows(() => readConvergeInput("converge", { pr: circular as unknown as string }), Error, "payload.pr");
+});
+
+test("safeStringify: always returns a string, even for values JSON.stringify serializes to undefined (Symbol/undefined/function)", () => {
+  // JSON.stringify returns `undefined` (WITHOUT throwing) for a Symbol, a bare undefined, or a
+  // function. safeStringify is typed `: string`, so it must fall back to String(value) rather than
+  // leak that `undefined` through and violate its own contract.
+  assertEquals(typeof safeStringify(Symbol("x")), "string");
+  assertEquals(typeof safeStringify(undefined), "string");
+  assertEquals(typeof safeStringify(() => 0), "string");
+  // A normal serializable value still round-trips through JSON.stringify.
+  assertEquals(safeStringify({ a: 1 }), '{"a":1}');
+});
+
+test("handler: a `converge-merge` connector enrolls the PR into the convergence loop via submitPr (row + started convergence-loop instance)", async () => {
+  await withGithubOff(async () => {
+    const { app, stores, created } = fakeApp();
+    await handler(
+      { variables: { target: "converge-merge", payload: { pr: "owner/repo#7" } }, processInstanceKey: "PI-graph", elementId: "n2" } as never,
+      app,
+    );
+    // The identical row + loop a `converge-feature` enrollment produces.
+    assertEquals(stores.pull_requests.rows.length, 1, "exactly one pull_requests row is registered");
+    const pr = stores.pull_requests.rows[0];
+    assertEquals(pr.pr_key, "owner/repo#7");
+    assertEquals(pr.status, "converging");
+    assertEquals(created.length, 1, "the convergence-loop instance was started");
+    assertEquals(created[0]?.processDefinitionId, PROCESS_ID);
+    // converge-merge → not converge-only, so the merge loop is authorised.
+    assertEquals(created[0]?.variables?.convergeOnly, false);
+    assertEquals(created[0]?.variables?.prKey, "owner/repo#7");
+    // Lineage roots on the stable per-node dedupe key (graph-derived here).
+    assertEquals(created[0]?.variables?.rootRequestKey, "PI-graph:n2");
+    // The connector ledger still recorded the dispatch (the at-most-once fence around the stub).
+    assertEquals(stores.delivery_connector_dispatches.rows.length, 1);
+  });
+});
+
+test("handler: a `converge` connector enrolls converge-ONLY (stops at converged, never hands to the merge loop)", async () => {
+  await withGithubOff(async () => {
+    const { app, created } = fakeApp();
+    await handler(
+      { variables: { target: "converge", payload: { pr: "owner/repo#8" } }, processInstanceKey: "PI-g", elementId: "n1" } as never,
+      app,
+    );
+    assertEquals(created.length, 1);
+    assertEquals(created[0]?.variables?.convergeOnly, true);
+  });
+});
+
+test("handler: re-dispatch (at-least-once redelivery) does NOT double-enroll (ledger fence + submitPr prKey idempotency)", async () => {
+  await withGithubOff(async () => {
+    const { app, stores, created } = fakeApp();
+    const job = { variables: { target: "converge-merge", payload: { pr: "owner/repo#9" } }, processInstanceKey: "PI-graph", elementId: "n2" } as never;
+    await handler(job, app);
+    await handler(job, app); // the graph resumes / the job is redelivered
+    assertEquals(stores.pull_requests.rows.length, 1, "still exactly one PR row");
+    assertEquals(created.length, 1, "the convergence-loop is started exactly once (submitPr collapses the repeat)");
+    assertEquals(stores.delivery_connector_dispatches.rows.length, 1, "one ledger row — the dispatch fence deduped");
+  });
+});
+
+test("handler: a redelivery AFTER the PR reached a terminal state does NOT re-enroll (the connector's at-most-once fence, not submitPr's short-circuit)", async () => {
+  await withGithubOff(async () => {
+    const { app, stores, created } = fakeApp();
+    const job = { variables: { target: "converge-merge", payload: { pr: "owner/repo#11" } }, processInstanceKey: "PI-graph", elementId: "n2" } as never;
+    await handler(job, app);
+    assertEquals(created.length, 1, "the first delivery enrolls the PR");
+    // The convergence (+ merge) loop ran to completion; the PR row is now TERMINAL.
+    stores.pull_requests.rows[0].status = "merged";
+    // An at-least-once redelivery (worker restart / lost ack / graph resume) lands AFTER settlement.
+    // `submitPr` deliberately RE-OPENS a terminal row, so the connector must not call it again — the
+    // node instance already fired exactly once, and the ledger fence must suppress the redelivery.
+    await handler(job, app);
+    assertEquals(created.length, 1, "the settled PR is NOT re-enrolled — no second convergence-loop instance");
+    assertEquals(stores.pull_requests.rows[0].status, "merged", "the terminal PR is never flipped back to converging");
+    assertEquals(stores.delivery_connector_dispatches.rows.length, 1, "still one ledger row — the connector fence deduped the redelivery");
+  });
+});
+
+test("handler: a converge redelivery whose prior claim CRASHED before recording delivery still enrolls (resume, not lost)", async () => {
+  await withGithubOff(async () => {
+    const { app, stores, created } = fakeApp();
+    const job = { variables: { target: "converge-merge", payload: { pr: "owner/repo#12" } }, processInstanceKey: "PI-graph", elementId: "n2" } as never;
+    // Simulate a crash BETWEEN claiming the ledger row and recording delivery: a `claimed` row with no
+    // enrollment yet. The redelivery must RESUME (perform the enrollment), never dedupe on the un-acted claim.
+    stores.delivery_connector_dispatches.rows.push({ id: 1, dedupe_key: "PI-graph:n2", target: "converge-merge", outcome: "claimed", detail: null, dispatched_at: "t0" });
+    await handler(job, app);
+    assertEquals(created.length, 1, "the crashed claim is resumed — the enrollment fires exactly once now");
+    assertEquals(stores.pull_requests.rows.length, 1, "the PR was enrolled on resume");
+    assertEquals(stores.delivery_connector_dispatches.rows[0].outcome, "delivered", "the resumed claim is recorded delivered");
+  });
+});
+
+test("handler: a crash-window RESUME whose PR already SETTLED to terminal does NOT re-open it (the enrollment action is terminal-safe)", async () => {
+  await withGithubOff(async () => {
+    const { app, stores, created } = fakeApp();
+    const job = { variables: { target: "converge-merge", payload: { pr: "owner/repo#13" } }, processInstanceKey: "PI-graph", elementId: "n2" } as never;
+    // The first attempt claimed the ledger AND enrolled the PR, which then ran the convergence (+ merge)
+    // loop to completion (`merged`) — but the worker crashed BEFORE recording `delivered`, leaving a
+    // still-`claimed` row. A redelivery RESUMES that claim (perform-again, since it never recorded done).
+    stores.delivery_connector_dispatches.rows.push({ id: 1, dedupe_key: "PI-graph:n2", target: "converge-merge", outcome: "claimed", detail: null, dispatched_at: "t0" });
+    stores.pull_requests.rows.push({ pr_key: "owner/repo#13", status: "merged" });
+    // `submitPr` deliberately RE-OPENS a terminal PR (it only short-circuits a NON-terminal row), so a
+    // resumed re-perform would flip the settled PR back to `converging`. The enrollment action must be
+    // terminal-safe: on resume against an already-settled PR it no-ops (no submitPr, no new instance).
+    await handler(job, app);
+    assertEquals(created.length, 0, "the settled PR is NOT re-enrolled on resume — no new convergence-loop instance");
+    assertEquals(stores.pull_requests.rows[0].status, "merged", "the terminal PR stays terminal (never flipped back to converging)");
+    assertEquals(stores.delivery_connector_dispatches.rows[0].outcome, "delivered", "the resumed claim is recorded delivered (the dispatch is done, no side effect was needed)");
+  });
+});
+
+test("handler: a misconfigured converge connector (no parseable pr) fails CLOSED and writes NO ledger row", async () => {
+  await withGithubOff(async () => {
+    const { app, stores, created } = fakeApp();
+    let threw = false;
+    try {
+      await handler(
+        { variables: { target: "converge-merge", payload: { pr: "garbage" } }, processInstanceKey: "PI", elementId: "n1" } as never,
+        app,
+      );
+    } catch {
+      threw = true;
+    }
+    assert(threw, "a converge connector with no target PR fails closed");
+    assertEquals(created.length, 0, "no convergence-loop instance is started");
+    assertEquals(stores.delivery_connector_dispatches.rows.length, 0, "no junk ledger row is claimed");
+  });
+});

package/workers/delivery-connector/worker.ts

@@ -12,8 +12,11 @@ import {
   type BoundFact,
   type ConnectorDispatchResult,
   connectorDedupeKey,
+  convergeOnlyForTarget,
   dispatchConnector,
+  isConvergeTarget,
 } from "../../app/deliveryConnector.ts";
+import { isPrSettled, MAX_ROUNDS, type ParsedPr, parsePr, submitPr } from "../../app/service.ts";
 
 // Typed off the compiled `connector` subProcess ioMapping (a RUNTIME-generated definition, so there is
 // no static data-envelope to derive from): `target`/`dedupeKey`/`payload` are seeded from the node's
@@ -58,8 +61,52 @@ export function readConnectorInput(vars: In): {
   return { target, payload, boundFacts, warnings };
 }
 
+/** JSON-stringify a user-controlled value for an error message, falling back to `String(value)` when
+ * the value is not JSON-serializable (e.g. a `BigInt` or a circular object throws, or a `Symbol` /
+ * `undefined` / function that `JSON.stringify` serializes to `undefined`) so the intended validation
+ * error is never masked by a serializer `TypeError` and the function always honours its `string`
+ * return type. */
+export function safeStringify(value: unknown): string {
+  try {
+    const s = JSON.stringify(value);
+    return s === undefined ? String(value) : s;
+  } catch {
+    return String(value);
+  }
+}
+
+/** Parse + validate the converge connector's payload (`{ pr, convergeOnly?, dependsOn? }`) for a
+ * `converge` / `converge-merge` target. `pr` is REQUIRED and must parse to a canonical `owner/repo#N`
+ * (fail CLOSED — a converge connector with no target PR is meaningless and could never enroll).
+ * `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. */
+export function readConvergeInput(
+  target: string,
+  payload: Record<string, unknown> | null,
+): { parsed: ParsedPr; convergeOnly: boolean; dependsOn: string[] } {
+  const p = payload ?? {};
+  const parsed = parsePr(p.pr);
+  if (!parsed) {
+    throw new Error(
+      `delivery-connector: '${target}' target requires payload.pr as a parseable "owner/repo#N" ` +
+        `(got ${safeStringify(p.pr ?? null)})`,
+    );
+  }
+  const convergeOnly = typeof p.convergeOnly === "boolean" ? p.convergeOnly : convergeOnlyForTarget(target);
+  const dependsOn = Array.isArray(p.dependsOn) ? p.dependsOn.filter((d): d is string => typeof d === "string") : [];
+  return { parsed, convergeOnly, dependsOn };
+}
+
 const handler: AppJobHandler<In, ConnectorDispatchResult> = async (job, app) => {
   const { target, payload, boundFacts, warnings } = readConnectorInput(job.variables);
+  // 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 dedupeKey = connectorDedupeKey({
     dedupeKey: job.variables.dedupeKey ?? null,
     processInstanceKey: job.processInstanceKey ?? null,
@@ -75,6 +122,46 @@ const handler: AppJobHandler<In, ConnectorDispatchResult> = async (job, app) =>
     app.data,
     { dedupeKey, target, payload, boundFacts },
     new Date().toISOString(),
+    // For a `converge`/`converge-merge` target, the connector's REAL side effect is enrolling the PR
+    // into the shared convergence (+ merge) loop via `submitPr` — the SAME enrollment
+    // `workers/converge-feature` uses, no duplicated machinery. It is injected as the dispatch's
+    // action so it lives INSIDE the at-most-once + resume envelope (`dispatchConnector`): it fires only
+    // on the claim winner (or a resumed crashed claim), and a `deduped` redelivery — a worker restart /
+    // lost ack / graph resume that lands AFTER the PR has settled — NEVER re-runs it. This is what
+    // preserves the connector's at-most-once semantics against `submitPr`, which deliberately RE-OPENS a
+    // terminal PR (it only short-circuits a non-terminal row); an unconditional call outside the fence
+    // would flip a `merged`/`converged`/`abandoned` PR back to `converging` on redelivery.
+    //
+    // The action is ALSO terminal-safe (idempotent on RESUME). A still-`claimed` crashed claim is
+    // re-performed by `dispatchConnector` (it never recorded delivery), and its first attempt may have
+    // already enrolled the PR AND let the convergence/merge loop settle it. Because `submitPr` re-opens a
+    // terminal row, re-performing blindly would regress that settled PR — so the action first checks
+    // `isPrSettled` and NO-OPS when the PR row is already terminal. On a LIVE (non-terminal) row
+    // `submitPr`'s own `prKey` short-circuit (`alreadyRunning`) already makes the resume double-safe.
+    // `rootRequestKey` is the stable per-node `dedupeKey` (authored, else `<processInstanceKey>:<elementId>`),
+    // so the enrolled PR's lineage is deterministic across redeliveries.
+    converge
+      ? async () => {
+          if (await isPrSettled(app.data, converge.parsed.prKey)) {
+            // Resume against an already-settled PR: the enrollment already ran its course. Record the
+            // dispatch delivered WITHOUT re-opening the terminal PR (never regress a settled PR).
+            app.log.info("delivery-connector: enrollment skipped — PR already terminal (resume-safe)", {
+              target,
+              dedupeKey,
+              prKey: converge.parsed.prKey,
+            });
+            return { detail: `${converge.parsed.prKey} already terminal — enrollment skipped (at-most-once resume-safe)` };
+          }
+          await submitPr(app.data, app.engine, converge.parsed, converge.dependsOn, MAX_ROUNDS, converge.convergeOnly, dedupeKey);
+          app.log.info("delivery-connector: enrolled PR into convergence loop", {
+            target,
+            dedupeKey,
+            prKey: converge.parsed.prKey,
+            convergeOnly: converge.convergeOnly,
+          });
+          return { detail: `enrolled ${converge.parsed.prKey} into convergence loop (convergeOnly=${converge.convergeOnly})` };
+        }
+      : undefined,
   );
   app.log.info("delivery-connector", { target, dedupeKey, outcome: result.connectorOutcome });
   return result;