@nanobpm/nano-workforce 0.133.0 → 0.134.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.134.0](https://github.com/nanobpm/nano-workforce/compare/v0.133.1...v0.134.0) (2026-08-24)
+
+### Features
+
+* **delivery-graph:** node timeout PT1H default, submission + per-node override ([#505](https://github.com/nanobpm/nano-workforce/issues/505)) ([#507](https://github.com/nanobpm/nano-workforce/issues/507)) ([96fe961](https://github.com/nanobpm/nano-workforce/commit/96fe96165bb898919f7000002e68cb4ba5a925e9))
+
+## [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

package/app/deliveryGraphDispatch.ts

@@ -23,6 +23,7 @@ import {
   DELIVERY_PHASE,
   deliveryGraphRuns,
 } from "./deliveryGraphRun.ts";
+import type { DeliveryRunTimeouts } from "./deliveryRunner.ts";
 import { deliveryGraphDigest, runDeliveryGraph } from "./deliveryRunner.ts";
 
 /** The outcome of a dispatch attempt — mirrors the retained run lifecycle. `ok:false` carries the
@@ -48,7 +49,7 @@ export type DispatchDeliveryGraphResult =
 export async function dispatchDeliveryGraphRun(
   app: Pick<AppApi, "data" | "engine" | "log">,
   graph: unknown,
-  options: { runKey?: string | null; title?: string | null } = {},
+  options: { runKey?: string | null; title?: string | null } & DeliveryRunTimeouts = {},
 ): Promise<DispatchDeliveryGraphResult> {
   const validationErrors = validateDeliveryGraph(graph);
   if (validationErrors.length > 0) {
@@ -130,7 +131,16 @@ export async function dispatchDeliveryGraphRun(
   };
   let launched: Awaited<ReturnType<typeof runDeliveryGraph>>;
   try {
-    launched = await runDeliveryGraph(app.engine, typedGraph, { runKey });
+    // Thread the operator-supplied run-level timeouts (#505) so a submission override reaches every
+    // node's seeded `nodeInputs` (absent → the runner's PT1H/PT30M/P1D defaults).
+    launched = await runDeliveryGraph(app.engine, typedGraph, {
+      runKey,
+      nodeTimeout: options.nodeTimeout,
+      probeTimeout: options.probeTimeout,
+      escalationSlaTimeout: options.escalationSlaTimeout,
+      probePollEvery: options.probePollEvery,
+      escalationAssignee: options.escalationAssignee,
+    });
   } catch (err) {
     await markClaimFailed();
     app.log.error("dispatch-delivery-graph launch threw", { runKey });

package/app/deliveryRunner.test.ts

@@ -138,6 +138,93 @@ test("wait gateKeys default to a fresh per-run token so concurrent runs of one g
   assertEquals(gateKeyOf(seeded), "run-7:n3");
 });
 
+test("the node timeout defaults to PT1H (raised from PT30M) when no option is supplied (#505)", async () => {
+  // #505: the hard PT30M default tripped the boundary timer on legitimately-long implementation nodes.
+  // With no timeout option, every agent/connector node inherits the NEW PT1H run default.
+  const p = await prepareOk(GRAPH);
+  const timeouts = Object.values(p.nodeInputs)
+    .filter((v) => "timeout" in v)
+    .map((v) => (v as { timeout: string }).timeout);
+  assert(timeouts.length === 2, `expected the agent + connector nodes to seed a timeout, got ${timeouts.length}`);
+  for (const t of timeouts) assertEquals(t, "PT1H");
+});
+
+test("a submission nodeTimeout override seeds every agent/connector node with that duration (#505)", async () => {
+  // AC: an operator dispatch that sets nodeTimeout: "PT2H" seeds PT2H for ALL agent/connector nodes.
+  const p = await prepareOk(GRAPH, { nodeTimeout: "PT2H" });
+  const timeouts = Object.values(p.nodeInputs)
+    .filter((v) => "timeout" in v)
+    .map((v) => (v as { timeout: string }).timeout);
+  assert(timeouts.length === 2, `expected two seeded node timeouts, got ${timeouts.length}`);
+  for (const t of timeouts) assertEquals(t, "PT2H");
+});
+
+test("a per-node timeout override wins for its node while siblings keep the run/default value (#505)", async () => {
+  // AC: a node declaring timeout: "PT4H" seeds nodeInputs.<el>.timeout == "PT4H" while its siblings keep
+  // the run-level (here PT2H) value. Asserted positionally on the compiled nodeInputs map.
+  const graph: DeliveryGraph = {
+    name: "per-node override",
+    nodes: [
+      { id: "heavy", kind: "agent", agent: { jobType: "senior:feature", prompt: "long build", timeout: "PT4H" } },
+      { id: "quick", kind: "agent", agent: { jobType: "senior:demo" } },
+      { id: "notify", kind: "connector", connector: { target: "slack:post", dedupeKey: "n-1", timeout: "PT10M" } },
+    ],
+    edges: [
+      { from: "heavy", to: "quick" },
+      { from: "quick", to: "notify" },
+    ],
+  };
+  const p = await prepareOk(graph, { nodeTimeout: "PT2H" });
+  const byJobType = (jt: string) =>
+    Object.values(p.nodeInputs).find((v) => (v as { jobType?: string }).jobType === jt) as { timeout: string } | undefined;
+  const connector = Object.values(p.nodeInputs).find((v) => (v as { target?: string }).target === "slack:post") as
+    | { timeout: string }
+    | undefined;
+
+  assertEquals(byJobType("senior:feature")?.timeout, "PT4H"); // per-node override wins
+  assertEquals(byJobType("senior:demo")?.timeout, "PT2H"); // sibling keeps the run-level value
+  assertEquals(connector?.timeout, "PT10M"); // connector per-node override wins too
+});
+
+test("a per-node timeout is normalized (lower-case → canonical) and a malformed one falls back to the run value (#505)", async () => {
+  // A graph built programmatically (bypassing the OpenAPI pattern) can carry a lower-case or malformed
+  // per-node duration. The runner normalizes it through `isoDuration` so a bad value never bakes an
+  // uninterpretable boundary timer: `pt4h` → `PT4H`, and `nonsense` falls back to the run-level default.
+  const graph: DeliveryGraph = {
+    name: "per-node normalization",
+    nodes: [
+      { id: "lower", kind: "agent", agent: { jobType: "senior:feature", timeout: "pt4h" } },
+      { id: "bad", kind: "connector", connector: { target: "slack:post", dedupeKey: "n-1", timeout: "nonsense" } },
+    ],
+    edges: [{ from: "lower", to: "bad" }],
+  } as unknown as DeliveryGraph;
+  const p = await prepareOk(graph, { nodeTimeout: "PT2H" });
+  const agent = Object.values(p.nodeInputs).find((v) => (v as { jobType?: string }).jobType === "senior:feature") as
+    | { timeout: string }
+    | undefined;
+  const connector = Object.values(p.nodeInputs).find((v) => (v as { target?: string }).target === "slack:post") as
+    | { timeout: string }
+    | undefined;
+
+  assertEquals(agent?.timeout, "PT4H"); // lower-case normalized to canonical form
+  assertEquals(connector?.timeout, "PT2H"); // malformed value rejected → run-level default
+});
+
+test("a RUN-LEVEL timeout is normalized (lower-case → canonical) and a malformed one falls back to the default (#505)", async () => {
+  // A programmatic caller of prepareDeliveryGraph/runDeliveryGraph bypasses the OpenAPI/door validators,
+  // so a lower-case or malformed run-level `nodeTimeout` must not become the fallback baked into a node's
+  // boundary timer FEEL. isoDuration canonicalizes it (`pt3h` → `PT3H`) at the run level too, and a
+  // malformed value falls back to the DEFAULTS run value rather than an uninterpretable duration.
+  const lower = await prepareOk(GRAPH, { nodeTimeout: "pt3h" });
+  for (const v of Object.values(lower.nodeInputs).filter((v) => "timeout" in v)) {
+    assertEquals((v as { timeout: string }).timeout, "PT3H"); // lower-case run value normalized
+  }
+  const bad = await prepareOk(GRAPH, { nodeTimeout: "nonsense" });
+  for (const v of Object.values(bad.nodeInputs).filter((v) => "timeout" in v)) {
+    assertEquals((v as { timeout: string }).timeout, "PT1H"); // malformed run value → PT1H default, never baked raw
+  }
+});
+
 test("a malformed graph returns the S1 compile errors and prepares nothing", async () => {
   const r = await prepareDeliveryGraph({ nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }], edges: [{ from: "a", to: "ghost" }] } as unknown as DeliveryGraph);
   assert(!r.ok, "a dangling edge fails to prepare");

package/app/deliveryRunner.ts

@@ -18,6 +18,7 @@ import type { EngineClient } from "@nanobpm/urban";
 import type { DeliveryFact, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
 import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery } from "./readiness.ts";
+import { isoDuration } from "./reviewWait.ts";
 
 /** The content digest of a compiled graph — `sha256(bpmn)[:12]` — the single source of truth for the
  * content-addressed deploy id (`delivery-graph-<digest>`) AND the dispatch fence's default idempotency
@@ -53,7 +54,7 @@ export interface DeliveryRunOptions extends DeliveryRunTimeouts {
 }
 
 const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
-  nodeTimeout: "PT30M",
+  nodeTimeout: "PT1H",
   probeTimeout: "PT30M",
   probePollEvery: msToIsoDuration(DEFAULT_EVERY_MS),
   escalationSlaTimeout: "P1D",
@@ -110,11 +111,14 @@ export async function prepareDeliveryGraph(
   const bpmn = rewriteProcessId(compiled.bpmn, processDefinitionId);
 
   const runKey = options.runKey?.trim() || randomUUID();
+  // Normalize the run-level timeouts through isoDuration so a programmatic caller that bypasses the
+  // OpenAPI/door validators cannot bake a malformed or lower-case duration into a BPMN timer FEEL —
+  // isoDuration canonicalizes case and falls back to the default on a malformed/blank value.
   const timeouts = {
-    nodeTimeout: options.nodeTimeout ?? DEFAULTS.nodeTimeout,
-    probeTimeout: options.probeTimeout ?? DEFAULTS.probeTimeout,
-    probePollEvery: options.probePollEvery ?? DEFAULTS.probePollEvery,
-    escalationSlaTimeout: options.escalationSlaTimeout ?? DEFAULTS.escalationSlaTimeout,
+    nodeTimeout: isoDuration(options.nodeTimeout, DEFAULTS.nodeTimeout),
+    probeTimeout: isoDuration(options.probeTimeout, DEFAULTS.probeTimeout),
+    probePollEvery: isoDuration(options.probePollEvery, DEFAULTS.probePollEvery),
+    escalationSlaTimeout: isoDuration(options.escalationSlaTimeout, DEFAULTS.escalationSlaTimeout),
     escalationAssignee: options.escalationAssignee ?? null,
   };
   const elementByNodeId = new Map(compiled.resolved.nodes.map((n) => [n.id, n.element]));
@@ -174,7 +178,7 @@ function buildNodeInput(
 ): NodeInput {
   switch (node.kind) {
     case "agent":
-      return { jobType: node.agent.jobType, appendPrompt: node.agent.prompt ?? "", timeout: ctx.nodeTimeout };
+      return { jobType: node.agent.jobType, appendPrompt: node.agent.prompt ?? "", timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
     case "wait": {
       const probe = parseProbe(node.wait);
       return {
@@ -201,7 +205,7 @@ function buildNodeInput(
         target: node.connector.target,
         dedupeKey: node.connector.dedupeKey ?? null,
         payload: node.connector.payload ?? null,
-        timeout: ctx.nodeTimeout,
+        timeout: isoDuration(node.connector.timeout, ctx.nodeTimeout),
       };
     default:
       return assertNever(node, "buildNodeInput");

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