@nanobpm/nano-workforce 0.132.0 → 0.133.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.133.1](https://github.com/nanobpm/nano-workforce/compare/v0.133.0...v0.133.1) (2026-08-24)
+
+### Bug Fixes
+
+* **read-model:** migrate remaining terminal-edge readers to derived_status ([#503](https://github.com/nanobpm/nano-workforce/issues/503)) ([#508](https://github.com/nanobpm/nano-workforce/issues/508)) ([663f113](https://github.com/nanobpm/nano-workforce/commit/663f1135a79a14436565f2a6b2320ad62bb0db6b))
+
+## [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/featureReadModel.test.ts

@@ -10,12 +10,12 @@
 // emitted from the ONE `featureReadModel` declaration, which ALSO drives the TS via `fnFor`. This
 // suite therefore guards THREE things:
 //
-//   1. DRIFT GUARD — migration 076 embeds each derived column's SQL VERBATIM from
+//   1. DRIFT GUARD — migration 080 embeds each derived column's SQL VERBATIM from
 //      `featureReadModel.sqlSelectFor(...)`, so the checked-in VIEW cannot drift from the declaration.
 //   2. FRAMEWORK PARITY GUARD — `assertReadModelParity` proves the SQL and TS lowerings the ONE
 //      declaration compiles to agree (the role the old hand-written lockstep test played, now
 //      framework-owned).
-//   3. END-TO-END BEHAVIOUR on the REAL migration VIEW (076 applied to an in-memory DB): the full
+//   3. END-TO-END BEHAVIOUR on the REAL migration VIEW (080 applied to an in-memory DB): the full
 //      status × open-task matrix vs the model-derived oracle, the stale-stored-column ignore, the
 //      reconciler `status`-bypass, the #422 answered-escalation drift, and the page binding.
 import { readFileSync } from "node:fs";
@@ -31,11 +31,14 @@ import { deriveListBucket, deriveStage } from "./stage.ts";
 const MIG = (name: string) => readFileSync(fileURLToPath(new URL(`../db/migrations/${name}`, import.meta.url)), "utf8");
 const PAGE = (name: string) => JSON.parse(readFileSync(fileURLToPath(new URL(`../pages/${name}`, import.meta.url)), "utf8"));
 
-const MIGRATION_076 = "076_feature_read_model_declare_once.sql";
+const MIGRATION_LATEST = "081_feature_read_model_derive_terminal.sql";
 
 // The base `feature_runs` shape the VIEW reads, plus the `user_tasks` inbox (034) the `attention`
-// derivation `EXISTS`-reads. The stored derived columns are present precisely so the tests can seed
-// STALE values and prove the VIEW ignores them.
+// derivation `EXISTS`-reads, plus a stand-in for the managed `feature_runs__tracking` derived VIEW
+// (ADR-0065) the read model now reads its terminal-folded `derived_status` off. The stored derived
+// columns are present precisely so the tests can seed STALE values and prove the VIEW ignores them;
+// `derived_status_override` lets a test model the reconciler's derive edge (a terminated instance ⇒
+// `abandoned` while base `status` stays frozen).
 function viewDb(): DatabaseSync {
   const db = new DatabaseSync(":memory:");
   db.exec(
@@ -43,14 +46,23 @@ function viewDb(): DatabaseSync {
        feature_key TEXT PRIMARY KEY, repo TEXT, issue_number INTEGER, issue_url TEXT, title TEXT,
        base_branch TEXT, status TEXT, process_key TEXT, pr_key TEXT, converge INTEGER, auto_merge INTEGER,
        outcome TEXT, delivery_label TEXT, acknowledged_at TEXT, created_at TEXT, updated_at TEXT,
-       stage TEXT, stage_state TEXT, stage_skipped TEXT, attention TEXT, list_bucket TEXT);`,
+       stage TEXT, stage_state TEXT, stage_skipped TEXT, attention TEXT, list_bucket TEXT,
+       derived_status_override TEXT);`,
   );
   db.exec(
     `CREATE TABLE user_tasks (
        user_task_key TEXT PRIMARY KEY, element_id TEXT NOT NULL, subject_type TEXT NOT NULL,
        subject_key TEXT NOT NULL);`,
   );
-  db.exec(MIG(MIGRATION_076));
+  // Stand-in for the managed `feature_runs__tracking` VIEW urban provisions at mount: re-exports
+  // `feature_runs.*` plus the terminal-folded `derived_status` the read model (migration 080) reads. A
+  // test seeds `derived_status_override` to model the reconciler's derive edge; absent, it falls through
+  // to the base `status`, exactly as the real VIEW's `ELSE base.status` branch does.
+  db.exec(
+    `CREATE VIEW feature_runs__tracking AS
+       SELECT f.*, COALESCE(f.derived_status_override, f.status) AS derived_status FROM feature_runs f;`,
+  );
+  db.exec(MIG(MIGRATION_LATEST));
   return db;
 }
 
@@ -126,22 +138,22 @@ function parityDb(db: DatabaseSync): ParityDb {
   };
 }
 
-test("DRIFT GUARD: migration 076 embeds each derived column VERBATIM from featureReadModel.sqlSelectFor (the VIEW cannot drift from the declaration)", () => {
-  const sql = MIG(MIGRATION_076);
+test("DRIFT GUARD: migration 080 embeds each derived column VERBATIM from featureReadModel.sqlSelectFor (the VIEW cannot drift from the declaration)", () => {
+  const sql = MIG(MIGRATION_LATEST);
   for (const col of FEATURE_READ_MODEL_DERIVED) {
     const emitted = featureReadModel.sqlSelectFor(col, { baseAlias: FEATURE_READ_MODEL_BASE_ALIAS });
     assert(
       sql.includes(`${emitted} AS ${col}`),
-      `migration ${MIGRATION_076} no longer embeds the declaration's SQL for "${col}" — regenerate it ` +
+      `migration ${MIGRATION_LATEST} no longer embeds the declaration's SQL for "${col}" — regenerate it ` +
         `from featureReadModel (or add a new superseding migration). Expected to contain:\n  ${emitted} AS ${col}`,
     );
   }
   // The VIEW is a DROP+CREATE that supersedes 073/075, and keeps every base column as an aliased
   // pass-through so the static pages↔schema contract guard still sees them.
-  assert(/DROP VIEW IF EXISTS feature_read_model;/.test(sql), "076 must DROP the superseded VIEW first");
-  assert(/CREATE VIEW feature_read_model AS/.test(sql), "076 must (re)create feature_read_model");
+  assert(/DROP VIEW IF EXISTS feature_read_model;/.test(sql), "080 must DROP the superseded VIEW first");
+  assert(/CREATE VIEW feature_read_model AS/.test(sql), "080 must (re)create feature_read_model");
   for (const base of ["feature_key", "status", "pr_key", "converge", "auto_merge", "acknowledged_at", "title", "repo"]) {
-    assert(sql.includes(`fr.${base} AS ${base}`), `076 must pass base column "${base}" through the VIEW`);
+    assert(sql.includes(`fr.${base} AS ${base}`), `080 must pass base column "${base}" through the VIEW`);
   }
 });
 
@@ -157,7 +169,11 @@ test("FRAMEWORK PARITY GUARD: featureReadModel's SQL and TS lowerings agree over
               const userTasks =
                 openTask && el !== null ? [{ subject_type: "feature", subject_key: "self", element_id: el }] : [];
               samples.push({
-                baseRow: { feature_key: "self", status, pr_key, converge, auto_merge, acknowledged_at },
+                // The status-classifying derivations read the tracking VIEW's terminal-folded
+                // `derived_status`; for a live (non-terminated) run it equals the base transient, so
+                // parity samples set it from `status`. (The parity guard's fixture table is named for the
+                // model's baseTable, `feature_runs__tracking`.)
+                baseRow: { feature_key: "self", status, derived_status: status, pr_key, converge, auto_merge, acknowledged_at },
                 projections: { user_tasks: userTasks },
               });
             }
@@ -172,7 +188,7 @@ test("FRAMEWORK PARITY GUARD: featureReadModel's SQL and TS lowerings agree over
   db.close();
 });
 
-test("the migration 076 VIEW derives stage/stage_state/stage_skipped/attention EXACTLY like deriveStage, over every status × converge/auto_merge/pr_key × open-task combination", () => {
+test("the migration 080 VIEW derives stage/stage_state/stage_skipped/attention EXACTLY like deriveStage, over every status × converge/auto_merge/pr_key × open-task combination", () => {
   const db = viewDb();
   const cases: Array<{ key: string; run: SampleRun; hasOpenBlockedTask: boolean; hasOpenEscalationTask: boolean }> = [];
   let i = 0;
@@ -217,7 +233,7 @@ test("the migration 076 VIEW derives stage/stage_state/stage_skipped/attention E
   }
 });
 
-test("the migration 076 VIEW derives list_bucket EXACTLY like deriveListBucket (history iff terminal AND acknowledged)", () => {
+test("the migration 080 VIEW derives list_bucket EXACTLY like deriveListBucket (history iff terminal AND acknowledged)", () => {
   const db = viewDb();
   let i = 0;
   const cases: Array<{ key: string; status: string; ackAt: string | null }> = [];
@@ -237,7 +253,7 @@ test("the migration 076 VIEW derives list_bucket EXACTLY like deriveListBucket (
   }
 });
 
-test("the migration 076 VIEW IGNORES any stale STORED projection columns — it reads only from status et al.", () => {
+test("the migration 080 VIEW IGNORES any stale STORED projection columns — it reads only from status et al.", () => {
   const db = viewDb();
   // A merged run whose STORED columns lie (frozen from when it was `running`). The VIEW must re-derive.
   addRun(db, "o/r#stale", {
@@ -312,6 +328,35 @@ test("RED/GREEN GUARD: a RAW-datasource feature_runs.status write (the instanceT
   assertEquals(row.list_bucket, deriveListBucket("abandoned", null));
 });
 
+test("RED/GREEN #503: a DERIVE-ONLY terminated run (base status frozen at 'running', derived_status='abandoned') renders Done/failed, not wedged 'Implementing'", () => {
+  // ADR-0065 (urban 0.81.0): cancel/terminate is DERIVE-ONLY — the reconciler feeds urban's projection
+  // and `feature_runs__tracking.derived_status` recomputes `abandoned` on READ; it does NOT write the
+  // terminal onto the base `feature_runs.status` column. So the base row stays frozen at its last
+  // transient (`running`) while the run is really terminated. Before 080 the read model classified off
+  // the frozen base `status` and rendered the dead run "Implementing" on the Feature history grid
+  // forever (the #503 phantom). 080 reads the terminal-folded `derived_status`, so it renders Done/
+  // failed with no worker write.
+  const db = viewDb();
+  // Seed a run whose engine instance was terminated out-of-band: base status still `running`, but the
+  // derive edge reports `abandoned` (modelled via the feature_runs__tracking stand-in's override).
+  addRun(db, "o/r#term", {
+    status: "running",
+    stored: { stage: "Implementing", stage_state: undefined, attention: "⚠", list_bucket: "active" },
+  });
+  assertEquals(projection(db, "o/r#term").stage, "Implementing", "precondition: the live transient renders Implementing");
+
+  db.prepare("UPDATE feature_runs SET derived_status_override = 'abandoned' WHERE feature_key = ?").run("o/r#term");
+
+  const row = projection(db, "o/r#term");
+  const oracle = deriveStage({ status: "abandoned", pr_key: null, converge: 0, auto_merge: 0 });
+  assertEquals(row.stage, "Done", "a derive-only terminated run is Done, not wedged at Implementing (the #503 phantom)");
+  assertEquals(row.stage, oracle.stage);
+  assertEquals(row.stage_state, "failed", "the derived terminal renders a FAILED state (was frozen NULL/Implementing)");
+  assertEquals(row.stage_state, oracle.state);
+  assertEquals(row.attention, null, "the stale ⚠ badge is gone once the run is terminated");
+  assertEquals(row.list_bucket, "active", "a just-cancelled run sits in Active until dismissed");
+});
+
 test("the Feature page binds the derived feature_read_model VIEW (not the raw feature_runs table)", () => {
   // `feature.page.json`'s runs grid is the ONLY thing making the UI consume the derived projection.
   const page = PAGE("feature.page.json");

package/app/featureReadModel.ts

@@ -47,20 +47,38 @@ export const STAGE_DONE_STATUSES: readonly string[] = ["merged", "converged", "b
  * promote this to the framework's canonical `urban_open_user_tasks` projection.) */
 export const USER_TASKS_PROJECTION = "user_tasks";
 
-/** `status IN (…)` as a closed-DSL predicate: an OR of equalities over the base row's `status`. */
-const statusIn = (...statuses: readonly string[]): Expr => or(...statuses.map((s) => eq(col("status"), lit(s))));
+/** The base table the read model reads: the auto-provisioned `feature_runs__tracking` derived VIEW
+ * (ADR-0065, urban 0.81.0), NOT the raw `feature_runs` table. The VIEW re-exports `feature_runs.*`
+ * plus a `derived_status` column that folds the `instanceTracking` reconciler's terminal edge
+ * (out-of-band terminate / in-app cancel → `abandoned`) over the worker-owned transient `status`. The
+ * status-classifying derivations below read `derived_status`, so a terminated run renders `Done`/
+ * `failed` instead of freezing at its last transient (`Implementing` forever — issue #503). The
+ * non-status base columns (`pr_key`/`converge`/`auto_merge`/`acknowledged_at`/`feature_key`) come off
+ * the same VIEW's pass-through of `base.*`. */
+export const FEATURE_READ_MODEL_BASE_TABLE = "feature_runs__tracking";
 
-/** The terminal tier — the row's `status` is one of the 6 `Done` statuses. */
+/** The effective-status column the status-classifying derivations read: the tracking VIEW's ADR-0065
+ * `derived_status` (terminal-folded), NOT the frozen base `status`. Single source of truth for the
+ * column name so the derivations can't drift from it. */
+export const EFFECTIVE_STATUS_COLUMN = "derived_status";
+
+/** `derived_status IN (…)` as a closed-DSL predicate: an OR of equalities over the tracking VIEW's
+ * terminal-folded effective status. */
+const statusIn = (...statuses: readonly string[]): Expr =>
+  or(...statuses.map((s) => eq(col(EFFECTIVE_STATUS_COLUMN), lit(s))));
+
+/** The terminal tier — the row's effective (terminal-folded) status is one of the 6 `Done` statuses. */
 const isDone: Expr = statusIn(...STAGE_DONE_STATUSES);
 
 /** The canonical pipeline `stage`. TOTAL over all 11 statuses. Terminal → `Done`; else `converging`
  * → `Converging`; else a raised PR (`pr_key` set, mirroring `(pr_key ?? "") !== ""`) or `opened` →
- * `PR open`; else a live/parked implementation status → `Implementing`; else `Requested`. */
+ * `PR open`; else a live/parked implementation status → `Implementing`; else `Requested`. Classifies
+ * on the terminal-folded `derived_status` so a cancelled/terminated run is `Done`, not frozen. */
 const stage: Expr = caseWhen(
   [
     when(isDone, lit("Done")),
-    when(eq(col("status"), lit("converging")), lit("Converging")),
-    when(or(neq(col("pr_key"), lit("")), eq(col("status"), lit("opened"))), lit("PR open")),
+    when(eq(col(EFFECTIVE_STATUS_COLUMN), lit("converging")), lit("Converging")),
+    when(or(neq(col("pr_key"), lit("")), eq(col(EFFECTIVE_STATUS_COLUMN), lit("opened"))), lit("PR open")),
     when(statusIn("running", "escalated", "awaiting_operator"), lit("Implementing")),
   ],
   lit("Requested"),
@@ -68,11 +86,12 @@ const stage: Expr = caseWhen(
 
 /** The active stage's render state in the `kind:"pipeline"` column's vocabulary: `ok` (merged/
  * converged), `blocked` (terminal blocked), `failed` (failed/skipped/abandoned), else NULL (in
- * progress). A pure function of `status`, so it is correct even for a parked/live status (NULL). */
+ * progress). A pure function of the terminal-folded `derived_status`, so a terminated run renders a
+ * terminal `failed` state instead of a frozen NULL. */
 const stageState: Expr = caseWhen(
   [
     when(statusIn("merged", "converged"), lit("ok")),
-    when(eq(col("status"), lit("blocked")), lit("blocked")),
+    when(eq(col(EFFECTIVE_STATUS_COLUMN), lit("blocked")), lit("blocked")),
     when(statusIn("failed", "skipped", "abandoned"), lit("failed")),
   ],
   lit(null),
@@ -136,7 +155,7 @@ export type FeatureReadModelDerivedColumn = (typeof FEATURE_READ_MODEL_DERIVED)[
  */
 export const featureReadModel: ReadModel = defineReadModel({
   name: "feature_read_model",
-  baseTable: "feature_runs",
+  baseTable: FEATURE_READ_MODEL_BASE_TABLE,
   selectBaseColumns: false,
   derive: {
     stage,

package/app/interEpicRegression.test.ts

@@ -18,6 +18,7 @@ import { resetDefaultBranchCache } from "./github.ts";
 import type { PlanDep } from "./plan.ts";
 import { EpicSetValidationError, validateEpicSet } from "./plan.ts";
 import { capabilityProbeForEdge, deriveEpicSchedule, lowerAdmittedSet } from "./planLowering.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import {
   type GithubRelease,
   matchCapability,
@@ -80,7 +81,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);
@@ -210,7 +211,7 @@ function makeData() {
       return Promise.resolve({ processInstanceKey: `PI-${started.length}` });
     },
   } as unknown as EngineClient;
-  const data = { table } as unknown as DataLayer;
+  const data = { table: withTrackingViews(table) } as unknown as DataLayer;
   return { data, engine, tables, started };
 }
 

package/app/plan.test.ts

@@ -6,6 +6,7 @@
 // is not a positive integer, so the loop is always bounded.
 import { after, test } from "node:test";
 import { assertEquals, assertRejects, assertThrows } from "#test-assert";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import { positiveIntEnv } from "./plan.ts";
 
 const KEY = "NANO_PLAN_REVIEW_ROUNDS_TEST";
@@ -126,8 +127,8 @@ test("re-plan of a finished issue clears stale plan_reviews rows", async () => {
     plan_task_deps: { rows: [], key: "plan_key" },
   };
   const data = {
-    table: (name: string, key: string) =>
-      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    table: withTrackingViews((name: string, key: string) =>
+      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
   } as any;
   const engine = {
     createInstance: () => Promise.resolve({ processInstanceKey: "PI-1" }),
@@ -146,8 +147,8 @@ test("re-plan of a finished issue clears stale plan_reviews rows", async () => {
 
 function memData(stores: Record<string, { rows: any[]; key: string }>) {
   return {
-    table: (name: string, key: string) =>
-      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    table: withTrackingViews((name: string, key: string) =>
+      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
   } as any;
 }
 

package/app/plan.ts

@@ -21,6 +21,7 @@ import {
   fetchDefaultBranch,
   fetchIssueTitle,
 } from "./github.ts";
+import { derivedTrackingTable } from "./instanceTracking.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
 import type { ReadinessProbe } from "./readiness.ts";
 import { clearTaskDeltas } from "./taskDelta.ts";
@@ -197,6 +198,17 @@ export type PlanTaskStatus = typeof PLAN_TASK_STATUSES[number];
  * offers Dismiss without a poller pass. The pure helpers stay the acknowledge-epic guard and the VIEW's
  * test oracle (app/plansReadModel.test.ts). */
 export const plans = (data: DataLayer) => data.table<Plan>("plans", "plan_key");
+/** A plan row as seen through its derived tracking VIEW (`plans__tracking`): the base columns plus
+ * urban's ADR-0065 `derived_status`, which folds the reconciler's terminal edge (out-of-band
+ * terminate / in-app cancel → `abandoned`) over the worker-owned transient. */
+type TrackedPlan = Plan & { derived_status: string };
+/** Read-only accessor over the plan derived tracking VIEW. Use this — and read `derived_status`, not
+ * `status` — for any terminal/active classification (the shared-base admission filter, the
+ * epic-admission idempotency gate), so an out-of-band-terminated epic (whose base row is still
+ * `planning`/`dispatched`) is correctly seen as `abandoned`. Worker-written terminals (`done`/
+ * `failed`) pass through unchanged. Writes stay on `plans`. */
+export const plansTracking = (data: DataLayer) =>
+  derivedTrackingTable<TrackedPlan>(data, "plans", "plan_key");
 export const planTasks = (data: DataLayer) => data.table<PlanTask>("plan_tasks", "id");
 
 /** One dependency edge in the plan DAG (issue #20): `task_id` waits for `depends_on_task_id`.
@@ -590,8 +602,12 @@ export async function findActivePlansByBase(
   repo: string,
   base: string,
 ): Promise<Plan[]> {
-  const rows = await plans(data).find({ repo, base_branch: base });
-  return rows.filter((p) => !PLAN_TERMINAL_STATUSES.some((s) => s === p.status));
+  const rows = await plansTracking(data).find({ repo, base_branch: base });
+  // ADR-0065: classify "active" on the DERIVED terminal edge, not the base transient — an epic whose
+  // engine instance was terminated out-of-band (or by an ordinary in-app cancel) keeps its base
+  // `status` frozen at `planning`/`dispatched` but reads `abandoned` on `plans__tracking.derived_status`.
+  // Reading the base `status` here counted a dead epic as ACTIVE and raised a false same-repo conflict.
+  return rows.filter((p) => !PLAN_TERMINAL_STATUSES.some((s) => s === p.derived_status));
 }
 
 /** Options gating the confirm-default (rule 3) and shared-base (rule 4) admission rules. Both
@@ -926,7 +942,14 @@ export async function startPlan(
   }
   const table = plans(data);
   const existing = await table.get(parsed.planKey);
-  if (existing && !PLAN_TERMINAL_STATUSES.some((s) => s === existing.status)) {
+  // ADR-0065: classify "already running" on the DERIVED terminal edge, not the base transient. An epic
+  // whose engine instance was terminated out-of-band (or by an ordinary in-app cancel — derive-only
+  // under urban 0.81.0) has a base row frozen at `planning`/`dispatched` but a
+  // `plans__tracking.derived_status` of `abandoned`; reading the base `status` here wedged a cancelled
+  // epic `alreadyRunning` (the `submitPr`-wedge twin). Route the idempotency gate through the derived
+  // view so a terminated epic is correctly seen terminal and RE-ADMITTABLE.
+  const trackedExisting = existing ? await plansTracking(data).get(parsed.planKey) : undefined;
+  if (trackedExisting && !PLAN_TERMINAL_STATUSES.some((s) => s === trackedExisting.derived_status)) {
     return { planKey: parsed.planKey, alreadyRunning: true };
   }
   const base = normalizeBaseBranch(baseBranch);

package/app/planLowering.test.ts

@@ -8,7 +8,7 @@ import { assert, assertEquals } from "#test-assert";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import type { PlanDep } from "./plan.ts";
 import { capabilityProbeForEdge, deriveEpicSchedule, lowerAdmittedSet } from "./planLowering.ts";
-
+import { withTrackingViews } from "../test/trackingViews.ts";
 const edge = (consumer: string, producer: string, pkg = "@scope/pkg", capRef = producer): PlanDep => ({
   plan_key: consumer,
   depends_on_plan_key: producer,
@@ -54,7 +54,7 @@ function makeData() {
       return Promise.resolve({ processInstanceKey: `PI-${started.length}` });
     },
   } as unknown as EngineClient;
-  const data = { table } as unknown as DataLayer;
+  const data = { table: withTrackingViews(table) } as unknown as DataLayer;
   return { data, engine, tables, started };
 }
 

package/app/plansReadModel.test.ts

@@ -34,19 +34,32 @@ function viewDb(): DatabaseSync {
        plan_key TEXT PRIMARY KEY, repo TEXT, issue_number INTEGER, issue_url TEXT, title TEXT,
        status TEXT, task_count INTEGER, process_key TEXT, outcome TEXT, created_at TEXT,
        updated_at TEXT, epic_phase TEXT, base_branch TEXT, wait_gate_label TEXT, bound_artifacts TEXT,
-       promotion_pr TEXT, promotion_state TEXT, acknowledged_at TEXT, list_bucket TEXT, ack_open INTEGER);
+       promotion_pr TEXT, promotion_state TEXT, acknowledged_at TEXT, list_bucket TEXT, ack_open INTEGER,
+       derived_status_override TEXT);
      CREATE TABLE plan_tasks (
        id INTEGER PRIMARY KEY, plan_key TEXT, task_index INTEGER, task_id TEXT, title TEXT,
        prompt TEXT, status TEXT, pr_key TEXT, summary TEXT, created_at TEXT, updated_at TEXT,
        wave INTEGER, open_question TEXT, answer TEXT, draft_pr_key TEXT, corr_key TEXT);
      CREATE TABLE pull_requests (pr_key TEXT PRIMARY KEY, url TEXT, status TEXT, process_key TEXT);`,
   );
+  // Stand-in for the managed `plans__tracking` VIEW urban provisions at mount (ADR-0065): re-exports
+  // `plans.*` plus the `derived_status` the terminal-edge reader (migration 079) reads. A test seeds
+  // `derived_status_override` to model the reconciler's derive edge (a terminated instance ⇒
+  // `abandoned` while base `status` stays frozen); absent, it falls through to the base `status`, exactly
+  // as the real VIEW's `ELSE base.status` branch does.
+  db.exec(
+    `CREATE VIEW plans__tracking AS
+       SELECT p.*, COALESCE(p.derived_status_override, p.status) AS derived_status FROM plans p;`,
+  );
   db.exec(MIG("059_plan_wave_summary.sql"));
   db.exec(MIG("060_plan_wave_rollup.sql"));
   db.exec(MIG("061_plan_delivery_rollup.sql"));
   // 074 redefines plan_read_model to DERIVE list_bucket/ack_open from status + acknowledged_at + the
   // derived plan_delivery signal (issue #439), instead of reading the denormalised base columns.
   db.exec(MIG("074_plan_read_model_derive_bucket.sql"));
+  // 079 re-points plan_read_model's status/bucket derivations at the derived plans__tracking VIEW so a
+  // terminated (derive-only `abandoned`) epic drops out of Active (issue #503).
+  db.exec(MIG("080_plan_read_model_derive_terminal.sql"));
   return db;
 }
 
@@ -367,3 +380,27 @@ test("RED/GREEN GUARD: a RAW-datasource plans.status write (the instanceTracking
   assertEquals(b.ack_open, epicIsAcknowledgeable("abandoned", b.delivery) ? 1 : 0);
   assertEquals(b.ack_open, 0, "no phantom Dismiss on a reconciler-cancelled epic");
 });
+
+test("RED/GREEN #503: a DERIVE-ONLY terminated epic (base status frozen, derived_status='abandoned') drops out of Active", () => {
+  // ADR-0065 (urban 0.81.0): cancel/terminate is DERIVE-ONLY — the reconciler feeds urban's projection
+  // and `plans__tracking.derived_status` recomputes `abandoned` on READ; it does NOT write the terminal
+  // onto the base `plans.status` column. So the base row stays frozen at its last transient
+  // (`dispatched`) while the epic is really terminated. Before 079 `plan_read_model` bucketed off the
+  // frozen base column and rendered the dead epic ACTIVE on the epic index/detail forever (the #503 /
+  // #497 phantom). 079 reads the effective status off `plans__tracking`, so it drops to History.
+  const db = viewDb();
+  // Seed a plan whose engine instance was terminated out-of-band: base status still `dispatched`, but
+  // the derive edge reports `abandoned` (modelled via the plans__tracking stand-in's override column).
+  db.prepare(
+    "INSERT INTO plans (plan_key, repo, issue_number, issue_url, status, task_count, updated_at, acknowledged_at, list_bucket, derived_status_override) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+  ).run("o/r#term", "o/r", 7, "https://gh/o/r#term", "dispatched", 0, "2026-01-01T00:00:00Z", null, "active", "abandoned");
+
+  const r = db
+    .prepare("SELECT status, list_bucket, ack_open FROM plan_read_model WHERE plan_key = ?")
+    .get("o/r#term") as { status: string; list_bucket: string; ack_open: number };
+
+  assertEquals(r.status, "abandoned", "plan_read_model surfaces the DERIVED terminal, not the frozen base transient");
+  assertEquals(r.list_bucket, "history", "a derive-only terminated epic is filed under History, not wedged Active");
+  assertEquals(r.list_bucket, deriveEpicBucket("abandoned", null, null));
+  assertEquals(r.ack_open, 0, "no phantom Dismiss on a derive-only terminated epic");
+});