@nanobpm/nano-workforce 0.189.1 → 0.189.3

package/app/featureReadModel.ts

@@ -31,16 +31,32 @@
 // LATER ADR-0065 rollout steps (3/4), deliberately out of scope here.
 
 import { and, caseWhen, col, defineReadModel, type Expr, eq, exists, lit, neq, not, or, pcol, type ReadModel, when } from "@nanobpm/urban";
-import { deriveAckOpenExpr, deriveListBucketExpr } from "./listBucket.ts";
+import { deriveAckOpenFromTerminal, deriveListBucketFromTerminal, terminalStatusIn } from "./listBucket.ts";
 
 /** The 6 TRULY-terminal statuses that map to the `Done` stage — the single source of truth for the
- * terminal tier of BOTH the pipeline `stage`/`stage_state` derivations and the `list_bucket` history
- * partition. Distinct from `FEATURE_TERMINAL_STATUSES` (app/feature.ts), the redispatch-settled set,
- * which also counts `opened`/`converging` as terminal — those are LIVE pipeline stages (`PR open`/
- * `Converging`), NOT `Done`, so the two lists must stay separate. Re-exported from app/stage.ts for
- * back-compat with its existing importers. */
+ * terminal tier of the pipeline `stage`/`stage_state` derivations (and the `stepAxis` render tier).
+ * Distinct from `FEATURE_TERMINAL_STATUSES` (app/feature.ts), the redispatch-settled set, which also
+ * counts `opened`/`converging` as terminal — those are LIVE pipeline stages (`PR open`/`Converging`),
+ * NOT `Done`, so the two lists stay separate for the STAGE derivations. Re-exported from app/stage.ts
+ * for back-compat with its existing importers.
+ *
+ * NOTE — the Active/History `list_bucket`/`ack_open` derivations do NOT use this set; they use the
+ * WIDER {@link FEATURE_ACK_TERMINAL_STATUSES} (issue #808). The dismissable-terminal set is
+ * deliberately decoupled from the pipeline `Done` set: a raise-only run that ends at `opened` is a live
+ * `PR open` STAGE yet a FINISHED run that must be acknowledgeable into History. */
 export const STAGE_DONE_STATUSES: readonly string[] = ["merged", "converged", "blocked", "failed", "skipped", "abandoned"];
 
+/** The status-set half of the DISMISSABLE-terminal predicate for the Active/History `list_bucket` +
+ * operator-`ack_open` derivations (issue #808) — the pipeline `Done` set ({@link STAGE_DONE_STATUSES})
+ * PLUS `opened`. A run folded to `opened` (a PR was raised) is dismissable-terminal, so it can drop to
+ * History on dismissal even though the pipeline still renders it in the LIVE `PR open` STAGE (which
+ * classifies on {@link STAGE_DONE_STATUSES}, so `opened` stays `PR open`, never `Done`). This is WIDER
+ * than `STAGE_DONE_STATUSES` (adds `opened`) and NARROWER than `FEATURE_TERMINAL_STATUSES` (excludes
+ * `converging`, still live in the convergence loop). NOTE — the derivation does NOT dismiss EVERY
+ * `opened` row on this set alone: an `opened` row that is still mid-handoff to the convergence loop is
+ * excluded by {@link featureDismissableTerminal} (see there). Exported for the drift/parity tests. */
+export const FEATURE_ACK_TERMINAL_STATUSES: readonly string[] = [...STAGE_DONE_STATUSES, "opened"];
+
 /** The DSL projection name the `attention` derivation `exists(...)`-reads. Unregistered in the
  * `projectionRegistry`, so it resolves to the same-named physical table — the app's own `user_tasks`
  * inbox (034_user_tasks_inbox.sql), reconciled by `pollUserTasks` (app/service.ts): a row exists IFF a
@@ -129,21 +145,69 @@ const attention: Expr = caseWhen(
   lit(null),
 );
 
-/** The Active/History partition: `history` IFF the row is in a truly-terminal status AND has been
+/** The one transient to EXCLUDE from the dismissable-terminal set: an `opened` row still mid-handoff
+ * into the convergence loop.
+ *
+ * Why (issue #808 follow-up): `record-feature` writes `status="opened"` for a converge-REQUESTED run
+ * too, BEFORE `gw-converge` routes it into `converge-feature` (which flips it to `converging`). During
+ * that in-between window the row reads `opened` while the engine instance is still ACTIVE, so a plain
+ * "any `opened` is dismissable" rule would offer Dismiss on an in-flight handoff and let a premature
+ * ack later drag a still-converging run to History — the SAME failure mode the epic model guards
+ * against by excluding its own mid-flight `converging`. The row itself distinguishes the two: a
+ * converge-requested run that actually handed off carries `converge=1 AND pr_key IS NOT NULL` — exactly
+ * the transient to exclude. Every other `opened` is finished: a raise-only run (`converge=0`), or a
+ * keyless `opened` that never satisfied the gateway's `prKey != null` and so fell through to `End`
+ * (`pr_key IS NULL`). The status guard (`derived_status = 'opened'`) scopes the exclusion to `opened`
+ * ONLY, so a genuinely-terminal row (e.g. `merged`) with `converge=1 AND pr_key` stays dismissable.
+ * `eq(col,col)` is the DSL's null-safe `IS NOT NULL` (see {@link isAckStamped}). A run stranded in this
+ * window by an out-of-band termination is reconciled to terminal by `pollFeatureDelivery`'s handoff
+ * edge (app/service.ts), which owns its liveness — so excluding it here never wedges it in Active. */
+const openedMidHandoff: Expr = and(
+  eq(col(EFFECTIVE_STATUS_COLUMN), lit("opened")),
+  eq(col("converge"), lit(1)),
+  eq(col("pr_key"), col("pr_key")),
+);
+
+/* DEFERRED (issue #810): `openedMidHandoff` only excludes the `converge=1 AND pr_key` handoff window,
+ * so a raise-only (`converge=0`) or keyless `opened` row IS treated as dismissable-terminal even in the
+ * brief window before `record-feature`'s token reaches `gw-blocked`/`gw-converge`/End. This is an
+ * accepted, bounded sub-transaction transient: `record-feature` writes `opened` only AFTER the
+ * productive work (the PR was raised) is done, so the sole still-"live" work in that window is one inert
+ * gateway→End hop the instance auto-completes near-instantly — there is nothing productive for an
+ * ack/resubmission to hide or replace. The categorical fix — gating dismissability on a PERSISTED
+ * engine-completion marker (which would reverse the option-1a `pr_key` heuristic adjudicated in
+ * escalation 162) — is tracked in issue #810; do NOT reverse option-1a here. */
+
+/** The feature DISMISSABLE-terminal PREDICATE — the epic read model's mid-flight refinement
+ * (app/planReadModel.ts / app/listBucket.ts) applied to features. A row is dismissable-terminal IFF its
+ * effective (terminal-folded) status is in the ONE canonical {@link FEATURE_ACK_TERMINAL_STATUSES} set
+ * (the pipeline-`Done` set PLUS `opened`) AND it is NOT a mid-handoff `opened` transient
+ * ({@link openedMidHandoff}). Built from the single {@link FEATURE_ACK_TERMINAL_STATUSES} source of
+ * truth — never a re-listed copy of its members — so a newly-acknowledgeable status added there flows
+ * through to `list_bucket`/`ack_open` without a second edit that could drift (issue #808 review). */
+export const featureDismissableTerminal: Expr = and(
+  terminalStatusIn(EFFECTIVE_STATUS_COLUMN, FEATURE_ACK_TERMINAL_STATUSES),
+  not(openedMidHandoff),
+);
+
+/** The Active/History partition: `history` IFF the row is DISMISSABLE-terminal AND has been
  * acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). Delegates to the ONE
- * shared `deriveListBucketExpr` oracle (app/listBucket.ts, issue #641) parameterised by the feature
- * terminal set ({@link STAGE_DONE_STATUSES}) so all four "Active …" grids share the identical AST — the
- * emitted SQL stays byte-equivalent to migration 081's already-merged VIEW body (the shared oracle
- * reproduces this model's `isDone`/`isNotNull` forms exactly). */
-const listBucket: Expr = deriveListBucketExpr(EFFECTIVE_STATUS_COLUMN, STAGE_DONE_STATUSES);
-
-/** The operator "Dismiss" (tick-off) affordance flag — `1` IFF the run is terminal AND not yet
- * acknowledged (so the page's `showWhenField` Dismiss button renders only for a terminal-but-
+ * shared oracle (app/listBucket.ts, issue #641) over the feature {@link featureDismissableTerminal}
+ * predicate — WIDER than the pipeline `Done` set so a finished raise-only `opened` run is dismissable
+ * into History while the STAGE derivations still render it `PR open`, yet excluding a mid-handoff
+ * `opened` so a stray/premature ack never drags a still-converging run to History. All four "Active …"
+ * grids share the identical AST shape. */
+const listBucket: Expr = deriveListBucketFromTerminal(featureDismissableTerminal);
+
+/** The operator "Dismiss" (tick-off) affordance flag — `1` IFF the run is DISMISSABLE-terminal AND not
+ * yet acknowledged (so the page's `showWhenField` Dismiss button renders only for a terminal-but-
  * unacknowledged run), else `0`. The feature twin of the PR/Delivery-Graph/Epic `ack_open`, from the
- * ONE shared oracle (app/listBucket.ts, issue #641) parameterised by the SAME {@link
- * STAGE_DONE_STATUSES} terminal set `list_bucket` uses — so the Dismiss button and the
- * `acknowledgeDone` guard consume the identical predicate and cannot drift (issue #654). */
-const ackOpen: Expr = deriveAckOpenExpr(EFFECTIVE_STATUS_COLUMN, STAGE_DONE_STATUSES);
+ * ONE shared oracle (app/listBucket.ts, issue #641) over the SAME {@link featureDismissableTerminal}
+ * predicate `list_bucket` uses — so the Dismiss button and the `acknowledgeDone` guard consume the
+ * identical predicate and cannot drift (issue #654). Including a FINISHED `opened` (issue #808) lets a
+ * raise-only run be ticked off so it no longer wedges in Active; excluding a mid-handoff `opened` keeps
+ * an in-flight convergence handoff non-dismissable. */
+const ackOpen: Expr = deriveAckOpenFromTerminal(featureDismissableTerminal);
 
 /** The keys of {@link featureReadModel}'s DERIVED columns, in the order migration 099 emits them.
  * Base columns are identity pass-throughs (not derivations) and are listed in the migration directly. */

package/app/github.test.ts

@@ -3,7 +3,7 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, fetchPrReviews, isNotAPullRequestError, listPrsForHead, type Mergeability, type PrState } from "./github.ts";
+import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, fetchPrReviews, isNotAPullRequestError, listPrsForHead, type GhReview, type Mergeability, type PrState } from "./github.ts";
 import { DEFAULT_MERGE_PROTOCOL, type MergeProtocol, type RequiredCheck } from "./mergeProtocol.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
@@ -40,6 +40,51 @@ async function withTokenTransport<T>(pages: number[], fn: () => Promise<T>): Pro
   }
 }
 
+function reviewFetch(pages: GhReview[][], requests: string[]) {
+  return (url: string | URL | Request): Promise<Response> => {
+    const u = new URL(String(url));
+    requests.push(u.toString());
+    const page = Number(u.searchParams.get("page") ?? "1");
+    const headers = new Headers();
+    if (page < pages.length) {
+      headers.set(
+        "link",
+        `<https://api.github.com/repos/o/r/pulls/1/reviews?per_page=100&page=${page + 1}>; rel="next", ` +
+          `<https://api.github.com/repos/o/r/pulls/1/reviews?per_page=100&page=${pages.length}>; rel="last"`,
+      );
+    }
+    return Promise.resolve(new Response(JSON.stringify(pages[page - 1] ?? []), { status: 200, headers }));
+  };
+}
+
+async function withTokenFetch<T>(fetchImpl: typeof fetch, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = fetchImpl;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+test("fetchPrReviews: returns the newest review when it is beyond page one", async () => {
+  const requests: string[] = [];
+  const pages = [
+    Array.from({ length: 100 }, (_, i) => ({ id: i + 1, state: "COMMENTED" })),
+    [{ id: 101, state: "APPROVED", submitted_at: "2026-09-15T12:00:00Z" }],
+  ];
+  const reviews = await withTokenFetch(reviewFetch(pages, requests) as typeof fetch, () =>
+    fetchPrReviews("o/r", 1, "tok"),
+  );
+  assertEquals(reviews?.length, 101);
+  assertEquals(reviews?.[reviews.length - 1]?.id, 101);
+  assertEquals(requests.length, 2, "the final page must be fetched after page one");
+});
+
 test("fetchPrFiles: returns the complete list for a sub-cap PR (short final page)", async () => {
   const files = await withTokenTransport([100, 42], () => fetchPrFiles("o/r", 1, "tok"));
   assertEquals(files?.length, 142);

package/app/reconcile.ts

@@ -232,7 +232,7 @@ interface InstanceSearchStateItem {
  *  outside this set is a partial/malformed read this app cannot interpret, so it degrades to `null`
  *  ("unknown" → the caller spares the row). Classifying an unrecognized state as "gone" would fold
  *  live work off a wire shape we misread — the exact failure mode the #736 cross-check exists to stop. */
-const ENGINE_TERMINAL_STATES: ReadonlySet<string> = new Set(["COMPLETED", "TERMINATED", "CANCELED", "FAILED"]);
+export const ENGINE_TERMINAL_STATES: ReadonlySet<string> = new Set(["COMPLETED", "TERMINATED", "CANCELED", "FAILED"]);
 
 /** Build an {@link EngineActiveProbe} that queries the engine's own `/v2/process-instances/search` for
  *  a single process instance key and reports whether the engine still considers it ACTIVE. This is the

package/app/service.test.ts

@@ -11,9 +11,10 @@ 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, isPrSettled, MAX_ACK_RETRIES, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
+import { abandonClosedPr, isPrSettled, MAX_ACK_RETRIES, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollReviews, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
 import { trackingTargetFor } from "./instanceTracking.ts";
 import type { DataLayer } from "@nanobpm/urban";
+import { READINESS_READY_MESSAGE } from "./readiness.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -78,6 +79,90 @@ function withGithubOff(run: () => Promise<void>): Promise<void> {
   });
 }
 
+function reviewPagesFetch(pages: Record<string, unknown>[][], requests: string[]) {
+  return (url: string | URL | Request): Promise<Response> => {
+    const u = new URL(String(url));
+    if (!u.pathname.endsWith("/reviews")) {
+      return Promise.resolve(
+        new Response(
+          JSON.stringify({ head: { ref: null, sha: "SHA_CURRENT" } }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        ),
+      );
+    }
+    requests.push(u.toString());
+    const page = Number(u.searchParams.get("page") ?? "1");
+    const headers = new Headers();
+    if (page < pages.length) {
+      headers.set(
+        "link",
+        `<https://api.github.com/repos/owner/repo/pulls/42/reviews?per_page=100&page=${page + 1}>; rel="next", ` +
+          `<https://api.github.com/repos/owner/repo/pulls/42/reviews?per_page=100&page=${pages.length}>; rel="last"`,
+      );
+    }
+    return Promise.resolve(new Response(JSON.stringify(pages[page - 1] ?? []), { status: 200, headers }));
+  };
+}
+
+test("pollReviews publishes readiness-ready for a fresh review on the final page (#793)", async () => {
+  const oldReviews = Array.from({ length: 100 }, (_, i) => ({
+    id: i + 1,
+    state: "COMMENTED",
+    submitted_at: "2026-09-01T00:00:00Z",
+    commit_id: "SHA_CURRENT",
+  }));
+  const pages = [
+    oldReviews,
+    [{ id: 101, state: "APPROVED", submitted_at: "2026-09-15T12:00:00Z", commit_id: "SHA_CURRENT" }],
+  ];
+  const requests: string[] = [];
+  const pr = {
+    pr_key: "owner/repo#42",
+    repo: "owner/repo",
+    number: 42,
+    status: "waiting_review",
+    waiting_since: "2026-09-10T00:00:00Z",
+    last_review_id: 100,
+  };
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    pull_requests: { rows: [pr], key: "pr_key" },
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], key),
+  } as any as DataLayer;
+  const messages: { name: string; correlationKey?: string; variables?: Record<string, unknown> }[] = [];
+  const engine = {
+    publishMessage: async (message: { name: string; correlationKey?: string; variables?: Record<string, unknown> }) => {
+      messages.push(message);
+    },
+  } as any;
+
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = reviewPagesFetch(pages, requests) as typeof fetch;
+  try {
+    await pollReviews(data, engine, "tok");
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+
+  assertEquals(requests.length, 2, "the poller must read the final reviews page");
+  assertEquals(
+    messages,
+    [{
+      name: READINESS_READY_MESSAGE,
+      correlationKey: "owner/repo#42",
+      variables: { ready: true, detail: "review 101 (APPROVED)" },
+    }],
+    "fresh review must release the review wait",
+  );
+  assertEquals(pr.last_review_id, 101);
+  assertEquals(pr.status, "converging");
+});
+
 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
@@ -495,6 +580,82 @@ test("submitPr stringifies a numeric processInstanceKey (contract: string | null
   });
 });
 
+// Phantom-enrollment guard (#704/#497, PR #809 review): `submitPr` INSERTS the `pull_requests` row
+// (`status='converging'`, `process_key` NULL) BEFORE `createInstance` and writes `process_key` only
+// after it returns. A create-instance failure/crash in that window strands a NON-terminal row with NO
+// `process_key` and NO live instance. Such a row must NOT be classified `alreadyRunning` (that would
+// wedge it forever, and `pollFeatureDelivery` edge (1) would skip it as non-terminal) — it must fall
+// through and RE-ENROLL, exactly as a genuinely-live row (non-terminal + `process_key` present) is
+// still short-circuited to `alreadyRunning`.
+test("submitPr re-enrolls a phantom row (non-terminal, process_key NULL) rather than reporting alreadyRunning (#704/#497)", async () => {
+  await withGithubOff(async () => {
+    const PR_KEY = "owner/repo#77";
+    const phantom = { pr_key: PR_KEY, repo: "owner/repo", number: 77, status: "converging", process_key: null };
+    const stores: Record<string, { rows: unknown[]; key: string }> = {
+      pull_requests: { rows: [phantom], key: "pr_key" },
+      escalations: { rows: [], key: "id" },
+      pr_dependencies: { rows: [], key: "pr_key" },
+    };
+    const data = {
+      table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
+      open: () => memOpen(stores as any),
+    } as any;
+    let created = 0;
+    const engine = {
+      createInstance: () => {
+        created++;
+        return Promise.resolve({ processInstanceKey: "PI-77" });
+      },
+    } as any;
+
+    const res = await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 77,
+      url: "https://github.com/owner/repo/pull/77",
+      prKey: PR_KEY,
+    });
+
+    assertEquals((res as any).alreadyRunning, undefined, "a phantom row is not short-circuited as alreadyRunning");
+    assertEquals(created, 1, "the phantom row is re-enrolled with a fresh instance");
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.process_key, "PI-77", "the previously-missing process_key is installed");
+  });
+});
+
+test("submitPr still short-circuits a genuinely-live non-terminal row (process_key present) as alreadyRunning (#704/#497)", async () => {
+  await withGithubOff(async () => {
+    const PR_KEY = "owner/repo#78";
+    const live = { pr_key: PR_KEY, repo: "owner/repo", number: 78, status: "converging", process_key: "PI-live" };
+    const stores: Record<string, { rows: unknown[]; key: string }> = {
+      pull_requests: { rows: [live], key: "pr_key" },
+      escalations: { rows: [], key: "id" },
+      pr_dependencies: { rows: [], key: "pr_key" },
+    };
+    const data = {
+      table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
+    } as any;
+    let created = 0;
+    const engine = {
+      createInstance: () => {
+        created++;
+        return Promise.resolve({ processInstanceKey: "PI-new" });
+      },
+    } as any;
+
+    const res = await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 78,
+      url: "https://github.com/owner/repo/pull/78",
+      prKey: PR_KEY,
+    });
+
+    assertEquals((res as any).alreadyRunning, true, "a live enrolled PR is still short-circuited");
+    assertEquals(created, 0, "no duplicate instance is created for a live PR");
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.process_key, "PI-live", "the live PR's process_key is untouched");
+  });
+});
+
 // Per-request review-only override: `submitPr` carries `convergeOnly` onto the convergence
 // instance so `pr.finalize` can stop at `converged` without handing off to the merge-loop. Default
 // false (so the global auto-merge default governs); true when the caller pins review-only.

package/app/service.ts

@@ -35,7 +35,7 @@ import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels } from "./deli
 import { deliveryHumanContextQuestion, isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { deriveEpicPhaseLive, deriveTerminalEpicPhase } from "./epicPhase.ts";
-import { deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
+import { deriveFeatureCompletion, deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns, featureRunsTracking, foldCompletedFeatureRun } from "./feature.ts";
 import {
   classifyMergeability,
   classifyPrLiveness,
@@ -88,6 +88,7 @@ import {
   readinessPollEvery,
   readinessTimeout,
 } from "./readiness.ts";
+import { ENGINE_TERMINAL_STATES } from "./reconcile.ts";
 // The repository-provisioning envelope builder lives in its own module (app/repoEnvelope.ts) so the
 // PRE-PR implementation dispatch (`feature.ts`/`plan.ts`) can reuse the ONE canonical implementation
 // without a `plan.ts ↔ service.ts` import cycle (issue #684). Imported for the PR-based callers
@@ -534,7 +535,16 @@ export async function submitPr(
   // 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)) {
+  // Phantom-enrollment guard (#704/#497, PR #809 review): a non-terminal row is "already running" ONLY
+  // if an engine instance was actually dispatched — i.e. it holds a `process_key`. `submitPr` INSERTS
+  // the `pull_requests` row (`status='converging'`, `process_key` NULL) BEFORE `createInstance` and
+  // writes `process_key` only AFTER it returns (below), so a create-instance failure/crash in that
+  // window strands a `converging` row with NO `process_key` and NO live instance. Classifying it off
+  // the derived status alone would wedge it `alreadyRunning` forever (and `pollFeatureDelivery` edge (1)
+  // would skip it as non-terminal, never re-enrolling). Treat a keyless non-terminal row as
+  // RESUBMITTABLE — fall through and re-enroll, exactly as `startFeature`'s intake guard (feature.ts)
+  // treats a keyless `running` feature row. A terminal row (any `process_key`) already falls through.
+  if (trackedExisting && existing?.process_key != null && !TERMINAL_STATUSES.includes(trackedExisting.derived_status)) {
     return { prKey: parsed.prKey, alreadyRunning: true };
   }
 
@@ -2294,19 +2304,69 @@ export async function pollPromotion(data: DataLayer, engine: EngineClient, token
   }
 }
 
-/** Reconcile each in-flight FEATURE run against its handed-off PR (fix: Feature history stuck at
- * `converging`). A feature run ends its own process with `status = converging` and its PR's live
- * outcome (merged / converged / abandoned) thereafter lives only on the `pull_requests` row keyed
- * by `pr_key` — so the Feature history grid, which reads `feature_runs`, showed `converging` forever.
- * This is the `feature_runs` twin of `pollDelivery` (which does the same for epic `plans`): for each
- * run currently `converging` with a `pr_key`, project the PR's status onto `feature_runs.status`
- * (advancing it to the matching terminal outcome once the PR settles) + a human `delivery_label`.
- * Never touches a run that isn't `converging` — additive/derived only, idempotent, best-effort. */
-export async function pollFeatureDelivery(data: DataLayer) {
+/** Reconcile each in-flight FEATURE run against ENGINE truth (fix: Feature history stuck at
+ * `converging`; issue #808: raise-only runs wedge in Active). Two idempotent, best-effort edges over
+ * the canonical feature reconciliation — no parallel reconciler:
+ *
+ * 1. CONVERGING → terminal (from its handed-off PR). A feature run ends its own process with
+ *    `status = converging` and its PR's live outcome (merged / converged / abandoned) thereafter lives
+ *    only on the `pull_requests` row keyed by `pr_key` — so the Feature history grid, which reads
+ *    `feature_runs`, showed `converging` forever. The `feature_runs` twin of `pollDelivery`: for each
+ *    run currently `converging` with a `pr_key`, project the PR's status onto `feature_runs.status`
+ *    (advancing it to the matching terminal outcome once the PR settles) + a human `delivery_label`.
+ *
+ * 2. COMPLETED → terminal (from the engine instance; issue #808). A raise-only / normally-completing
+ *    run ends its process with the non-terminal base `status = running` and is NEVER handed to a PR
+ *    loop, so neither edge (1) nor `instanceTracking`'s TERMINATED → `abandoned` edge folds it — it
+ *    would wedge in Active forever ("poller owns liveness; never leave a run on a status no pass
+ *    scans"). This owns the COMPLETED → terminal fold for such runs, mirroring the taskless-plan pass
+ *    ({@link pollTasklessPlanTermination}, #624) and {@link pollDeliveryGraphPhase}. Scoped to
+ *    `running` — the only non-terminal, non-parked status that can reach COMPLETED (`escalated` /
+ *    `awaiting_operator` keep the instance ALIVE at a user task, owned by their own edges) — so a
+ *    `converging` run is untouched by this fold. Liveness is read off the ADR-0065 derived tracking
+ *    VIEW (`derived_status`), so a run TERMINATED out of band (folding `derived_status` → `abandoned`)
+ *    is left to the `onTerminated` edge and never re-queried every pass. Writes only on a real
+ *    COMPLETED read (idempotent — a pass over a still-active or already-terminal run is a no-op).
+ *
+ * 3. MID-HANDOFF `opened` → terminal (PR #809 review / escalation 162). `record-feature` writes base
+ *    `status = opened` for a converge-REQUESTED run too, BEFORE `gw-converge` hands it to
+ *    `converge-feature` (which flips it to `converging` and enrolls the PR via `submitPr`). That
+ *    transient `opened` + `converge=1` + `pr_key` window is NOT dismissable (`featureReadModel` excludes
+ *    it so a premature ack can't drag a still-converging run to History), yet `opened` is no
+ *    `instanceTracking` activeStatus and neither edge (1) nor (2) scans it — so a row stranded there has
+ *    no owner. This owns that liveness, deciding PR-FIRST (never off the FEATURE instance state alone —
+ *    that was the drift surface): the `pull_requests` row keyed by `pr_key` is the single source of truth
+ *    for whether `submitPr` enrollment happened. If a PR row EXISTS, enrollment succeeded and the PR is a
+ *    live/settled SEPARATE process whose outcome edge (1) owns — fold `opened` → `converging`/terminal via
+ *    the same `deriveFeatureDelivery`, NEVER `abandoned` (it is structurally impossible for this edge to
+ *    abandon an enrolled PR). ONLY when NO PR row exists (enrollment never happened) is the engine probed:
+ *    a mid-handoff row can then only be stranded if its instance died before `submitPr`, so a KNOWN
+ *    terminal (or genuinely absent) instance means the handoff was interrupted — fold to the terminal
+ *    `abandoned` (mirroring `onTerminated`). That probe applies the reconcile-probe tri-state
+ *    (app/reconcile.ts): ACTIVE is left for `converge-feature`, and an instance whose snapshot carries an
+ *    empty/unknown state is SPARED (never folded off a wire shape we misread). A key edge (2) folded THIS
+ *    pass is skipped (it is already terminalized, not stranded). Read off the derived tracking VIEW so an
+ *    out-of-band fold is not re-queried; scoped to `converge=1 AND pr_key` (a raise-only or keyless
+ *    `opened` is genuinely terminal, owned by its own dismissable edge). */
+export async function pollFeatureDelivery(
+  data: DataLayer,
+  // Full `EngineClient`: edge (1) re-enrolls a converging run whose PR row is still missing via
+  // `submitPr` (which needs `createInstance`), not just the `searchProcessInstances` the fold edges use.
+  engine: EngineClient,
+) {
   // Preload every PR status once per pass (mirrors pollDelivery — avoids an N+1 `prs(data).get`).
   // Read the ADR-0065 derived edge (`derived_status`) so a terminated run reads `abandoned`.
   const statusByPrKey = new Map<string, string>();
-  for (const pr of await prsTracking(data).all()) statusByPrKey.set(pr.pr_key, pr.derived_status);
+  // Also index each tracked PR row so edge (1) can distinguish a NEVER-enrolled PR (no row) from a
+  // PARTIALLY-enrolled one (row present, but `submitPr` crashed after the row insert and before
+  // `createInstance` returned, so `process_key` is NULL and no instance exists — #704/#497 phantom).
+  // Keep the whole row (not just the key) so the terminal-status classification below reads the
+  // ADR-0065 `.derived_status`, satisfying the derive-only-reader class guard (#503/#704).
+  const prRowByKey = new Map<string, TrackedPullRequest>();
+  for (const pr of await prsTracking(data).all()) {
+    statusByPrKey.set(pr.pr_key, pr.derived_status);
+    prRowByKey.set(pr.pr_key, pr);
+  }
   // Only `converging` runs are ever reconciled — query them via the `feature_runs(status)` index
   // (db/migrations/028) instead of scanning all history, so this pass stays O(in-flight), not
   // O(total runs), as the table grows.
@@ -2314,6 +2374,27 @@ export async function pollFeatureDelivery(data: DataLayer) {
     if (!run.pr_key) continue;
     try {
       const prStatus = statusByPrKey.get(run.pr_key) ?? null;
+      const trackedPr = prRowByKey.get(run.pr_key) ?? null;
+      // RE-ENROLL a converging run whose PR is not actually live, in EITHER of two shapes (PR #809
+      // review):
+      //   (a) NO `pull_requests` row (`prStatus === null`) — since `converge-feature` writes
+      //       `converging` BEFORE `submitPr`, a terminate/crash in that gap (or an old submit failure /
+      //       store desync) leaves a converging row whose PR was never enrolled; and
+      //   (b) a PARTIALLY-enrolled row — present but with NO `process_key` and a non-terminal status:
+      //       `submitPr` inserts the row before `createInstance`, so a create-instance failure/crash
+      //       after the insert leaves a `converging` PR row with `process_key` NULL and no instance
+      //       (#704/#497 phantom). `prStatus` is non-null there, so the (a) check alone would skip it and
+      //       it would wedge `converging` forever with no PR process.
+      // Both heal via the SAME idempotent `submitPr`: it is idempotent on the PR key (a redundant call
+      // on an already-live PR early-returns `alreadyRunning`), and now treats a keyless non-terminal row
+      // as resubmittable, so it re-creates the instance and installs `process_key`. `convergeOnly`
+      // mirrors `converge-feature` — the inverse of the run's `auto_merge` flag.
+      const partiallyEnrolled =
+        trackedPr != null && trackedPr.process_key == null && !TERMINAL_STATUSES.includes(trackedPr.derived_status);
+      if (prStatus === null || partiallyEnrolled) {
+        const parsed = parsePr(run.pr_key);
+        if (parsed) await submitPr(data, engine, parsed, [], MAX_ROUNDS, run.auto_merge !== 1, run.feature_key);
+      }
       const { status, label } = deriveFeatureDelivery(prStatus);
       if (run.status !== status || run.delivery_label !== label) {
         await featureRuns(data).update(run.feature_key, {
@@ -2326,6 +2407,92 @@ export async function pollFeatureDelivery(data: DataLayer) {
       console.error(`[poller] feature delivery ${run.feature_key}: ${err}`);
     }
   }
+  // Edge (2): COMPLETED → terminal for a normally-completing `running` run (issue #808). Read the
+  // derived tracking VIEW so a base-`running` row whose instance TERMINATED out of band (derived
+  // `abandoned`) is skipped here (the `onTerminated` edge owns it) and never re-queried the engine.
+  // Feature keys this edge folds this pass are tracked in `foldedByCompletion` so edge (3) — which
+  // re-reads the DB and would otherwise see a row edge (2) just moved to `opened` in the SAME pass —
+  // leaves them alone (PR #809 review): edge (2) has already assigned such a row its terminal outcome.
+  const foldedByCompletion = new Set<string>();
+  for (const run of await featureRunsTracking(data).find({ status: "running" })) {
+    if (!run.process_key) continue;
+    if (run.derived_status !== "running") continue;
+    const processKey = run.process_key;
+    try {
+      const snapshots = await engine.searchProcessInstances({ processInstanceKeys: [processKey] });
+      const state = snapshots.find((s) => String(s.processInstanceKey) === processKey)?.state ?? null;
+      if (state !== "COMPLETED") continue;
+      const { status, label } = deriveFeatureCompletion(run);
+      // Guarded CAS (not a blind update-by-key): a concurrent `startFeature` may have re-seeded this
+      // same row to a fresh `running` incarnation (new `process_key`) in the window since the engine
+      // read above — the guard makes such a lost race a no-op instead of clobbering the new run.
+      if (await foldCompletedFeatureRun(data, run.feature_key, processKey, status, label)) {
+        foldedByCompletion.add(run.feature_key);
+      }
+    } catch (err) {
+      console.error(`[poller] feature completion ${run.feature_key}: ${err}`);
+    }
+  }
+  // Edge (3): mid-handoff `opened` → `abandoned` for a run whose instance died before convergence (PR
+  // #809 review, issue #808 follow-up). `record-feature` writes base `status="opened"` for a
+  // converge-REQUESTED run TOO, BEFORE `gw-converge` hands it to `converge-feature` (which flips it to
+  // `converging`). That transient `opened` + `converge=1` + non-null `pr_key` window is deliberately
+  // NOT dismissable (`featureReadModel` excludes it, so a premature ack can't drag a still-converging
+  // run to History) — but `opened` is not an `instanceTracking` activeStatus (nano.app.json), and
+  // neither the converging edge (1) nor the running edge (2) scans it, so an instance TERMINATED in
+  // that window would strand the row in Active FOREVER with `ack_open=0` and no reconciler. This edge
+  // owns that liveness: a mid-handoff row can only LEAVE `opened` by writing `converging` (a clean
+  // handoff) — so if its instance is a KNOWN terminal (or genuinely absent) while the row still reads
+  // `opened`, the handoff was interrupted (out-of-band terminate / crash) and the run is folded to the
+  // terminal `abandoned` (the same edge `instanceTracking.onTerminated` applies to a tracked run's
+  // out-of-band termination). The snapshot is read with the SAME tri-state as the reconcile probe
+  // (app/reconcile.ts): a still-ACTIVE instance is left untouched (`converge-feature` will advance it),
+  // and an instance present with an empty/unknown/newly-introduced state is SPARED, never folded off a
+  // wire shape we misread. A row edge (2) folded to `opened` in THIS pass is skipped (`foldedByCompletion`)
+  // — it is already terminalized, not a stranded handoff. Read the derived tracking VIEW so a row
+  // already folded `abandoned` out of band is skipped and never re-queried. Guarded CAS on the OLD
+  // `process_key` + `status='opened'`, so a concurrent `startFeature` re-seed is a no-op, never a
+  // clobber. Scoped to `converge=1 AND pr_key` — a raise-only (`converge=0`) or keyless (`pr_key IS
+  // NULL`) `opened` is genuinely terminal and owned by its own dismissable edge, so it is never queried here.
+  for (const run of await featureRunsTracking(data).find({ status: "opened" })) {
+    if (!run.process_key || !run.pr_key || run.converge !== 1) continue;
+    if (run.derived_status !== "opened") continue;
+    // Edge (2) may have folded a COMPLETED `running` run to `opened` in THIS pass (thread 1): that row
+    // is already terminalized by its own derivation, not a stranded mid-handoff — never re-fold it here.
+    if (foldedByCompletion.has(run.feature_key)) continue;
+    const processKey = run.process_key;
+    try {
+      // PR-DERIVED liveness FIRST (PR #809 review / escalation 162 decision 2): a `pull_requests` row
+      // keyed by `pr_key` is the single source of truth for "did `submitPr` enrollment actually happen".
+      // If one EXISTS, `converge-feature` already enrolled the PR — it is a live/settled SEPARATE process
+      // whose outcome edge (1) owns — so the handoff was NOT interrupted regardless of the FEATURE
+      // instance's engine state. Project the PR's derived outcome onto the row (fold `opened` →
+      // `converging`/terminal via the SAME `deriveFeatureDelivery` edge (1) uses) and NEVER abandon it.
+      // This makes it structurally impossible for the handoff edge to abandon an enrolled PR — inferring
+      // "interrupted" from the FEATURE instance state alone was the drift surface. The engine probe below
+      // is reached ONLY when no PR row exists (enrollment never happened), the genuine interrupted handoff.
+      const prStatus = statusByPrKey.get(run.pr_key) ?? null;
+      if (prStatus !== null) {
+        const { status, label } = deriveFeatureDelivery(prStatus);
+        await foldCompletedFeatureRun(data, run.feature_key, processKey, status, label, "opened");
+        continue;
+      }
+      const snapshots = await engine.searchProcessInstances({ processInstanceKeys: [processKey] });
+      const match = snapshots.find((s) => String(s.processInstanceKey) === processKey);
+      // Interpret the snapshot with the SAME tri-state semantics as the reconcile engine-probe
+      // (app/reconcile.ts): ACTIVE → still mid-handoff; a KNOWN terminal state or a genuinely-absent
+      // instance → the handoff was interrupted (fold); an instance present with an empty/unknown/
+      // newly-introduced state → a partial answer this app cannot interpret, so spare the row rather
+      // than fold a possibly still-live run to `abandoned` off a wire shape we misread (thread 3).
+      const state = match ? String(match.state ?? "").trim().toUpperCase() : null;
+      if (state === "ACTIVE") continue; // still mid-handoff — converge-feature will advance it
+      if (state !== null && !ENGINE_TERMINAL_STATES.has(state)) continue; // unknown/empty → spare
+      // state === null (engine answered, instance absent) OR a known terminal → interrupted handoff.
+      await foldCompletedFeatureRun(data, run.feature_key, processKey, "abandoned", "handoff interrupted", "opened");
+    } catch (err) {
+      console.error(`[poller] feature handoff ${run.feature_key}: ${err}`);
+    }
+  }
 }
 
 /** The `pull_requests` statuses a PR instance can be parked-and-active on, DERIVED from the single
@@ -3102,7 +3269,7 @@ export async function pollOnce(
   await pollMerges(data, engine, token);
   await pollWaitGate(data);
   await pollPromotion(data, engine, token);
-  await pollFeatureDelivery(data);
+  await pollFeatureDelivery(data, engine);
   await pollLineage(data);
   await pollUserTasks(data, engine, engineRest);
   await pollEpicPhase(data, engine, engineRest);