@nanobpm/nano-workforce 0.210.1 → 0.211.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.211.0](https://github.com/nanobpm/nano-workforce/compare/v0.210.2...v0.211.0) (2026-11-14)
+
+### Features
+
+* **openapi:** add x-cli command projection to every operation ([#963](https://github.com/nanobpm/nano-workforce/issues/963)) ([4ba5c8c](https://github.com/nanobpm/nano-workforce/commit/4ba5c8c61e6d5bfceaff3883c1719795797eb9a4)), closes [#961](https://github.com/nanobpm/nano-workforce/issues/961) [#961](https://github.com/nanobpm/nano-workforce/issues/961)
+
+## [0.210.2](https://github.com/nanobpm/nano-workforce/compare/v0.210.1...v0.210.2) (2026-11-14)
+
+### Bug Fixes
+
+* **tracking:** merged PRs no longer derive 'abandoned' when their run was terminated ([#960](https://github.com/nanobpm/nano-workforce/issues/960)) ([56f0ff4](https://github.com/nanobpm/nano-workforce/commit/56f0ff4c4a3a0d8a3cf68745b1f7b9bf539987da)), closes [nano-bpm#1579](https://github.com/nanobpm/nano-bpm/issues/1579) [#959](https://github.com/nanobpm/nano-workforce/issues/959)
+
 ## [0.210.1](https://github.com/nanobpm/nano-workforce/compare/v0.210.0...v0.210.1) (2026-11-12)
 
 ### Bug Fixes

package/app/abandon.test.ts

@@ -134,6 +134,37 @@ test("abandonStatusForToken derives abandoned from the row status", async () =>
   assertEquals(await abandonStatusForToken(data, "nope"), undefined);
 });
 
+test("abandonStatusForToken aborts a MERGED PR whose owning run was terminated (owner_terminated)", async () => {
+  // derived_status reports a landed PR as `merged` even when its run was terminated (#959), so the
+  // cancellation signal rides the separate owner_terminated column — terminating a redundant
+  // post-merge round must still tell its agent to stop.
+  const data = memData();
+  await data.table("pull_requests", "pr_key").insert({
+    pr_key: "o/r#4",
+    abandon_token: "landed-term",
+    status: "merged",
+    merged_at: "t",
+    owner_terminated: 1,
+  });
+  await data.table("pull_requests", "pr_key").insert({
+    pr_key: "o/r#5",
+    abandon_token: "landed-live",
+    status: "merged",
+    merged_at: "t",
+    owner_terminated: null,
+  });
+  assertEquals(await abandonStatusForToken(data, "landed-term"), {
+    prKey: "o/r#4",
+    status: "merged",
+    abandoned: true,
+  });
+  assertEquals(await abandonStatusForToken(data, "landed-live"), {
+    prKey: "o/r#5",
+    status: "merged",
+    abandoned: false,
+  });
+});
+
 test("abandonStatusForToken fails CLOSED on a non-string derived status", async () => {
   // A malformed/missing derived_status must never be reported as `abandoned:false`
   // (that would let a cancelled run proceed with irreversible side effects). It throws

package/app/abandon.ts

@@ -24,12 +24,15 @@
 import type { DataLayer } from "@nanobpm/urban";
 import { publicBaseUrl } from "./blackboard.ts";
 import { trackingTargetFor } from "./instanceTracking.ts";
+import { OWNER_TERMINATED_COLUMN } from "./prTrackingReadModel.ts";
 
 /** The one derived-status value meaning a PR is terminally abandoned — the run must not be worked on
  * further. Two disjoint producers surface a row here, and both are non-completion terminals that must
  * stop a servicing agent:
  *   1. an explicit **cancel** of a live convergence/merge run (Urban's cancel primitive terminates
- *      the instance; the `instanceTracking` `onTerminated.set` edge derives `abandoned` on read), and
+ *      the instance; the `instanceTracking` `onTerminated.set` edge derives `abandoned` on read) —
+ *      but ONLY when the PR did NOT land: the merge-aware derivation (app/prTrackingReadModel.ts,
+ *      issue #959) folds a terminated-but-MERGED PR to `merged`, never `abandoned`, and
  *   2. **`abandonClosedPr`** reconciling a wave-member PR that was **closed on GitHub without
  *      merging** (#352) — for both `pull_requests` and its `plan_tasks` — by writing the base row.
  * Convergence/merge terminal states `converged`/`merged` are NOT abandonment. In either abandoned
@@ -116,7 +119,10 @@ export async function abandonStatusForToken(
     );
   }
   const status = rawStatus;
-  return { prKey: row.pr_key, status, abandoned: isAbandoned(status) };
+  // `derived_status` reports a landed PR as `merged` even when its run was terminated (issue #959),
+  // so termination is read from its own column: a terminated owner ALWAYS aborts the agent.
+  const ownerTerminated = Boolean(row[OWNER_TERMINATED_COLUMN]);
+  return { prKey: row.pr_key, status, abandoned: isAbandoned(status) || ownerTerminated };
 }
 
 /** The instruction block appended (verbatim, via `appendPrompt`) to each side-effecting agent's

package/app/cliExtension.test.ts

@@ -0,0 +1,40 @@
+// Authoring guard for the `x-cli` CLI command-projection extension (issue #961, nano-ide#617).
+//
+// `d8ctl nwf …` projects every `openapi.yaml` operation into a CLI command from its `x-cli`. The
+// spec is parsed by the SAME `@nanobpm/urban` walker the runtime uses (`parseSpec` +
+// `collectOperations`), which validates `x-cli` (unknown keys, kebab-case words, duplicate command
+// paths) and exposes it as `op.cli` — no second parser to drift from it.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { collectOperations, parseSpec } from "@nanobpm/urban/toolkit";
+import { assert } from "#test-assert";
+
+const SPEC_PATH = join(dirname(dirname(fileURLToPath(import.meta.url))), "openapi.yaml");
+const ops = () => collectOperations(parseSpec(readFileSync(SPEC_PATH, "utf8")));
+
+test("every operation declares x-cli (a deliberate command or an explicit exclude)", () => {
+  const missing = ops().filter((op) => op.cli === undefined).map((op) => op.operationId);
+  assert(missing.length === 0, `operations without x-cli: ${missing.join(", ")}`);
+});
+
+test("every x-mcp-excluded operation is operator-audience or CLI-excluded", () => {
+  const leaked = ops()
+    .filter((op) => op.mcpExcluded && !(op.cli?.exclude === true || op.cli?.audience === "operator"))
+    .map((op) => op.operationId);
+  assert(leaked.length === 0, `x-mcp-excluded but CLI-visible to agents: ${leaked.join(", ")}`);
+});
+
+test("the /hooks/* side channels are excluded from the CLI", () => {
+  const hooks = ops().filter((op) => op.path.startsWith("/hooks/"));
+  assert(hooks.length > 0, "expected /hooks/* operations");
+  const exposed = hooks.filter((op) => op.cli?.exclude !== true).map((op) => op.operationId);
+  assert(exposed.length === 0, `hook side channels exposed as CLI commands: ${exposed.join(", ")}`);
+});
+
+test("dispatchDeliveryGraph is an operator-audience command", () => {
+  const op = ops().find((o) => o.operationId === "dispatchDeliveryGraph");
+  assert(op?.cli?.audience === "operator", "dispatchDeliveryGraph must be audience: operator");
+  assert(op?.cli?.command.join(" ") === "graph dispatch", "dispatchDeliveryGraph command");
+});

package/app/conformance.test.ts

@@ -126,6 +126,23 @@ test("hasDeliveredImplementation: true iff at least one PR landed", async () =>
   assert(hasDeliveredImplementation(await gatherConformance(data, PLAN)));
 });
 
+// Issue #959: a PR that MERGED but whose loop was terminated afterwards (operator cancel, out-of-band
+// merge reconcile, restart cleanup) derived `abandoned` off the `onTerminated` edge — and conformance
+// then refused to count it as landed. The merge-aware derivation folds it to `merged` (merged_at set),
+// so a merged-then-terminated PR IS landed. Model the terminated divergence by seeding the base row at
+// its frozen transient (`converging`) WITH `merged_at` set: the tracking view must report `merged`.
+test("hasDeliveredImplementation: a merged-then-terminated PR (frozen base + merged_at) counts as landed (#959)", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 0, task_id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  // Base status frozen at the in-flight transient, but the PR landed (merged_at set) before termination.
+  stores["pull_requests"] = [{ pr_key: "acme/widgets#10", status: "converging", merged_at: "2026-11-01T00:00:00Z" }];
+  assertEquals(await hasDeliveredImplementationForPlan(data, PLAN), true);
+  const d = await gatherConformance(data, PLAN);
+  assertEquals(hasDeliveredImplementation(d), true);
+  assertEquals(d.slices.find((s) => s.taskId === "t1")?.landed, true);
+});
+
 test("hasDeliveredImplementationForPlan: matches the digest without a blackboard scan", async () => {
   const { data, stores } = memData();
   seedPlan(stores);

package/app/loopTermination.test.ts

@@ -410,3 +410,7 @@ test("PR#944 round 6: a successor-owned converging row is NEVER demoted by a red
   assertEquals(stores.pull_requests[0].process_key, "succ");
   assertEquals(stores.pull_requests[0].retire_pending_key, "merge-1", "the pending retirement is left for retryPendingRetirements");
 });
+
+test("#959 isOrphanedPr: an audit-only landing (derived merged, base merging, no merged_at) is never orphaned", () => {
+  assert(!isOrphanedPr({ status: "merging", derived_status: "merged", termination_reason: null, merged_at: null }));
+});

package/app/migration139.test.ts

@@ -0,0 +1,115 @@
+// Migration guard for 139_pull_requests_backfill_merged_not_abandoned.sql (issue #959): the backfill
+// that re-derives the 23 merged-but-terminated PRs so they show as `merged`, not `abandoned`.
+//
+// Applies the migration to a real in-memory SQLite DB over a pre-existing `pull_requests` + `merges`
+// shape and asserts the contract:
+//   * a row with a `merged` audit outcome but a non-`merged` base status (the loop terminated before
+//     `merged_at` was stamped) is settled to `status='merged'` + `merged_at` — so the merge-aware
+//     derivation reports `merged` however the instance ended;
+//   * a row already settled `merged` is left untouched (idempotent);
+//   * a row with NO `merged` audit outcome (a genuinely abandoned/closed-unmerged run) is NOT
+//     flipped — it stays at its frozen transient so the derivation still reports `abandoned`;
+//   * re-running the migration is a no-op (forward-only, idempotent).
+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_139 = fileURLToPath(
+  new URL("../db/migrations/139_pull_requests_backfill_merged_not_abandoned.sql", import.meta.url),
+);
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE pull_requests (
+       pr_key TEXT PRIMARY KEY,
+       repo TEXT NOT NULL,
+       number INTEGER NOT NULL,
+       status TEXT NOT NULL,
+       process_key TEXT,
+       merged_at TEXT,
+       updated_at TEXT
+     );
+     CREATE TABLE merges (
+       id INTEGER PRIMARY KEY AUTOINCREMENT,
+       pr_key TEXT NOT NULL,
+       outcome TEXT NOT NULL,
+       method TEXT,
+       detail TEXT,
+       at TEXT NOT NULL
+     );`,
+  );
+  return db;
+}
+
+function addPr(db: DatabaseSync, prKey: string, status: string, mergedAt: string | null = null): void {
+  db.prepare(
+    "INSERT INTO pull_requests (pr_key, repo, number, status, process_key, merged_at, updated_at) VALUES (?, 'o/r', 1, ?, 'PI-1', ?, 't0')",
+  ).run(prKey, status, mergedAt);
+}
+
+function addMerge(db: DatabaseSync, prKey: string, outcome: string, at: string): void {
+  db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES (?, ?, 'squash', 'd', ?)").run(prKey, outcome, at);
+}
+
+function row(db: DatabaseSync, prKey: string): { status: string; merged_at: string | null } {
+  return db.prepare("SELECT status, merged_at FROM pull_requests WHERE pr_key = ?").get(prKey) as {
+    status: string;
+    merged_at: string | null;
+  };
+}
+
+const SQL = () => readFileSync(MIGRATION_139, "utf8");
+
+test("139 backfills a merged-but-terminated PR (frozen transient + merged audit) to status='merged' + merged_at", () => {
+  const db = migratedDb();
+  // The #959 case: PR landed (merged audit row) but the loop was terminated before merged_at was set,
+  // leaving the base status frozen at its in-flight transient.
+  addPr(db, "o/r#landed", "converging", null);
+  addMerge(db, "o/r#landed", "merged", "2026-11-01T02:03:04Z");
+  db.exec(SQL());
+  const r = row(db, "o/r#landed");
+  assertEquals(r.status, "merged");
+  assertEquals(r.merged_at, "2026-11-01T02:03:04Z", "merged_at is stamped from the earliest merged audit row");
+  db.close();
+});
+
+test("139 leaves an already-merged row untouched (idempotent, never overwrites merged_at)", () => {
+  const db = migratedDb();
+  addPr(db, "o/r#already", "merged", "2026-10-30T00:00:00Z");
+  addMerge(db, "o/r#already", "merged", "2026-10-30T00:00:00Z");
+  db.exec(SQL());
+  const r = row(db, "o/r#already");
+  assertEquals(r.status, "merged");
+  assertEquals(r.merged_at, "2026-10-30T00:00:00Z");
+  db.close();
+});
+
+test("139 does NOT flip a closed-unmerged / genuinely-abandoned PR (no merged audit outcome)", () => {
+  const db = migratedDb();
+  // A PR closed without merging: terminated → abandoned, NO merged audit row. Must stay un-merged.
+  addPr(db, "o/r#closed", "converging", null);
+  addMerge(db, "o/r#closed", "abandoned", "2026-11-01T00:00:00Z");
+  // A still-in-flight PR with no merge record at all.
+  addPr(db, "o/r#inflight", "waiting_merge", null);
+  db.exec(SQL());
+  assertEquals(row(db, "o/r#closed").status, "converging", "no merged outcome → not flipped to merged");
+  assertEquals(row(db, "o/r#closed").merged_at, null);
+  assertEquals(row(db, "o/r#inflight").status, "waiting_merge");
+  assertEquals(row(db, "o/r#inflight").merged_at, null);
+  db.close();
+});
+
+test("139 is idempotent — a second run is a no-op", () => {
+  const db = migratedDb();
+  addPr(db, "o/r#landed", "waiting_merge", null);
+  addMerge(db, "o/r#landed", "merged", "2026-11-01T02:03:04Z");
+  db.exec(SQL());
+  const first = row(db, "o/r#landed");
+  db.exec(SQL());
+  const second = row(db, "o/r#landed");
+  assertEquals(second, first);
+  db.close();
+});

package/app/prTrackingReadModel.test.ts

@@ -0,0 +1,175 @@
+// Issue #959 — the canonical "merged beats terminated" effective-status derivation for a PR.
+//
+// THE DEFECT: `pull_requests__tracking.derived_status` mapped ANY terminated run to `abandoned`
+// without consulting the PR's merge state, so the 23 November PRs that MERGED but whose loops were
+// terminated afterwards (operator cancel, out-of-band merge reconcile, restart cleanup) all read
+// "abandoned". These tests pin the fixed semantics against the REAL derivation SQL
+// (`pullRequestTrackingReadModel`, app/prTrackingReadModel.ts) compiled to an in-memory SQLite VIEW
+// over the SAME canonical `urban_instance_state` projection the framework feeds:
+//
+//   terminated + merged PR          → `merged`     (landed wins over terminated)
+//   terminated + closed-unmerged PR → `abandoned`  (no merged_at → the onTerminated edge)
+//   terminated + open PR            → `abandoned`
+//   live (non-terminated) run       → base `status` passes through
+//
+// and the downstream consequence: conformance/retro count a merged-then-terminated PR as LANDED.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { registerCanonicalProjections, readModelRegistry } from "@nanobpm/urban";
+import { assert, assertEquals } from "#test-assert";
+import {
+  pullRequestTrackingReadModel,
+  registerPullRequestTrackingReadModel,
+} from "./prTrackingReadModel.ts";
+
+// The projection NAME→physical-table mapping the VIEW's `EXISTS` resolves through.
+registerCanonicalProjections();
+
+/** A minimal in-memory DB: the real `pull_requests` base columns the derivation reads (`status`,
+ *  `process_key`, `merged_at`), the canonical `_urban_instance_state` projection, and the
+ *  app-owned tracking VIEW compiled from the ONE declaration. */
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE pull_requests (pr_key TEXT PRIMARY KEY, status TEXT, process_key TEXT, merged_at TEXT);
+     CREATE TABLE merges (id INTEGER PRIMARY KEY, pr_key TEXT, outcome TEXT, method TEXT, detail TEXT, at TEXT);
+     CREATE TABLE _urban_instance_state (process_instance_key TEXT PRIMARY KEY, state TEXT, waiting_on_human INTEGER NOT NULL DEFAULT 0, updated_at TEXT);`,
+  );
+  db.exec(pullRequestTrackingReadModel.viewDdl());
+  return db;
+}
+
+function addPr(
+  db: DatabaseSync,
+  prKey: string,
+  opts: { status: string; processKey: string | null; mergedAt: string | null },
+): void {
+  db.prepare("INSERT INTO pull_requests (pr_key, status, process_key, merged_at) VALUES (?, ?, ?, ?)").run(
+    prKey,
+    opts.status,
+    opts.processKey,
+    opts.mergedAt,
+  );
+}
+
+function terminate(db: DatabaseSync, processKey: string): void {
+  db.prepare(
+    "INSERT INTO _urban_instance_state (process_instance_key, state, waiting_on_human, updated_at) VALUES (?, 'TERMINATED', 0, 't')",
+  ).run(processKey);
+}
+
+function derivedStatus(db: DatabaseSync, prKey: string): string {
+  const r = db.prepare("SELECT derived_status FROM pull_requests__tracking WHERE pr_key = ?").get(prKey) as {
+    derived_status: string;
+  };
+  return r.derived_status;
+}
+
+test("terminated instance + merged PR (merged_at set) derives `merged`, not `abandoned`", () => {
+  const db = viewDb();
+  // The #959 case: the loop was terminated AFTER the PR landed; base status frozen at its transient.
+  addPr(db, "o/r#merged", { status: "converging", processKey: "514213", mergedAt: "2026-11-01T00:00:00Z" });
+  terminate(db, "514213");
+  assertEquals(derivedStatus(db, "o/r#merged"), "merged");
+  db.close();
+});
+
+test("terminated instance + closed-unmerged PR (no merged_at) derives `abandoned`", () => {
+  const db = viewDb();
+  addPr(db, "o/r#closed", { status: "converging", processKey: "222", mergedAt: null });
+  terminate(db, "222");
+  assertEquals(derivedStatus(db, "o/r#closed"), "abandoned");
+  db.close();
+});
+
+test("terminated instance + open PR (no merged_at) derives `abandoned`", () => {
+  const db = viewDb();
+  addPr(db, "o/r#open", { status: "waiting_review", processKey: "333", mergedAt: null });
+  terminate(db, "333");
+  assertEquals(derivedStatus(db, "o/r#open"), "abandoned");
+  db.close();
+});
+
+test("a live (non-terminated) in-flight run passes its base status through unchanged", () => {
+  const db = viewDb();
+  addPr(db, "o/r#live", { status: "converging", processKey: "444", mergedAt: null });
+  db.prepare(
+    "INSERT INTO _urban_instance_state (process_instance_key, state, waiting_on_human, updated_at) VALUES ('444', 'ACTIVE', 0, 't')",
+  ).run();
+  assertEquals(derivedStatus(db, "o/r#live"), "converging");
+  db.close();
+});
+
+test("a merged PR whose instance COMPLETED normally (no terminated edge) reads base `merged`", () => {
+  const db = viewDb();
+  addPr(db, "o/r#done", { status: "merged", processKey: "555", mergedAt: "2026-11-01T00:00:00Z" });
+  db.prepare(
+    "INSERT INTO _urban_instance_state (process_instance_key, state, waiting_on_human, updated_at) VALUES ('555', 'COMPLETED', 0, 't')",
+  ).run();
+  assertEquals(derivedStatus(db, "o/r#done"), "merged");
+  db.close();
+});
+
+test("a landed PR with no instance-state row (null process_key) still derives merged off merged_at", () => {
+  const db = viewDb();
+  // merged_at set but the instance row is gone/null: the merged WHEN keys on merged_at, not the join.
+  addPr(db, "o/r#nullkey", { status: "converging", processKey: null, mergedAt: "2026-11-01T00:00:00Z" });
+  assertEquals(derivedStatus(db, "o/r#nullkey"), "merged");
+  db.close();
+});
+
+test("a landed PR whose instance-state row was pruned still derives merged off merged_at", () => {
+  const db = viewDb();
+  addPr(db, "o/r#pruned", { status: "waiting_merge", processKey: "777", mergedAt: "2026-11-01T00:00:00Z" });
+  assertEquals(derivedStatus(db, "o/r#pruned"), "merged");
+  db.close();
+});
+
+test("a run terminated between pr.merge's audit and pr.mark-merged (merged_at NULL) derives merged", () => {
+  const db = viewDb();
+  addPr(db, "o/r#gap", { status: "merging", processKey: "888", mergedAt: null });
+  db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES ('o/r#gap', 'merged', 'squash', '', 't')").run();
+  terminate(db, "888");
+  assertEquals(derivedStatus(db, "o/r#gap"), "merged");
+  db.close();
+});
+
+test("a non-merged audit outcome does not fold a terminated run to merged", () => {
+  const db = viewDb();
+  addPr(db, "o/r#rc", { status: "merging", processKey: "889", mergedAt: null });
+  db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES ('o/r#rc', 'reconverge', 'x', '', 't')").run();
+  terminate(db, "889");
+  assertEquals(derivedStatus(db, "o/r#rc"), "abandoned");
+  db.close();
+});
+
+test("owner_terminated exposes termination separately: set for a terminated merged PR, NULL for a live one", () => {
+  const db = viewDb();
+  addPr(db, "o/r#mt", { status: "merged", processKey: "901", mergedAt: "t" });
+  terminate(db, "901");
+  addPr(db, "o/r#ml", { status: "merged", processKey: "902", mergedAt: "t" });
+  const get = (k: string) =>
+    (db.prepare("SELECT derived_status, owner_terminated FROM pull_requests__tracking WHERE pr_key = ?").get(k) as {
+      derived_status: string;
+      owner_terminated: number | null;
+    });
+  assertEquals(get("o/r#mt").derived_status, "merged");
+  assertEquals(get("o/r#mt").owner_terminated, 1);
+  assertEquals(get("o/r#ml").owner_terminated, null);
+  db.close();
+});
+
+// The whole fix hinges on the app-owned model claiming the EXACT view name urban's provisioner would
+// otherwise manage, so the framework defers to it. Pin that contract: the model is named
+// `pull_requests__tracking`, registers into the process-wide registry (idempotently), and the
+// registration is what `main.ts` invokes before `runFromEnv`.
+test("the app-owned model is named pull_requests__tracking and registers idempotently", () => {
+  assertEquals(pullRequestTrackingReadModel.decl.name, "pull_requests__tracking");
+  assertEquals(pullRequestTrackingReadModel.decl.baseTable, "pull_requests");
+  registerPullRequestTrackingReadModel();
+  const registered = readModelRegistry.get("pull_requests__tracking");
+  assert(registered, "the model must be registered so the framework defers to it");
+  assertEquals(registered.decl.name, "pull_requests__tracking");
+  // Idempotent: re-registering the identical definition is a no-op (never throws).
+  registerPullRequestTrackingReadModel();
+});

package/app/prTrackingReadModel.ts

@@ -0,0 +1,152 @@
+// nano-workforce — the ONE canonical "what is this PR's effective status" derivation (issue #959).
+//
+// THE DEFECT. `derived_status` came from the `instanceTracking` `onTerminated.set` edge, which maps
+// **any** terminated run to `abandoned` without consulting the PR's merge state. But a run is
+// terminated AFTER its PR merged in several legitimate ways — an operator cancels a loop that is
+// redundant after a merge, an out-of-band merge (Mergify / a manual click) is reconciled, a restart
+// or upgrade cleans up. Every one of those was recorded "abandoned", which made the status
+// untrustworthy (an operator can't tell dropped work from shipped work) and skewed retro/conformance
+// stats (`LANDED_PR_STATUSES` excludes `abandoned`, so merged PRs didn't count as landed).
+//
+// THE FIX (the defect class, not the instance). `abandoned` must mean "terminated AND the PR did not
+// merge". When the PR landed — recorded on the base row's `merged_at` (set by `pr.mark-merged` or the
+// out-of-band `retireTerminalReviewWait`) — the effective status is `merged` REGARDLESS of how the
+// instance ended. This module owns that derivation ONCE, as a `defineReadModel` over the SAME
+// canonical `urban_instance_state` projection the framework's tracking view uses, plus the base row's
+// own `merged_at` column.
+//
+// HOW IT SHIPS. The model is named `pull_requests__tracking` — the EXACT managed-VIEW name urban's
+// `instanceTracking` provisioner would otherwise create for the `pull_requests` binding
+// (`instanceTrackingReadModelTarget`). Registering it into the process-wide `readModelRegistry` makes
+// the framework's mount DEFER to this app-owned derivation: `provisionInstanceTrackingViews` refuses
+// to clobber a registered read model of the same name (it logs and skips), and `mountWorkers`
+// (`readModelRegistry.ensureViews`) — which runs BEFORE `mountInstanceTracking` — applies this VIEW.
+// So every reader that already routes through `pull_requests__tracking.derived_status` (the abandon
+// check, conformance, retro, the PR list, the read model) picks up the merge-aware edge with NO
+// per-reader change — the "one canonical derivation, no per-reader logic" the issue asks for.
+//
+// PRECEDENCE (merged > terminated > waiting-human > base). The merged `WHEN` is emitted FIRST so a
+// landed PR reads `merged` even when its instance was terminated; a terminated-unmerged run still
+// reads `abandoned`; a waiting-on-human edge (none for pull_requests today, but kept for parity with
+// the framework's derivation) still applies to a live, unmerged run; otherwise the worker-owned base
+// `status` passes through.
+
+import {
+  and,
+  caseWhen,
+  col,
+  defineReadModel,
+  type Expr,
+  eq,
+  exists,
+  isNotNull,
+  lit,
+  not,
+  or,
+  pcol,
+  type ReadModel,
+  readModelRegistry,
+  when,
+} from "@nanobpm/urban";
+import { trackingBindingFor, trackingTargetFor } from "./instanceTracking.ts";
+
+const TABLE = "pull_requests";
+
+/** The engine-truth terminal lifecycle state the terminal edge keys on (mirrors urban's
+ *  `TERMINATED_STATE`). Duplicated as a literal so this module derives from the public DSL primitives
+ *  (`exists`/`pcol`) without reaching into urban's internals. */
+const TERMINATED = "TERMINATED";
+
+/** `EXISTS(urban_instance_state WHERE process_instance_key = base.<keyField> AND state='TERMINATED')`
+ *  — the SAME terminal edge the framework's tracking derivation uses, keyed off the binding's
+ *  `keyField` (`process_key`) so it can never drift from the reconciler's notion of "which column
+ *  holds the engine instance key". */
+function terminatedEdge(keyField: string): Expr {
+  return exists(
+    "urban_instance_state",
+    and(eq(pcol("process_instance_key"), col(keyField)), eq(pcol("state"), lit(TERMINATED))),
+  );
+}
+
+/** `EXISTS(urban_open_user_tasks WHERE process_instance_key = base.<keyField>)` — the wait-on-human
+ *  edge, kept for parity with the framework's derivation (a binding that adds `onWaitingHuman` later
+ *  still derives it correctly). */
+function waitingHumanEdge(keyField: string): Expr {
+  return exists("urban_open_user_tasks", eq(pcol("process_instance_key"), col(keyField)));
+}
+
+/** The landed signal: the base row's `merged_at` stamp OR a durable `merges.outcome='merged'` audit
+ *  row. `pr.merge` writes the audit BEFORE the separate `pr.mark-merged` task stamps `merged_at`, so a
+ *  run terminated between the two still landed — the audit alone must be sufficient. Neither signal
+ *  depends on a retained instance-state row (a pruned/null `process_key` still reads `merged`). */
+function landedEdge(): Expr {
+  return or(
+    isNotNull(col("merged_at")),
+    exists("merges", and(eq(pcol("pr_key"), col("pr_key")), eq(pcol("outcome"), lit("merged")))),
+  );
+}
+
+/** The merge-aware effective-status derivation for the `pull_requests` binding:
+ *
+ *   CASE
+ *     WHEN <merged_at set OR merged audit row>         THEN 'merged'      -- landed wins, however the run ended
+ *     WHEN <terminated>                                THEN <onTerminated> -- terminated-unmerged = abandoned
+ *     WHEN <waiting-on-human> AND NOT <terminated>     THEN <onWaitingHuman>
+ *     ELSE base.<statusField>                          -- the worker-owned transient
+ *   END
+ *
+ * The merged `WHEN` precedes the terminated one so a landed PR is `merged` no matter how its run
+ * ended; the terminated-unmerged branch preserves the manifest's `onTerminated.set.status` value
+ * (`abandoned`) rather than hard-coding it, so the manifest stays the source of truth for the
+ * not-landed terminal. */
+export function derivePrEffectiveStatusExpr(): Expr {
+  const binding = trackingBindingFor(TABLE);
+  const statusField = binding.statusField ?? "status";
+  const keyField = binding.keyField;
+  const terminated = terminatedEdge(keyField);
+
+  const whens = [
+    // Landed beats terminated: a merged PR is `merged` even when its loop was terminated afterwards.
+    when(landedEdge(), lit("merged")),
+  ];
+  const terminalStatus = binding.onTerminated?.set?.[statusField];
+  if (typeof terminalStatus === "string") {
+    whens.push(when(terminated, lit(terminalStatus)));
+  }
+  const waitingStatus = binding.onWaitingHuman?.set?.[statusField];
+  if (typeof waitingStatus === "string") {
+    whens.push(when(and(waitingHumanEdge(keyField), not(terminated)), lit(waitingStatus)));
+  }
+  return caseWhen(whens, col(statusField));
+}
+
+/** The derived column exposing "this PR's owning run was terminated" SEPARATELY from the effective
+ *  status. `derived_status` deliberately reports a landed PR as `merged` even when its run was
+ *  terminated, so it can no longer carry the cancellation signal on its own — the abort protocol
+ *  (`abandonStatusForToken`) reads THIS column too, so terminating a redundant post-merge round still
+ *  tells its agent to stop. `1` when terminated, otherwise `NULL`. */
+export const OWNER_TERMINATED_COLUMN = "owner_terminated";
+
+/** `CASE WHEN <terminated> THEN 1 END` over the same terminal edge `derived_status` uses. */
+export function deriveOwnerTerminatedExpr(): Expr {
+  return caseWhen([when(terminatedEdge(trackingBindingFor(TABLE).keyField), lit(1))], lit(null));
+}
+
+/** The app-owned `pull_requests__tracking` read model. `selectBaseColumns: true` (the default) so the
+ *  VIEW re-exports `pull_requests.*` plus the derived `derived_status` — byte-compatible with the
+ *  framework's own tracking VIEW shape, so every existing reader keeps working unchanged. */
+export const pullRequestTrackingReadModel: ReadModel = defineReadModel({
+  name: trackingTargetFor(TABLE).view,
+  baseTable: TABLE,
+  derive: {
+    [trackingTargetFor(TABLE).statusColumn]: derivePrEffectiveStatusExpr(),
+    [OWNER_TERMINATED_COLUMN]: deriveOwnerTerminatedExpr(),
+  },
+});
+
+/** Register the merge-aware tracking VIEW into the process-wide `readModelRegistry` so the framework
+ *  provisions THIS derivation (and defers its own). Call ONCE at boot, BEFORE `runFromEnv` mounts
+ *  workers/instance-tracking. Idempotent: re-registering the identical definition is a no-op. */
+export function registerPullRequestTrackingReadModel(): void {
+  readModelRegistry.register(pullRequestTrackingReadModel);
+}

package/app/retro.test.ts

@@ -140,6 +140,17 @@ test("isPlanComplete: true when every task is settled (terminal PR or skipped/bl
   assertEquals(await isPlanComplete(data, PLAN), true);
 });
 
+// Issue #959: a PR that MERGED but whose loop was terminated afterwards derived `abandoned` off the
+// `onTerminated` edge. Retro must still treat it as the landed terminal it is. Model the terminated
+// divergence by seeding the base row at its frozen in-flight transient WITH `merged_at` set: the
+// merge-aware tracking view folds it to `merged`, so the plan reads complete (not stuck-in-flight).
+test("isPlanComplete: a merged-then-terminated PR (frozen base + merged_at) is terminal/landed (#959)", async () => {
+  const { data, stores } = memData();
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  stores["pull_requests"] = [{ pr_key: "acme/widgets#10", status: "converging", merged_at: "2026-11-01T00:00:00Z" }];
+  assertEquals(await isPlanComplete(data, PLAN), true);
+});
+
 test("isPlanComplete: an empty plan has nothing to retrospect", async () => {
   const { data } = memData();
   assertEquals(await isPlanComplete(data, PLAN), false);