@nanobpm/nano-workforce 0.132.0 → 0.133.1

package/db/migrations/080_plan_read_model_derive_terminal.sql

@@ -0,0 +1,75 @@
+-- Fold the ADR-0065 DERIVED terminal edge into the epic read model (issue #503 — the plans row of the
+-- "migrate remaining terminal-edge readers to derived_status" class).
+--
+-- Since ADR-0065 (`@nanobpm/urban@0.81.0`) the `instanceTracking` reconciler is a SOURCE, not a writer:
+-- on cancel/terminate it feeds urban's instance projection and the terminal edge (`onTerminated →
+-- abandoned`) is RECOMPUTED ON READ as `plans__tracking.derived_status` — it NO LONGER writes
+-- `abandoned` onto the base `plans.status` column. `plans` had NO derived reader, so a terminated epic's
+-- base row stayed frozen at `planning`/`dispatched` and 074's `plan_read_model` bucketed it ACTIVE
+-- forever (a terminated epic rendered active on the epic index/detail).
+--
+-- 074_plan_read_model_derive_bucket.sql made `plan_read_model` the composite VIEW the epic pages bind
+-- and DERIVED `list_bucket`/`ack_open` from the base `plans.status` (+ `acknowledged_at` + the derived
+-- `plan_delivery.delivery` signal). This migration redefines `plan_read_model` (same name, so no page
+-- repoint is needed) to read the EFFECTIVE status off the auto-provisioned `plans__tracking` derived
+-- VIEW instead of the frozen base column: the projected `status` and the bucket/ack derivations now
+-- fold in the reconciler's terminal edge, so a cancelled/terminated epic drops out of Active with no
+-- worker write and no poller pass.
+--
+-- `plans__tracking` is the managed VIEW urban provisions at mount (`<table>__tracking`, ADR-0065),
+-- re-exporting `plans.*` plus a `derived_status` column that is `abandoned` on a terminated instance and
+-- the base `plans.status` otherwise. SQLite does not validate a view body at CREATE time, so this
+-- migration (which runs before the runtime mount that provisions `plans__tracking`) is created fine and
+-- resolves once the managed VIEW exists. The `COALESCE(t.derived_status, pl.status)` fallback degrades to
+-- the previous base-column behaviour only for an unexpected NULL `derived_status` or a missing joined row
+-- (the LEFT JOIN yielding no `t` row) — it does NOT protect against the `plans__tracking` VIEW being
+-- absent, which would fail this VIEW's query at read time.
+--
+-- A merged view is not editable in place (that would edit a shipped migration), so this DROPs and
+-- re-CREATEs it. `plan_read_model` is a leaf — no other view builds on it — so the DROP is safe. Its
+-- output column set is UNCHANGED (only the SOURCE of `status`/`list_bucket`/`ack_open` moved from the
+-- base column to the derived VIEW), so the pages↔schema contract guard and every page binding stay
+-- valid.
+--
+-- Forward-only. NO BEGIN/COMMIT — the runner wraps each file in its own transaction. Numbered after 078.
+
+DROP VIEW plan_read_model;
+
+CREATE VIEW plan_read_model AS
+SELECT
+  pl.plan_key AS plan_key,
+  pl.repo AS repo,
+  pl.issue_number AS issue_number,
+  pl.issue_url AS issue_url,
+  pl.title AS title,
+  COALESCE(t.derived_status, pl.status) AS status,
+  pl.task_count AS task_count,
+  pl.process_key AS process_key,
+  pl.outcome AS outcome,
+  pl.updated_at AS updated_at,
+  pl.epic_phase AS epic_phase,
+  pl.base_branch AS base_branch,
+  pl.wait_gate_label AS wait_gate_label,
+  pl.bound_artifacts AS bound_artifacts,
+  pl.promotion_pr AS promotion_pr,
+  pl.promotion_state AS promotion_state,
+  (CASE
+    WHEN COALESCE(t.derived_status, pl.status) IN ('planning', 'dispatched') THEN 'active'
+    WHEN COALESCE(t.derived_status, pl.status) = 'done' AND d.delivery = 'converging' THEN 'active'
+    WHEN COALESCE(t.derived_status, pl.status) = 'done' AND pl.acknowledged_at IS NULL THEN 'active'
+    WHEN COALESCE(t.derived_status, pl.status) = 'done' THEN 'history'
+    ELSE 'history'
+  END) AS list_bucket,
+  (CASE
+    WHEN COALESCE(t.derived_status, pl.status) = 'done' AND d.delivery IS NOT 'converging' AND pl.acknowledged_at IS NULL THEN 1
+    ELSE 0
+  END) AS ack_open,
+  wl.wave_count AS wave_count,
+  wl.current_wave AS current_wave,
+  wl.wave_label AS wave_label,
+  d.delivery AS delivery,
+  d.delivery_label AS delivery_label
+FROM plans pl
+LEFT JOIN plans__tracking t ON t.plan_key = pl.plan_key
+LEFT JOIN plan_wave_label wl ON wl.plan_key = pl.plan_key
+LEFT JOIN plan_delivery d ON d.plan_key = pl.plan_key;

package/db/migrations/081_feature_read_model_derive_terminal.sql

@@ -0,0 +1,65 @@
+-- Feature-run read model: fold the ADR-0065 DERIVED terminal edge into the projection (issue #503 —
+-- the feature_runs row of the "migrate remaining terminal-edge readers to derived_status" class).
+--
+-- Since ADR-0065 (`@nanobpm/urban@0.81.0`) the `instanceTracking` reconciler is a SOURCE, not a writer:
+-- on cancel/terminate it feeds urban's instance projection and the terminal edge (`onTerminated →
+-- abandoned`) is RECOMPUTED ON READ as `feature_runs__tracking.derived_status` — it NO LONGER writes
+-- `abandoned` onto the base `feature_runs.status` column. `feature_runs` had NO derived reader, so a
+-- terminated feature run's base row stayed frozen at `running`/`escalated`/`awaiting_operator` and
+-- 076's `feature_read_model` rendered it "Implementing" (never "failed") on the Feature history grid
+-- forever.
+--
+-- 076_feature_read_model_declare_once.sql authored the projection ONCE (`defineReadModel`,
+-- app/featureReadModel.ts) and emitted each derived column VERBATIM from that declaration; it read the
+-- base `feature_runs.status`. This migration SUPERSEDES 076's VIEW body: the declaration's `baseTable`
+-- is now the auto-provisioned `feature_runs__tracking` derived VIEW (which re-exports `feature_runs.*`
+-- plus a terminal-folded `derived_status`), and every status-classifying derived column below reads
+-- `fr."derived_status"` instead of `fr."status"`. So a cancelled/terminated run renders `Done`/`failed`
+-- with no worker write. 076 is a MERGED, IMMUTABLE migration — never edited; this is a NEW migration
+-- superseding its VIEW body (the same pattern by which 076 superseded 073/075).
+--
+-- Every DERIVED column body is emitted VERBATIM from the ONE declaration
+-- (`featureReadModel.sqlSelectFor(col, { baseAlias: "fr" })`), which ALSO drives the runtime TS via
+-- `fnFor` — the two lowerings fall out of the same closed-DSL AST and cannot diverge. The drift guard
+-- (app/featureReadModel.test.ts) fails if this file stops matching the declaration, and
+-- `assertReadModelParity` proves the SQL and TS lowerings agree. SEMANTICS are unchanged from 076 EXCEPT
+-- the status source (base transient → terminal-folded `derived_status`): `attention` still derives from
+-- ENGINE TRUTH (an OPEN `user_tasks` row, issue #422); `stage_skipped` is still a pure function of
+-- `converge`/`auto_merge`.
+--
+-- `feature_runs__tracking` is the managed VIEW urban provisions at mount (`<table>__tracking`); SQLite
+-- does not validate a view body at CREATE time, so this migration (which runs before the runtime mount
+-- that provisions the managed VIEW) is created fine and resolves once the managed VIEW exists. Base
+-- columns stay aliased pass-throughs (so the static pages↔schema contract guard still sees the VIEW
+-- columns), now sourced off `feature_runs__tracking`'s re-export of `base.*`; `feature_runs__tracking fr`
+-- is the sole top-level FROM (the user_tasks lookups are nested EXISTS subqueries at paren depth >= 1).
+--
+-- Forward-only VIEW redefinition (DROP then CREATE). The runner wraps each file in its own transaction,
+-- so this file must NOT contain BEGIN/COMMIT. Numbered after 079.
+
+DROP VIEW IF EXISTS feature_read_model;
+
+CREATE VIEW feature_read_model AS
+SELECT
+  fr.feature_key AS feature_key,
+  fr.repo AS repo,
+  fr.issue_number AS issue_number,
+  fr.issue_url AS issue_url,
+  fr.title AS title,
+  fr.base_branch AS base_branch,
+  fr.status AS status,
+  fr.process_key AS process_key,
+  fr.pr_key AS pr_key,
+  fr.converge AS converge,
+  fr.auto_merge AS auto_merge,
+  fr.outcome AS outcome,
+  fr.delivery_label AS delivery_label,
+  fr.acknowledged_at AS acknowledged_at,
+  fr.created_at AS created_at,
+  fr.updated_at AS updated_at,
+  CASE WHEN COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) THEN 'Done' WHEN COALESCE(("fr"."derived_status" = 'converging'), 0) THEN 'Converging' WHEN COALESCE((COALESCE(("fr"."pr_key" <> ''), 0) OR COALESCE(("fr"."derived_status" = 'opened'), 0)), 0) THEN 'PR open' WHEN COALESCE((COALESCE(("fr"."derived_status" = 'running'), 0) OR COALESCE(("fr"."derived_status" = 'escalated'), 0) OR COALESCE(("fr"."derived_status" = 'awaiting_operator'), 0)), 0) THEN 'Implementing' ELSE 'Requested' END AS stage,
+  CASE WHEN COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0)), 0) THEN 'ok' WHEN COALESCE(("fr"."derived_status" = 'blocked'), 0) THEN 'blocked' WHEN COALESCE((COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) THEN 'failed' ELSE NULL END AS stage_state,
+  CASE WHEN (NOT COALESCE("fr"."converge", 0)) THEN 'Converging Merging' WHEN (NOT COALESCE("fr"."auto_merge", 0)) THEN 'Merging' ELSE '' END AS stage_skipped,
+  CASE WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-blocked'), 0)), 0)) THEN 'blocked' WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-escalation'), 0)), 0)) THEN '⚠' ELSE NULL END AS attention,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) AND COALESCE(("fr"."acknowledged_at" = "fr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket
+FROM feature_runs__tracking fr;

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/operations/listActivePrs.test.ts

@@ -5,6 +5,7 @@ import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
 import { noopLog } from "../test/log.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import handler from "./listActivePrs.ts";
 
 function memApp(rows: any[], escalations: any[] = []): AppApi {
@@ -24,7 +25,7 @@ function memApp(rows: any[], escalations: any[] = []): AppApi {
       },
     };
   };
-  return { data: { table }, log: noopLog() } as any as AppApi;
+  return { data: { table: withTrackingViews(table) }, log: noopLog() } as any as AppApi;
 }
 
 function input(headers: Record<string, string> = {}) {

package/operations/startEpicSet.admission.integration.test.ts

@@ -18,6 +18,7 @@ import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
 import { resetDefaultBranchCache } from "../app/github.ts";
 import { noopLog } from "../test/log.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import startEpicSet from "./startEpicSet.ts";
 
 // ── in-memory github model (mirrors startPlanFanout.admission.integration.test.ts) ───────────────
@@ -116,7 +117,7 @@ function makeApp(seedPlans: Record<string, unknown>[] = []) {
     };
   };
   const app = {
-    data: { table },
+    data: { table: withTrackingViews(table) },
     engine: {
       createInstance: (req: { processDefinitionId: string; variables?: Record<string, unknown> }) => {
         started.push(req);
@@ -526,7 +527,7 @@ function makeSqliteApp(
     delete: () => Promise.resolve(),
   });
   const app = {
-    data: { table },
+    data: { table: withTrackingViews(table) },
     engine: { createInstance: () => Promise.resolve({ processInstanceKey: "PI-1" }) },
     log: noopLog(),
   } as any as AppApi;

package/operations/startPlanFanout.admission.integration.test.ts

@@ -9,6 +9,7 @@ import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
 import { resetDefaultBranchCache } from "../app/github.ts";
 import { noopLog } from "../test/log.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import startPlanFanout from "./startPlanFanout.ts";
 
 // ── in-memory github model ───────────────────────────────────────────────────
@@ -112,7 +113,7 @@ function makeApp(seedPlans: Record<string, unknown>[] = []) {
     };
   };
   const app = {
-    data: { table },
+    data: { table: withTrackingViews(table) },
     engine: {
       createInstance: (req: { processDefinitionId: string; variables?: Record<string, unknown> }) => {
         started.push(req);

package/package.json

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

@@ -30,7 +30,17 @@ export function withTrackingViews<F extends TableFn>(base: F): F {
     const statusField = baseStatusFieldFor(baseName);
     // biome-ignore lint/suspicious/noExplicitAny: test-only projection over dynamic row shapes.
     const project = (row: any) =>
-      row == null ? row : { ...row, [derivedColumn]: row[statusField] };
+      row == null
+        ? row
+        : // Honor an explicitly-seeded `derived_status` so a test can model the ADR-0065 divergence a
+          // real terminated instance produces — the base `<statusField>` frozen at its last transient
+          // while the derive edge reports the terminal (`abandoned`/`failed`/`reviewed`). When a row
+          // seeds no derived column the VIEW's `ELSE base.<statusField>` fall-through applies, so it
+          // stays byte-for-byte the pass-through the previous behaviour modelled.
+          {
+            ...row,
+            [derivedColumn]: row[derivedColumn] ?? row[statusField],
+          };
     // biome-ignore lint/suspicious/noExplicitAny: test-only Proxy over a dynamic DataLayer table.
     return new Proxy(inner, {
       get(target: any, prop: string) {

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");
+  });
+});