@nanobpm/nano-workforce 0.133.0 → 0.134.0

package/app/reviewWait.ts

@@ -20,6 +20,14 @@ export const DEFAULT_REVIEW_WAIT_TIMEOUT = "PT20M";
 // would fail to interpret; not a full grammar (we don't need fractional seconds here).
 const ISO_DURATION = /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/;
 
+/** True when `raw` is a well-formed ISO-8601 duration under {@link isoDuration}'s grammar — the strict
+ * predicate an operator submission door uses to REJECT a malformed duration (400) rather than silently
+ * fall back to a default. Derives from the same {@link ISO_DURATION} grammar so the accept/reject
+ * decision can never drift from the normalise-or-default one. Case-insensitive (`pt2h` is valid). */
+export function isValidIsoDuration(raw: string): boolean {
+  return ISO_DURATION.test(raw.trim().toUpperCase());
+}
+
 /** Validate an ISO-8601 duration string for a BPMN timer's `<bpmn:timeDuration>`, falling back to
  * `def` when the value is absent, blank, or malformed — a bad env value must never deploy an
  * uninterpretable timer expression into a process. Normalises to upper case (`pt20m` → `PT20M`).

package/app/service.ts

@@ -511,7 +511,14 @@ export async function submitPr(
 ) {
   const table = prs(data);
   const existing = await table.get(parsed.prKey);
-  if (existing && !TERMINAL_STATUSES.includes(existing.status)) {
+  // ADR-0065: classify "already running" on the DERIVED terminal edge, not the base transient. A
+  // PR 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 its last worker transient (e.g. `converging`) but a
+  // `pull_requests__tracking.derived_status` of `abandoned`; reading the base `status` here would wedge
+  // it `alreadyRunning` forever (the #497 phantom). Route the idempotency gate through the derived view
+  // so a cancelled PR is correctly seen terminal and RESUBMITTABLE.
+  const trackedExisting = existing ? await prsTracking(data).get(parsed.prKey) : undefined;
+  if (trackedExisting && !TERMINAL_STATUSES.includes(trackedExisting.derived_status)) {
     return { prKey: parsed.prKey, alreadyRunning: true };
   }
 
@@ -747,9 +754,17 @@ export interface ActivePr {
  * BOTH loops' escalations uniformly. Once answered the row leaves `open`, so `openEscalation`
  * derives back to null. */
 export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
-  const all = await prs(data).all();
+  const all = await prsTracking(data).all();
   const active = all
-    .filter((p) => !TERMINAL_STATUSES.includes(p.status))
+    // ADR-0065: classify "in flight" on the DERIVED terminal edge, not the base transient. A PR whose
+    // engine instance was terminated out-of-band (or by an ordinary in-app cancel — derive-only under
+    // urban 0.81.0) keeps its base `status` frozen at the last worker transient but reads `abandoned`
+    // on `pull_requests__tracking.derived_status`; filtering on the base `status` here left the
+    // Convergence tab showing a cancelled PR active indefinitely (the #497 phantom). The base
+    // `status`/worker-owned transient columns are still surfaced on each row below (the view re-exports
+    // `base.*`), and `pull_requests` has no `onWaitingHuman` edge, so for a still-active PR
+    // `derived_status === status`.
+    .filter((p) => !TERMINAL_STATUSES.includes(p.derived_status))
     .sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0));
   // Only an `escalated` PR is parked awaiting a human answer (either loop). Surface the question
   // from its latest still-open `escalations` row; a resubmit retires stale rows and finalize/merge
@@ -972,9 +987,9 @@ async function classifyWaveTarget(
   prKey: string,
   token: string,
 ): Promise<"cleared" | "closed" | "pending"> {
-  const tracked = await prs(data).get(prKey);
-  if (tracked && tracked.status === "merged") return "cleared";
-  if (tracked && tracked.status === ABANDONED_STATUS) return "cleared"; // already reconciled terminal → non-blocking, no re-reconcile needed
+  const tracked = await prsTracking(data).get(prKey);
+  if (tracked && tracked.status === "merged") return "cleared"; // worker-owned terminal, passes through the derive edge unchanged
+  if (tracked && tracked.derived_status === ABANDONED_STATUS) return "cleared"; // ADR-0065 derive-only terminal → non-blocking, no re-reconcile needed
   const parsed = parsePr(prKey);
   if (!parsed) return "cleared"; // unparseable ref can't be checked → never wedge the barrier
   let st: Awaited<ReturnType<typeof fetchPrState>>;
@@ -1016,7 +1031,7 @@ async function flipToMergingThenPublish(
   }
 }
 
-async function mergeLaneDecisionForPr(data: DataLayer, prKey: string): Promise<PrLaneDecision | null> {
+export async function mergeLaneDecisionForPr(data: DataLayer, prKey: string): Promise<PrLaneDecision | null> {
   const taskRows = await planTasks(data).find({ pr_key: prKey });
   const task = taskRows[0];
   if (!task) return null;
@@ -1034,8 +1049,12 @@ async function mergeLaneDecisionForPr(data: DataLayer, prKey: string): Promise<P
   const lanePrKeys = new Set([...taskToPr.values()]);
   const completedPrKeys = new Set<string>();
   for (const lanePrKey of lanePrKeys) {
-    const lanePr = await prs(data).get(lanePrKey);
-    if (lanePr && (lanePr.status === "merged" || lanePr.status === "abandoned")) {
+    const lanePr = await prsTracking(data).get(lanePrKey);
+    // ADR-0065: a lane member is complete when it MERGED (worker-owned terminal, base `status`) OR was
+    // cancelled/terminated (derive-only terminal → `derived_status === "abandoned"`; the base row is
+    // still frozen at its transient). Reading only base `status` here missed a cancelled member and
+    // stalled/misrouted the lane.
+    if (lanePr && (lanePr.status === "merged" || lanePr.derived_status === "abandoned")) {
       completedPrKeys.add(lanePr.pr_key);
     }
   }
@@ -1400,12 +1419,15 @@ async function pollJobActivation(
   const headers: Record<string, string> = { "content-type": "application/json" };
   if (engineToken) headers.authorization = `Bearer ${engineToken}`;
 
-  const all = await prs(data).all();
+  const all = await prsTracking(data).all();
   for (const pr of all) {
     // Only a `converging` PR has a live review-round job. Any other status with a stale worker
     // set (e.g. it just moved to `waiting_review`) gets cleared so the grid can't show a
-    // phantom "agent working".
-    if (pr.status !== "converging") {
+    // phantom "agent working". ADR-0065: classify on the DERIVED status, not the base transient —
+    // a PR whose instance was terminated out-of-band keeps its base `status` frozen at `converging`
+    // but reads `abandoned` on `derived_status`, so a base read would leave `active_worker`/
+    // `lease_until` set on a dead run (a phantom "agent working"). Writes stay on the base `prs`.
+    if (pr.derived_status !== "converging") {
       if (pr.active_worker || pr.lease_until) {
         await prs(data).update(pr.pr_key, {
           active_worker: null,
@@ -1512,13 +1534,16 @@ export async function pollIncidentsImpl(
   base: string,
   headers: Record<string, string>,
 ) {
-  const all = await prs(data).all();
+  const all = await prsTracking(data).all();
   for (const pr of all) {
     // No live instance to inspect (never created, mid-transition, or terminal — the run has
     // finished or was given up, so its instance is gone) → make sure no stale incident lingers on
-    // the row, then move on. Reuses the canonical `TERMINAL_STATUSES` so incident logic can't drift
-    // from the rest of the status machine.
-    if (!pr.process_key || TERMINAL_STATUSES.includes(pr.status)) {
+    // the row, then move on. ADR-0065: classify on the DERIVED terminal edge, not the base transient
+    // — a PR terminated out-of-band keeps its base `status` frozen at `converging` but reads
+    // `abandoned` on `derived_status`, so a base read would keep reconciling incidents against a dead
+    // instance. Reuses the canonical `TERMINAL_STATUSES` so incident logic can't drift from the rest
+    // of the status machine. Writes stay on the base `prs`.
+    if (!pr.process_key || TERMINAL_STATUSES.includes(pr.derived_status)) {
       if (pr.incident_key || pr.incident_message) {
         await prs(data).update(pr.pr_key, {
           incident_key: null,

package/app/stage.ts

@@ -14,7 +14,7 @@
 // anywhere (not in SQL, not in the page, not in each poller/worker): every reader flows through the
 // VIEW or these adapters, both sourced from the one declaration.
 
-import { type FeatureReadModelDerivedColumn, featureReadModel, STAGE_DONE_STATUSES, USER_TASKS_PROJECTION } from "./featureReadModel.ts";
+import { EFFECTIVE_STATUS_COLUMN, type FeatureReadModelDerivedColumn, featureReadModel, STAGE_DONE_STATUSES, USER_TASKS_PROJECTION } from "./featureReadModel.ts";
 
 // Re-exported for back-compat with existing importers (operations/acknowledgeDone.ts). Its canonical
 // home is now app/featureReadModel.ts, where it feeds the terminal tier of the derived columns.
@@ -90,7 +90,12 @@ function evalDerived<T>(column: FeatureReadModelDerivedColumn, baseRow: Record<s
 export function deriveStage(run: StageInput): DerivedStage {
   const baseRow = {
     feature_key: SELF_KEY,
-    status: run.status,
+    // The status-classifying derivations read the tracking VIEW's terminal-folded `derived_status`
+    // (ADR-0065), so this façade feeds the caller's effective `status` under that column name — the SQL
+    // VIEW reads `fr."derived_status"` off `feature_runs__tracking`, and both lowerings agree by
+    // construction (`assertReadModelParity`). Callers off the write path pass the run's effective
+    // status (which equals the base transient for any non-terminated run).
+    [EFFECTIVE_STATUS_COLUMN]: run.status,
     pr_key: run.pr_key ?? null,
     converge: run.converge ?? null,
     auto_merge: run.auto_merge ?? null,
@@ -111,5 +116,5 @@ export function deriveStage(run: StageInput): DerivedStage {
  * `feature_runs.list_bucket` base column is vestigial (retired as a write projection, issue #439). This
  * adapter is the TS lowering of that derivation, used off the write path (redispatch gating, tests). */
 export function deriveListBucket(status: string, acknowledgedAt: string | null | undefined): "active" | "history" {
-  return evalDerived<"active" | "history">("list_bucket", { status, acknowledged_at: acknowledgedAt ?? null });
+  return evalDerived<"active" | "history">("list_bucket", { [EFFECTIVE_STATUS_COLUMN]: status, acknowledged_at: acknowledgedAt ?? null });
 }

package/app/terminalReaderBehaviour.test.ts

@@ -0,0 +1,289 @@
+// Behaviour coverage for issue #503 — the ADR-0065 derive-only-terminal divergence at the terminal
+// EDGE readers. Under `@nanobpm/urban@0.81.0` the `instanceTracking` reconciler no longer WRITES the
+// terminal `abandoned`/`failed`/`reviewed` onto the base `status`; it re-derives it on read via the
+// `<table>__tracking.derived_status` VIEW. A PR/plan whose engine instance was terminated out-of-band
+// (or by an ordinary in-app cancel) therefore keeps its base `status` frozen at its last worker
+// transient (e.g. `converging`/`dispatched`) while `derived_status` reads `abandoned`.
+//
+// Each test seeds that EXACT divergence (base row `status: "converging"`, `derived_status: "abandoned"`)
+// via the `withTrackingViews` seam, and asserts the reader classifies on the derived edge:
+//   - a terminated PR is RESUBMITTABLE (not wedged `alreadyRunning`) and absent from `activePrs`,
+//   - a terminated instance sheds its stale incident,
+//   - a terminated lane member counts as COMPLETE (does not stall the merge lane),
+//   - a terminated epic is not counted active (no false same-base conflict) and is RE-ADMITTABLE.
+// Reading only the base `status` (the pre-#503 behaviour) fails every one of these — the RED.
+
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { withTrackingViews } from "../test/trackingViews.ts";
+import { findActivePlansByBase, startPlan } from "./plan.ts";
+import { activePrs, mergeLaneDecisionForPr, pollIncidentsImpl, pollWaveGatesImpl, submitPr } from "./service.ts";
+
+function memTable(rows: any[], key: string) {
+  return {
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    all: () => Promise.resolve([...rows]),
+    find: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    findOne: (q: any) =>
+      Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v)) ?? null),
+    count: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)).length),
+    insert: (r: any) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r);
+    },
+    delete: (k: any) => {
+      for (let i = rows.length - 1; i >= 0; i--) if (rows[i][key] === k) rows.splice(i, 1);
+      return Promise.resolve();
+    },
+  };
+}
+
+type Stores = Record<string, { rows: any[]; key: string }>;
+
+function memData(stores: Stores) {
+  return {
+    table: withTrackingViews((name: string, key: string) =>
+      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
+  } as any;
+}
+
+function withGithubOff(run: () => Promise<void>): Promise<void> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token"; // no token below -> fetchPrMeta returns null
+  delete process.env["GITHUB_TOKEN"];
+  return run().finally(() => {
+    if (prevMode !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
+  });
+}
+
+// #503 / #497: `submitPr`'s idempotency gate reads `derived_status`, so a derive-only-terminated PR
+// (base frozen at `converging`, `derived_status = abandoned`) is seen terminal and RESUBMITTABLE —
+// it re-opens for a fresh convergence run instead of wedging `alreadyRunning`.
+test("submitPr re-opens a derive-only-terminated PR (base 'converging', derived 'abandoned') — not alreadyRunning", async () => {
+  await withGithubOff(async () => {
+    const PR_KEY = "owner/repo#42";
+    const stores: Stores = {
+      pull_requests: {
+        rows: [{
+          pr_key: PR_KEY,
+          repo: "owner/repo",
+          number: 42,
+          url: "https://github.com/owner/repo/pull/42",
+          title: "t",
+          status: "converging", // base transient FROZEN — reconciler no longer writes the terminal
+          derived_status: "abandoned", // ADR-0065 derive-only terminal
+          current_round: 3,
+        }],
+        key: "pr_key",
+      },
+      escalations: { rows: [], key: "id" },
+      pr_dependencies: { rows: [], key: "pr_key" },
+    };
+    const data = memData(stores);
+    const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-9" }) } as any;
+
+    const res = await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 42,
+      url: "https://github.com/owner/repo/pull/42",
+      prKey: PR_KEY,
+    });
+
+    assertEquals((res as any).alreadyRunning, undefined); // NOT wedged
+    assertEquals(res.processKey, "PI-9");
+    const pr = stores.pull_requests.rows[0];
+    assertEquals(pr.status, "converging");
+    assertEquals(pr.current_round, 1); // re-opened for a fresh run
+    assertEquals(pr.process_key, "PI-9");
+  });
+});
+
+// #503 / #497 phantom: `activePrs` filters on `derived_status`, so a derive-only-terminated PR drops
+// off the Convergence tab instead of showing "active" indefinitely.
+test("activePrs excludes a derive-only-terminated PR and keeps a genuinely active one", async () => {
+  const stores: Stores = {
+    pull_requests: {
+      rows: [
+        { pr_key: "o/r#1", repo: "o/r", number: 1, url: "u1", status: "converging", derived_status: "abandoned", current_round: 2, updated_at: "2024-01-02" },
+        { pr_key: "o/r#2", repo: "o/r", number: 2, url: "u2", status: "converging", derived_status: "converging", current_round: 1, updated_at: "2024-01-01" },
+      ],
+      key: "pr_key",
+    },
+    escalations: { rows: [], key: "id" },
+  };
+  const active = await activePrs(memData(stores));
+  assertEquals(active.map((p) => p.prKey), ["o/r#2"]);
+});
+
+// #503: `pollIncidentsImpl` classifies a dead instance on `derived_status`, so a derive-only-terminated
+// PR sheds its stale incident (rather than re-reconciling against a gone instance), and NEVER queries
+// the engine for it. A live PR still gets queried.
+test("pollIncidentsImpl clears a stale incident off a derive-only-terminated PR without querying the engine", async () => {
+  const stores: Stores = {
+    pull_requests: {
+      rows: [{
+        pr_key: "o/r#7",
+        repo: "o/r",
+        number: 7,
+        url: "u",
+        status: "converging",
+        derived_status: "abandoned",
+        process_key: "PI-DEAD",
+        incident_key: "INC-1",
+        incident_message: "boom",
+      }],
+      key: "pr_key",
+    },
+  };
+  const prevFetch = globalThis.fetch;
+  let queried = false;
+  globalThis.fetch = (() => {
+    queried = true;
+    throw new Error("engine must not be queried for a derive-only-terminated PR");
+  }) as any;
+  try {
+    await pollIncidentsImpl(memData(stores), "http://engine", {});
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(queried, false);
+  const pr = stores.pull_requests.rows[0];
+  assertEquals(pr.incident_key, null);
+  assertEquals(pr.incident_message, null);
+});
+
+// #503: the merge-lane decision counts a lane member COMPLETE on the derived terminal edge, so a
+// derive-only-abandoned member (base 'converging') no longer holds its lane-mate behind a dead PR.
+test("mergeLaneDecisionForPr treats a derive-only-abandoned lane member as complete (does not hold the lane)", async () => {
+  const PLAN_KEY = "o/r#100";
+  const stores: Stores = {
+    plan_tasks: {
+      rows: [
+        { id: 1, plan_key: PLAN_KEY, task_id: "a", pr_key: "o/r#1" },
+        { id: 2, plan_key: PLAN_KEY, task_id: "b", pr_key: "o/r#2" },
+      ],
+      key: "id",
+    },
+    plan_merge_exclusions: {
+      // a & b collide on a shared surface → one landing lane, land one-at-a-time
+      rows: [{ id: 1, plan_key: PLAN_KEY, task_a: "a", task_b: "b", files: JSON.stringify(["shared.ts"]), source: "file-overlap" }],
+      key: "id",
+    },
+    plan_task_deps: { rows: [], key: "plan_key" },
+    pull_requests: {
+      rows: [
+        // lane head candidate `a`: derive-only-terminated (base frozen, derived abandoned)
+        { pr_key: "o/r#1", repo: "o/r", number: 1, status: "converging", derived_status: "abandoned" },
+        // `b`: the PR we ask about — still converging
+        { pr_key: "o/r#2", repo: "o/r", number: 2, status: "converging", derived_status: "converging" },
+      ],
+      key: "pr_key",
+    },
+  };
+  const decision = await mergeLaneDecisionForPr(memData(stores), "o/r#2");
+  // With `a` counted complete, `b` is free to land — NOT held behind the dead member.
+  assertEquals(decision?.isHeld, false);
+});
+
+// #503: `classifyWaveTarget` classifies a wave member on the derived terminal edge, so a
+// derive-only-abandoned member (base frozen at `converging`, still notionally open) is treated
+// NON-BLOCKING (`cleared`) WITHOUT a GitHub round-trip — the wave gate advances instead of wedging on
+// a dead member. Driven through `pollWaveGatesImpl`: with the sole gate member cleared and the token
+// parked at `wait-wave-merged`, the barrier is released (`wave-merged` published). Reading the base
+// `status` (the RED) would fall through to a GitHub liveness read (which, with no live "merged"
+// signal, returns `pending`) and never publish.
+test("classifyWaveTarget treats a derive-only-abandoned wave member as cleared and releases the gate (no GitHub read)", async () => {
+  await withGithubOff(async () => {
+    const PLAN_KEY = "o/r#200";
+    const stores: Stores = {
+      plans: { rows: [{ plan_key: PLAN_KEY, gate_wave: 0, process_key: "PI-1" }], key: "plan_key" },
+      plan_tasks: {
+        rows: [{ id: 1, plan_key: PLAN_KEY, task_id: "a", wave: 0, status: "opened", pr_key: "o/r#1" }],
+        key: "id",
+      },
+      pull_requests: {
+        rows: [{ pr_key: "o/r#1", repo: "o/r", number: 1, status: "converging", derived_status: "abandoned" }],
+        key: "pr_key",
+      },
+    };
+    const published: unknown[] = [];
+    const engine = { publishMessage: (m: unknown) => (published.push(m), Promise.resolve()) } as any;
+    const prevFetch = globalThis.fetch;
+    // Confirm the token is parked at the `wave-merged` wait so the barrier is releasable; a GitHub
+    // liveness read for the abandoned member would be a bug (it's classified `cleared` off the view).
+    globalThis.fetch = ((url: string) => {
+      if (String(url).endsWith("/message-subscriptions/search")) {
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({ items: [{ messageName: "wave-merged", correlationKey: PLAN_KEY, messageSubscriptionState: "CREATED" }] }),
+            { status: 200, headers: { "content-type": "application/json" } },
+          ),
+        );
+      }
+      throw new Error(`no GitHub read expected for a derive-only-abandoned wave member: ${url}`);
+    }) as any;
+    try {
+      await pollWaveGatesImpl(memData(stores), engine, "", "http://engine", {});
+    } finally {
+      globalThis.fetch = prevFetch;
+    }
+    assertEquals(published.length, 1); // wave released — the abandoned member did not block it
+  });
+});
+
+
+// derive-only-abandoned epic (base frozen at `dispatched`) is NOT counted active and raises no false
+// same-base conflict.
+test("findActivePlansByBase excludes a derive-only-abandoned epic", async () => {
+  const stores: Stores = {
+    plans: {
+      rows: [
+        { plan_key: "o/r#10", repo: "o/r", base_branch: "epic/x", status: "dispatched", derived_status: "abandoned" },
+        { plan_key: "o/r#11", repo: "o/r", base_branch: "epic/x", status: "dispatched", derived_status: "dispatched" },
+      ],
+      key: "plan_key",
+    },
+  };
+  const active = await findActivePlansByBase(memData(stores), "o/r", "epic/x");
+  assertEquals(active.map((p) => p.plan_key), ["o/r#11"]);
+});
+
+// #503: `startPlan`'s idempotency gate reads `derived_status`, so a derive-only-abandoned epic (base
+// frozen at `dispatched`) is seen terminal and RE-ADMITTABLE — it re-plans instead of wedging
+// `alreadyRunning`.
+test("startPlan re-admits a derive-only-abandoned epic (base 'dispatched', derived 'abandoned') — not alreadyRunning", async () => {
+  await withGithubOff(async () => {
+    const PLAN_KEY = "owner/repo#7";
+    const stores: Stores = {
+      plans: {
+        rows: [{ plan_key: PLAN_KEY, repo: "owner/repo", base_branch: "epic/x", status: "dispatched", derived_status: "abandoned", task_count: 1 }],
+        key: "plan_key",
+      },
+      plan_tasks: { rows: [{ id: 1, plan_key: PLAN_KEY }], key: "id" },
+      plan_reviews: { rows: [], key: "plan_key" },
+      plan_task_deps: { rows: [], key: "plan_key" },
+    };
+    const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-1" }) } as any;
+
+    const res = await startPlan(memData(stores), engine, {
+      repo: "owner/repo",
+      number: 7,
+      url: "https://github.com/owner/repo/issues/7",
+      planKey: PLAN_KEY,
+    }, "epic/x");
+
+    assertEquals((res as any).alreadyRunning, undefined); // NOT wedged — re-planned
+    // The prior epic's tasks were cleared on the re-plan path (proves it did NOT short-circuit).
+    assertEquals(stores.plan_tasks.rows.length, 0);
+  });
+});

package/app/terminalReaderGuard.test.ts

@@ -0,0 +1,106 @@
+// Class guard for the ADR-0065 terminal-edge reader migration (issue #503).
+//
+// Since ADR-0065 (`@nanobpm/urban@0.81.0`) the `instanceTracking` reconciler is a SOURCE, not a
+// writer: on cancel/terminate it feeds urban's instance projection and the terminal edge
+// (`onTerminated`) is RECOMPUTED ON READ as `<table>__tracking.derived_status` — it NO LONGER writes
+// the terminal (`abandoned`/`failed`/`reviewed`) onto the base `status` column. A classifying reader
+// that inspects the BASE `status` column of a DERIVE-ONLY tracked table therefore sees a row frozen at
+// its last worker-owned transient after the instance ends → phantom-active / wedged-idempotency bugs
+// (the #497 / #503 class).
+//
+// This is a SOURCE-SCAN guard over the defect CLASS, not a single instance: it asserts that every
+// terminal/active classification (`TERMINAL_STATUSES.includes` / `=== ABANDONED_STATUS` /
+// `PLAN_TERMINAL_STATUSES` / the feature read model's status DSL) for the three derive-only tracked
+// tables (`pull_requests`, `plans`, `feature_runs`) reads the DERIVED effective status
+// (`.derived_status`), never the frozen base `.status`. A future reader that silently re-drifts onto
+// the base column fails here.
+//
+// Worker-owned terminals that PASS THROUGH the derive edge unchanged (`merged`) are exempt: a base
+// `=== "merged"` read is legitimate (see `isDepMerged` / `classifyWaveTarget` / `mergeLaneDecisionForPr`
+// in app/service.ts). Only the DERIVE-ONLY terminals (`abandoned`/`failed`/`reviewed`) must route
+// through the derived accessor. Writers (`data.table(<table>).update({ status: … })`) are unaffected —
+// they still write the base column.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { EFFECTIVE_STATUS_COLUMN } from "./featureReadModel.ts";
+
+const SRC = (name: string): string => readFileSync(fileURLToPath(new URL(`./${name}`, import.meta.url)), "utf8");
+
+/** Strip line (`//`) and block (`/* … *​/`) comments so the scan only inspects executable code — a
+ * doc comment may legitimately mention `.status` in prose without being a classification. The line
+ * stripper skips a `//` preceded by `:` so a URL scheme inside a string/template literal (e.g.
+ * `https://…` in app/service.ts) is not mistaken for a comment start and does not corrupt the scan. */
+function stripComments(src: string): string {
+  return src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+
+test("class guard: every TERMINAL_STATUSES classification in service.ts reads derived_status, not base status", () => {
+  const code = stripComments(SRC("service.ts"));
+  const calls = [...code.matchAll(/TERMINAL_STATUSES\.includes\(([^)]*)\)/g)];
+  assert(calls.length > 0, "expected TERMINAL_STATUSES.includes classifications in service.ts");
+  for (const m of calls) {
+    const arg = m[1];
+    assert(
+      /\.derived_status\b/.test(arg),
+      `TERMINAL_STATUSES.includes(${arg}) classifies on the BASE status of a derive-only tracked table — ` +
+        `route it through prsTracking and read \`.derived_status\` (ADR-0065, #503)`,
+    );
+    assert(
+      !/[A-Za-z0-9_)\]]\.status\b/.test(arg),
+      `TERMINAL_STATUSES.includes(${arg}) still reads a base \`.status\` — the terminal edge is derive-only (#503)`,
+    );
+  }
+});
+
+test("class guard: no base `.status === ABANDONED_STATUS` / `.status === \"abandoned\"` read classification in service.ts", () => {
+  const code = stripComments(SRC("service.ts"));
+  // A READ classification against the derive-only `abandoned` terminal must use `.derived_status`. A
+  // base `.status === ABANDONED_STATUS`/`"abandoned"` would miss a derive-only-terminated PR. (Writers
+  // use the object-literal form `{ status: ABANDONED_STATUS }`, which this pattern never matches.)
+  const bad = [
+    ...code.matchAll(/[A-Za-z0-9_)\]]\.status\s*===\s*ABANDONED_STATUS/g),
+    ...code.matchAll(/[A-Za-z0-9_)\]]\.status\s*===\s*["']abandoned["']/g),
+  ];
+  assertEquals(
+    bad.length,
+    0,
+    `a base \`.status\` is compared to the derive-only \`abandoned\` terminal — read \`.derived_status\` off ` +
+      `prsTracking instead (ADR-0065, #503): ${bad.map((m) => m[0]).join(", ")}`,
+  );
+});
+
+test("class guard: every PLAN_TERMINAL_STATUSES classification in plan.ts reads derived_status, not base status", () => {
+  const code = stripComments(SRC("plan.ts"));
+  // Match the `.some((s) => s === <ref>)` classification form used at both admission sites.
+  const calls = [...code.matchAll(/PLAN_TERMINAL_STATUSES\.some\(\([^)]*\)\s*=>\s*[^)]*===\s*([A-Za-z0-9_.]+)\)/g)];
+  assert(calls.length > 0, "expected PLAN_TERMINAL_STATUSES classifications in plan.ts");
+  for (const m of calls) {
+    const ref = m[1];
+    assert(
+      /\.derived_status$/.test(ref),
+      `PLAN_TERMINAL_STATUSES classification reads \`${ref}\` — route it through plansTracking and read ` +
+        `\`.derived_status\` so a derive-only-terminated epic is seen terminal (ADR-0065, #503)`,
+    );
+  }
+});
+
+test("class guard: the feature read model classifies on derived_status, never the base status column", () => {
+  // The feature history read model (app/featureReadModel.ts) buckets a run's pipeline `stage`/
+  // `list_bucket` off its status. Under ADR-0065 that must be the terminal-folded `derived_status`
+  // (off `feature_runs__tracking`), or a terminated run renders "Implementing" forever. Assert the DSL
+  // never references the base `col("status")` for classification and that the effective-status column
+  // is the derived one.
+  assertEquals(EFFECTIVE_STATUS_COLUMN, "derived_status", "the feature read model's effective status must be the derived column");
+  const code = stripComments(SRC("featureReadModel.ts"));
+  assert(
+    !/col\(\s*["']status["']\s*\)/.test(code),
+    'app/featureReadModel.ts still references col("status") — the status-classifying derivations must ' +
+      'read col("derived_status") off feature_runs__tracking (ADR-0065, #503)',
+  );
+  assert(
+    /baseTable:\s*FEATURE_READ_MODEL_BASE_TABLE/.test(code) || /feature_runs__tracking/.test(code),
+    "the feature read model must be based on the feature_runs__tracking derived VIEW (ADR-0065, #503)",
+  );
+});

package/db/migrations/080_plan_read_model_derive_terminal.sql

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