@nanobpm/nano-workforce 0.131.1 → 0.133.0

package/app/migration079.test.ts

@@ -0,0 +1,153 @@
+// Read-model guard for migration 079's extended `lineage_thread_view` VIEW (issue #498: surface
+// delivery-graph runs in the Lineage tab as a fan-in parent thread). Mirrors app/migration064.test.ts:
+// apply the migration to a real in-memory SQLite DB and assert the VIEW's output over sample rows —
+// so this exercises the real view, not a re-implementation.
+//
+// The extended view adds a third origin arm: a root that matches a `delivery_graph_runs.run_key`
+// derives `kind = 'delivery'`, `title` from the run, and a NULL `issue_url` (a run is keyed by
+// run_key/digest, not a GitHub issue). The epic/feature/pr arms must keep behaving exactly as 064's
+// view did (precedence unchanged).
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals } from "#test-assert";
+
+const MIGRATION_064 = fileURLToPath(new URL("../db/migrations/064_lineage_thread_view.sql", import.meta.url));
+const MIGRATION_079 = fileURLToPath(
+  new URL("../db/migrations/079_lineage_thread_view_delivery.sql", import.meta.url),
+);
+
+/** A DB with the base shapes the view reads (`lineage_threads`, `plans`, `feature_runs`,
+ *  `delivery_graph_runs`) plus 064 then 079 applied in order — so this exercises the real DROP VIEW +
+ *  re-CREATE the migration performs, not just the final definition. */
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE lineage_threads (
+       root_request_key TEXT PRIMARY KEY, title TEXT, stage TEXT,
+       stage_label TEXT, process_key TEXT, pr_keys TEXT, pr_count INTEGER, active INTEGER,
+       created_at TEXT, updated_at TEXT);
+     CREATE TABLE plans (plan_key TEXT PRIMARY KEY, title TEXT, issue_url TEXT);
+     CREATE TABLE feature_runs (feature_key TEXT PRIMARY KEY, title TEXT, issue_url TEXT);
+     CREATE TABLE delivery_graph_runs (run_key TEXT PRIMARY KEY, title TEXT, phase TEXT, status TEXT);`,
+  );
+  db.exec(readFileSync(MIGRATION_064, "utf8"));
+  db.exec(readFileSync(MIGRATION_079, "utf8"));
+  return db;
+}
+
+/** Insert a `lineage_threads` row exactly as `pollLineage` denormalises one (post-072 schema — no
+ *  `kind`/`issue_url` columns; the view derives both from the origin joins). */
+function addThread(
+  db: DatabaseSync,
+  row: {
+    root_request_key: string;
+    title: string | null;
+    stage: string;
+    stage_label: string | null;
+    process_key: string | null;
+    pr_keys: string | null;
+    pr_count: number;
+    active: number;
+  },
+): void {
+  db.prepare(
+    `INSERT INTO lineage_threads (root_request_key, title, stage, stage_label,
+       process_key, pr_keys, pr_count, active, created_at, updated_at)
+     VALUES (@root_request_key, @title, @stage, @stage_label, @process_key,
+       @pr_keys, @pr_count, @active, 't0', 't1')`,
+  ).run(row);
+}
+
+test("lineage_thread_view derives kind/title/NULL issue_url for a delivery-graph thread from the run origin", () => {
+  const db = viewDb();
+  db.prepare(
+    "INSERT INTO delivery_graph_runs (run_key, title, phase, status) VALUES (?, ?, ?, ?)",
+  ).run("dg-abc123", "Ship widget across repos", "Parked on human node: manual OTP publish", "running");
+  // pollLineage wrote the fan-in run's procedural frontier onto lineage_threads, keyed on run_key.
+  addThread(db, {
+    root_request_key: "dg-abc123",
+    title: "Ship widget across repos",
+    stage: "converging",
+    stage_label: "Parked on human node: manual OTP publish",
+    process_key: "P-dg",
+    pr_keys: '["a/b#1","c/d#9"]',
+    pr_count: 2,
+    active: 1,
+  });
+
+  const v = db
+    .prepare("SELECT * FROM lineage_thread_view WHERE root_request_key = ?")
+    .get("dg-abc123") as Record<string, unknown>;
+  // Derived from the delivery_graph_runs join.
+  assertEquals(v.kind, "delivery");
+  assertEquals(v.title, "Ship widget across repos");
+  // A run is keyed by run_key/digest, not a GitHub issue — issue_url is always NULL.
+  assertEquals(v.issue_url, null);
+  // Procedural frontier columns pass through unchanged from lineage_threads (the run's derived phase).
+  assertEquals(v.stage, "converging");
+  assertEquals(v.stage_label, "Parked on human node: manual OTP publish");
+  assertEquals(v.process_key, "P-dg");
+  assertEquals(v.pr_keys, '["a/b#1","c/d#9"]');
+  assertEquals(v.pr_count, 2);
+  assertEquals(v.active, 1);
+});
+
+test("lineage_thread_view renders a delivery thread with no PR landed yet (empty member set, run phase)", () => {
+  const db = viewDb();
+  db.prepare(
+    "INSERT INTO delivery_graph_runs (run_key, title, phase, status) VALUES (?, ?, ?, ?)",
+  ).run("dg-empty", "Fresh run", "Running", "running");
+  addThread(db, {
+    root_request_key: "dg-empty",
+    title: "Fresh run",
+    stage: "implementing",
+    stage_label: "Running",
+    process_key: "P-e",
+    pr_keys: "[]",
+    pr_count: 0,
+    active: 1,
+  });
+
+  const v = db
+    .prepare("SELECT kind, title, issue_url, stage_label, pr_count FROM lineage_thread_view WHERE root_request_key = ?")
+    .get("dg-empty") as Record<string, unknown>;
+  assertEquals(v.kind, "delivery");
+  assertEquals(v.title, "Fresh run");
+  assertEquals(v.issue_url, null);
+  assertEquals(v.stage_label, "Running");
+  assertEquals(v.pr_count, 0);
+});
+
+test("lineage_thread_view keeps the epic/feature/pr arms unchanged after the delivery arm is added", () => {
+  const db = viewDb();
+  db.prepare("INSERT INTO plans (plan_key, title, issue_url) VALUES ('o/r#2', 'Epic', 'u-epic')").run();
+  db.prepare("INSERT INTO feature_runs (feature_key, title, issue_url) VALUES ('o/r#1', 'Feat', 'u-feat')").run();
+  const rows = [
+    { root_request_key: "o/r#2", kind: "epic", title: "Epic", issue_url: "u-epic" },
+    { root_request_key: "o/r#1", kind: "feature", title: "Feat", issue_url: "u-feat" },
+    { root_request_key: "o/r#30", kind: "pr", title: "PR", issue_url: null },
+  ];
+  for (const r of rows) {
+    addThread(db, {
+      root_request_key: r.root_request_key,
+      title: r.title,
+      stage: "opened",
+      stage_label: "Opened",
+      process_key: null,
+      pr_keys: "[]",
+      pr_count: 1,
+      active: 1,
+    });
+  }
+
+  for (const r of rows) {
+    const v = db
+      .prepare("SELECT kind, title, issue_url FROM lineage_thread_view WHERE root_request_key = ?")
+      .get(r.root_request_key) as Record<string, unknown>;
+    assertEquals(v.kind, r.kind);
+    assertEquals(v.title, r.title);
+    assertEquals(v.issue_url, r.issue_url);
+  }
+});

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/db/migrations/079_lineage_thread_view_delivery.sql

@@ -0,0 +1,65 @@
+-- Surface delivery-graph runs in the Lineage read model (issue #498: "surface dynamic delivery
+-- graphs in the Lineage tab as a fan-in parent thread").
+--
+-- 064_lineage_thread_view.sql created `lineage_thread_view`, deriving a thread's view-expressible
+-- identity columns (`kind`, `title`, `issue_url`) from the `plans` / `feature_runs` origin joins and
+-- passing the procedural frontier columns through from `lineage_threads`. It matched a root against
+-- exactly two origin tables (else a self-rooted `'pr'`), so a delivery-graph run — a SEPARATE
+-- aggregate (`delivery_graph_runs`, keyed by `run_key`) — was structurally invisible: its thread fell
+-- through to `'pr'` with a NULL title.
+--
+-- `collectThreads` (app/lineage.ts) now enumerates `delivery_graph_runs` as a fan-in parent thread
+-- keyed on `run_key`, so `pollLineage` writes a `lineage_threads` row for each run. Extend the view
+-- with a third origin arm so it derives that row's identity from the run:
+--   • `kind`      — 'delivery' when the root matches a `delivery_graph_runs.run_key` (after the
+--                   epic/feature arms, mirroring the precedence in `collectThreads` / `deriveLineage`).
+--   • `title`     — the run's `title` (its authored delivery-graph title).
+--   • `issue_url` — NULL: a delivery-graph run is keyed by `run_key`/`digest`, not a GitHub issue,
+--                   exactly as `deriveLineage` sets it (only feature/epic threads root on an issue).
+-- The procedural frontier columns (`stage`/`stage_label`/`process_key`/`pr_keys`/`pr_count`/`active`)
+-- still pass through from `lineage_threads`, so a delivery thread's frontier reflects the run's
+-- derived phase that `pollLineage` wrote.
+--
+-- A VIEW cannot be `ALTER`ed, so DROP the old definition and CREATE the extended one. This is a NEW
+-- forward-only migration — 064 stays immutable. The view remains a plain `CREATE VIEW <name> AS
+-- SELECT … FROM …` (no CTE, no select-list subquery, every column aliased) so the static
+-- pages↔schema contract guard can still introspect its output columns; the added CASE arm and LEFT
+-- JOIN keep the SAME output column set, so the repointed Lineage page renders identically.
+--
+-- Forward-only, additive: no schema change to any base table, no DROP of `lineage_threads`. The
+-- runner wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+DROP VIEW IF EXISTS lineage_thread_view;
+
+CREATE VIEW lineage_thread_view AS
+SELECT
+  lt.root_request_key AS root_request_key,
+  CASE
+    WHEN pl.plan_key IS NOT NULL THEN 'epic'
+    WHEN fr.feature_key IS NOT NULL THEN 'feature'
+    WHEN dg.run_key IS NOT NULL THEN 'delivery'
+    ELSE 'pr'
+  END AS kind,
+  CASE
+    WHEN pl.plan_key IS NOT NULL THEN pl.title
+    WHEN fr.feature_key IS NOT NULL THEN fr.title
+    WHEN dg.run_key IS NOT NULL THEN dg.title
+    ELSE lt.title
+  END AS title,
+  CASE
+    WHEN pl.plan_key IS NOT NULL THEN pl.issue_url
+    WHEN fr.feature_key IS NOT NULL THEN fr.issue_url
+    ELSE NULL
+  END AS issue_url,
+  lt.stage AS stage,
+  lt.stage_label AS stage_label,
+  lt.process_key AS process_key,
+  lt.pr_keys AS pr_keys,
+  lt.pr_count AS pr_count,
+  lt.active AS active,
+  lt.created_at AS created_at,
+  lt.updated_at AS updated_at
+FROM lineage_threads lt
+LEFT JOIN plans pl ON pl.plan_key = lt.root_request_key
+LEFT JOIN feature_runs fr ON fr.feature_key = lt.root_request_key
+LEFT JOIN delivery_graph_runs dg ON dg.run_key = lt.root_request_key;

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

@@ -148,10 +148,10 @@ components:
       properties:
         rootRequestKey:
           type: string
-          description: The origin issue key (feature_key/plan_key), or a self-rooted pr_key.
+          description: The origin issue key (feature_key/plan_key), a self-rooted pr_key, or a delivery-graph run_key.
         kind:
           type: string
-          enum: [feature, epic, pr]
+          enum: [feature, epic, pr, delivery]
         title:
           type: string
           nullable: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.131.1",
+  "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/pages/lineage.page.json

@@ -70,7 +70,7 @@
       "type": "text",
       "id": "subtitle",
       "props": {
-        "text": "One narrative per request, not a card-swap. Each row is a single arc of your intent \u2014 request \u2192 implementing \u2192 PR opened \u2192 converging (round n) \u2192 merged/converged/abandoned \u2014 stitched from the feature/epic that started it, the PR(s) it produced, and their convergence + merge outcome. The Stage column is the active frontier; drill into a row for its member PR(s) and rounds. Epics fan out to N PR sub-threads. A human/webhook PR with no originating request is shown as its own root.",
+        "text": "One narrative per request, not a card-swap. Each row is a single arc of your intent \u2014 request \u2192 implementing \u2192 PR opened \u2192 converging (round n) \u2192 merged/converged/abandoned \u2014 stitched from the feature/epic that started it, the PR(s) it produced, and their convergence + merge outcome. The Stage column is the active frontier; drill into a row for its member PR(s) and rounds. Epics fan out to N PR sub-threads. A delivery-graph run is a fan-in parent thread: the heterogeneous downstream PR convergences it spawns (across different repos/issues) nest under the run, whose frontier reflects its derived phase. A human/webhook PR with no originating request is shown as its own root.",
         "variant": "sub"
       }
     },