@nanobpm/nano-workforce 0.132.0 → 0.133.1

package/app/service.test.ts

@@ -11,7 +11,9 @@ import { memDataFor } from "../test/worldDb.ts";
 import { withTrackingViews } from "../test/trackingViews.ts";
 import { DurableResumeRegistry } from "./durableResume.ts";
 import { WorldStore } from "./world/index.ts";
-import { abandonClosedPr, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
+import { abandonClosedPr, isPrSettled, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
+import { trackingTargetFor } from "./instanceTracking.ts";
+import type { DataLayer } from "@nanobpm/urban";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -49,6 +51,31 @@ function withGithubOff(run: () => Promise<void>): Promise<void> {
   });
 }
 
+test("isPrSettled reads the derived tracking view — an out-of-band-abandoned PR (base row still converging) is settled", async () => {
+  // The base `pull_requests` row still reads `converging`, but the ADR-0065 derived tracking VIEW
+  // folds the reconciler's out-of-band terminal edge into `derived_status: "abandoned"`. Terminal-edge
+  // classification must read `derived_status`, not the stale base `status`, or a crash-window RESUME
+  // of the delivery-connector enrollment action re-runs `submitPr` against a PR that has actually
+  // already settled (and the ledger detail falsely claims it enrolled).
+  const PR_KEY = "owner/repo#7";
+  const view = trackingTargetFor("pull_requests").view;
+  const base = { pr_key: PR_KEY, status: "converging" };
+  function make(derived: string) {
+    return {
+      table(name: string) {
+        if (name === "pull_requests") return { get: async (k: string) => (k === PR_KEY ? { ...base } : null) };
+        if (name === view) return { get: async (k: string) => (k === PR_KEY ? { ...base, derived_status: derived } : null) };
+        throw new Error(`unexpected table ${name}`);
+      },
+    } as any as DataLayer;
+  }
+  assertEquals(await isPrSettled(make("abandoned"), PR_KEY), true, "out-of-band-abandoned PR is settled via derived_status");
+  assertEquals(await isPrSettled(make("converging"), PR_KEY), false, "a genuinely live PR is not settled");
+  const empty = { table: () => ({ get: async () => null }) } as any as DataLayer;
+  assertEquals(await isPrSettled(empty, PR_KEY), false, "an absent PR row is not settled");
+});
+
+
 test("re-submit of a cancelled PR marks stale open escalations", async () => {
   await withGithubOff(async () => {
     const PR_KEY = "owner/repo#42";

package/app/service.ts

@@ -482,6 +482,21 @@ export async function worldRestoreSha(data: DataLayer, prKey: string): Promise<s
   return lastPushedSha(data, prKey);
 }
 
+/** Whether the `pull_requests` row for `prKey` already exists AND is in a TERMINAL state
+ * (`converged`/`merged`/`abandoned`). Reads the ADR-0065 derived tracking VIEW's `derived_status`
+ * (via `prsTracking`), NOT the base `status`, so an out-of-band-terminated PR — whose base row is
+ * still `converging` but whose reconciled edge is `abandoned` — is correctly seen as settled. The
+ * delivery-connector's converge-enrollment action guards on this so a crash-window RESUME (a
+ * `claimed`-but-not-`delivered` ledger row whose first attempt already enrolled the PR and let it
+ * settle) never re-runs `submitPr` against a settled PR — `submitPr` deliberately RE-OPENS a terminal
+ * row, so an unconditional re-perform would flip the PR back to `converging`, regressing a settled PR.
+ * Reuses the canonical `TERMINAL_STATUSES` so the terminal-safety check can't drift from the one the
+ * loop/incident logic uses. */
+export async function isPrSettled(data: DataLayer, prKey: string): Promise<boolean> {
+  const existing = await prsTracking(data).get(prKey);
+  return !!existing && TERMINAL_STATUSES.includes(existing.derived_status);
+}
+
 /** Register a PR row (if new) and start the convergence process. Idempotent on prKey. Optional
  * `dependsOn` (explicit refs) is unioned with any `Depends-on:` line parsed from the PR body and
  * recorded as the PR's merge-stage dependency set. */
@@ -496,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 };
   }
 
@@ -732,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
@@ -957,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>>;
@@ -1001,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;
@@ -1019,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);
     }
   }
@@ -1385,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,
@@ -1497,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)",
+  );
+});