@nanobpm/nano-workforce 0.91.0 → 0.92.0

package/app/plan.ts

@@ -11,9 +11,16 @@
 // hand-written SQL — matching app/service.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
+import { deriveEpicBucket, epicIsAcknowledgeable } from "./delivery.ts";
 import { EPIC_PHASE } from "./epicPhase.ts";
 import { DEFAULT_ESCALATION_SLA_TIMEOUT, escalationSlaTimeout } from "./escalationSla.ts";
-import { coalesceTitle, ensureBaseBranch, fetchDefaultBranch, fetchIssueTitle } from "./github.ts";
+import {
+  BaseBranchMustExistError,
+  coalesceTitle,
+  ensureBaseBranch,
+  fetchDefaultBranch,
+  fetchIssueTitle,
+} from "./github.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
 import { clearTaskDeltas } from "./taskDelta.ts";
 
@@ -100,6 +107,19 @@ export interface Plan {
   //                       which has nothing to promote). Display-only; projected by the poller.
   promotion_pr: string | null;
   promotion_state: string | null;
+  // Active/History partition + operator tick-off (044_plan_list_bucket.sql, #298). Derived,
+  // write-time-projected by the `plans` gateway (below) from the pure `deriveEpicBucket` /
+  // `epicIsAcknowledgeable` helpers (app/delivery.ts) — never written by the plan lifecycle or a
+  // poller directly. Bucket epics on the derived `delivery` rollup, not raw `status`, so a `done`
+  // epic still converging — or landed-but-unpromoted — does not vanish from Active.
+  //   • acknowledged_at — NULL until an operator dismisses a resolved `done` epic (acknowledge-epic).
+  //   • list_bucket     — 'active' | 'history': the page tabs filter on this flat column.
+  //   • ack_open        — 1 | 0: 1 iff a resolved (`done`, not converging) but unacknowledged epic,
+  //                       gating the Dismiss button's `showWhenField`. NULL only on pre-#298 rows
+  //                       until `backfillPlanBuckets`.
+  acknowledged_at: string | null;
+  list_bucket: string | null;
+  ack_open: number | null;
   created_at: string;
   updated_at: string;
 }
@@ -136,7 +156,85 @@ export const PLAN_TASK_STATUSES = [
 ] as const;
 export type PlanTaskStatus = typeof PLAN_TASK_STATUSES[number];
 
-export const plans = (data: DataLayer) => data.table<Plan>("plans", "plan_key");
+export const plans = (data: DataLayer) => {
+  const table = data.table<Plan>("plans", "plan_key");
+  return new Proxy(table, {
+    get(target, prop) {
+      if (prop === "insert") {
+        return (row: Partial<Plan>) => target.insert({ ...row, ...projectPlanBucket(row) });
+      }
+      if (prop === "update") {
+        return async (id: unknown, patch: Partial<Plan>) => {
+          // Only re-read + reproject when the patch changes a projection input (status / delivery /
+          // acknowledged_at) or writes a derived column directly. A projection-irrelevant patch (e.g.
+          // an `updated_at`- or `wave_label`-only write — including the direct `data.table` writes in
+          // e.g. `app/retro.ts` that stamp `retro_started_at`) leaves the stored projection correct, so
+          // skip the extra `get` roundtrip and delegate straight. Any bucket-relevant write
+          // (status/delivery/acknowledged_at or a derived column) MUST go through this gateway to stay
+          // reprojected.
+          if (!patchAffectsPlanProjection(patch)) return target.update(id, patch);
+          const existing = await target.get(id);
+          const merged: Partial<Plan> = { ...existing, ...patch };
+          return target.update(id, { ...patch, ...projectPlanBucket(merged) });
+        };
+      }
+      // Delegate every other method straight through. Bind functions to the real target so the
+      // gateway's private class fields resolve — a Proxy `this` would not carry them.
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+};
+
+/** The `plans` fields the bucket projection READS: a patch touching none of these (and none it
+ * writes) cannot change `list_bucket`/`ack_open`, so the gateway skips the read-back+reproject. Kept
+ * adjacent to {@link projectPlanBucket} so the two stay in lockstep. */
+const PLAN_PROJECTION_INPUT_KEYS: readonly (keyof Plan)[] = ["status", "delivery", "acknowledged_at"];
+
+/** The `plans` fields the bucket projection WRITES. Included in the reproject trigger so a caller who
+ * writes a derived column directly (e.g. `list_bucket`/`ack_open`) can never bypass derivation: the
+ * gateway re-reads, recomputes, and OVERRIDES the raw value with the canonical derived one. */
+const PLAN_PROJECTION_OUTPUT_KEYS: readonly (keyof Plan)[] = ["list_bucket", "ack_open"];
+
+/** True when a patch changes at least one field the bucket projection derives from OR one it writes —
+ * i.e. the projection must be recomputed (mirrors feature.ts `patchAffectsProjection`). */
+function patchAffectsPlanProjection(patch: Partial<Plan>): boolean {
+  return (
+    PLAN_PROJECTION_INPUT_KEYS.some((k) => k in patch) ||
+    PLAN_PROJECTION_OUTPUT_KEYS.some((k) => k in patch)
+  );
+}
+
+/** Compute the write-time bucket projection columns for a merged `plans` row. Centralised so the
+ * gateway is the ONE place `deriveEpicBucket` / `epicIsAcknowledgeable` are applied — the page, SQL,
+ * pollers and workers never re-derive the mapping (AGENTS.md "derivation over duplication"). */
+function projectPlanBucket(row: Partial<Plan>): Partial<Plan> {
+  if (!row.status) return {};
+  return {
+    list_bucket: deriveEpicBucket(row.status, row.delivery ?? null, row.acknowledged_at ?? null),
+    ack_open:
+      epicIsAcknowledgeable(row.status, row.delivery ?? null) && (row.acknowledged_at ?? null) === null
+        ? 1
+        : 0,
+  };
+}
+
+/** Re-project every `plans` row through the gateway so rows written before migration 042 (whose
+ * `list_bucket`/`ack_open` are NULL) get a correct Active/History bucket. Idempotent and safe to
+ * re-run: it re-derives from each row's own stored fields, so a second pass is a no-op. Runs once at
+ * boot (pollOnce) — the gateway keeps every future write fresh, so this only needs to catch legacy
+ * rows. Returns the count actually stamped. Mirrors `backfillFeatureStages` (app/feature.ts). */
+export async function backfillPlanBuckets(data: DataLayer): Promise<number> {
+  const table = plans(data);
+  let stamped = 0;
+  for (const row of await table.all()) {
+    // Only touch rows the projection has never reached — a legacy row whose `list_bucket` is NULL.
+    if (row.list_bucket != null) continue;
+    await table.update(row.plan_key, projectPlanBucket(row));
+    stamped++;
+  }
+  return stamped;
+}
 export const planTasks = (data: DataLayer) => data.table<PlanTask>("plan_tasks", "id");
 
 /** One dependency edge in the plan DAG (issue #20): `task_id` waits for `depends_on_task_id`.
@@ -173,18 +271,25 @@ export const planDeps = (data: DataLayer) => data.table<PlanDep>("plan_deps", "p
 /** The fields an admission caller supplies for one inter-epic edge; `created_at` is stamped here. */
 export type PlanDepInput = Omit<PlanDep, "created_at">;
 
-/** Record one inter-epic dependency edge, enforcing the schema's two invariants at the app layer too
- * (the durable table backstops both, but the in-memory test data layer does not): an epic may not
- * depend on itself, and a consumer→producer edge is recorded at most once. A duplicate re-submission
- * is a no-op that returns the existing row rather than throwing, so batch admission (S2) stays
- * idempotent; a self-edge is a programming/validation error and throws. */
-export async function recordPlanDep(data: DataLayer, edge: PlanDepInput): Promise<PlanDep> {
+/** The record-gateway shape both the durable `plan_deps` table and its FK-free admission-staging
+ * twin `admitted_plan_deps` expose. Both hold the identical {@link PlanDep} row, so the idempotent
+ * edge-insert below is written once against this shape and reused for both. */
+type PlanDepTable = ReturnType<typeof planDeps>;
+
+/** Insert one inter-epic edge into `table` idempotently, enforcing the schema's two invariants at
+ * the app layer too (the durable table backstops both, but the in-memory test data layer does not):
+ * an epic may not depend on itself, and a consumer→producer edge is recorded at most once. A
+ * duplicate re-submission is a no-op that returns the existing row rather than throwing, so batch
+ * admission (S2) stays idempotent; a self-edge is a programming/validation error and throws. `label`
+ * only names the offending table in the self-edge error. */
+async function insertEdgeIdempotent(
+  table: PlanDepTable,
+  label: string,
+  edge: PlanDepInput,
+): Promise<PlanDep> {
   if (edge.plan_key === edge.depends_on_plan_key) {
-    throw new Error(
-      `plan_deps: self-edge rejected — epic ${edge.plan_key} cannot depend on itself`,
-    );
+    throw new Error(`${label}: self-edge rejected — epic ${edge.plan_key} cannot depend on itself`);
   }
-  const table = planDeps(data);
   const match = { plan_key: edge.plan_key, depends_on_plan_key: edge.depends_on_plan_key };
   const existing = (await table.find(match))[0];
   if (existing) return existing;
@@ -204,6 +309,71 @@ export async function recordPlanDep(data: DataLayer, edge: PlanDepInput): Promis
   }
 }
 
+/** Record one inter-epic dependency edge into the durable `plan_deps` graph. Idempotent on the
+ * consumer→producer pair; a self-edge throws. NOTE: `plan_deps.plan_key` foreign-keys to an admitted
+ * `plans` row, so this is written by slice S3 (planner lowering), NOT by the S2 admission door —
+ * S2 stages edges FK-free via {@link recordAdmittedPlanDep} instead. */
+export function recordPlanDep(data: DataLayer, edge: PlanDepInput): Promise<PlanDep> {
+  return insertEdgeIdempotent(planDeps(data), "plan_deps", edge);
+}
+
+/** One STAGED admitted epic (issue #292 slice S2, db/migrations/045_epic_set_admission_staging.sql):
+ * the FK-free record the set/batch admission door persists per admitted epic so a crash between
+ * admission and lowering does not lose the set. It carries exactly what slice S3 (lowering) needs to
+ * MATERIALIZE the durable `plans` row — repo, issue number/url, and the normalized integration base
+ * branch admitPlan resolved. Keyed on `plan_key`, one staged row per epic (idempotent re-submit). */
+export interface AdmittedEpic {
+  plan_key: string;
+  repo: string;
+  issue_number: number;
+  issue_url: string;
+  base_branch: string;
+  created_at: string;
+}
+export const admittedEpics = (data: DataLayer) =>
+  data.table<AdmittedEpic>("admitted_epics", "plan_key");
+
+/** The FK-free staging twin of `plan_deps` (db/migrations/045_epic_set_admission_staging.sql): the
+ * validated inter-epic edges the S2 admission door stages before any `plans` row exists. Same row
+ * shape as {@link PlanDep}; slice S3 reads it to materialize the durable `plan_deps` edges. */
+export const admittedPlanDeps = (data: DataLayer) =>
+  data.table<PlanDep>("admitted_plan_deps", "plan_key");
+
+/** The fields an admission caller supplies for one staged admitted epic; `created_at` is stamped
+ * here (mirrors {@link PlanDepInput}). */
+export type AdmittedEpicInput = Omit<AdmittedEpic, "created_at">;
+
+/** Stage one admitted epic (issue #292 slice S2). Idempotent on `plan_key`: a re-submitted set that
+ * re-admits the same epic is a no-op returning the existing staged row, so the whole set door stays
+ * idempotent (mirroring {@link recordAdmittedPlanDep}). */
+export async function recordAdmittedEpic(
+  data: DataLayer,
+  epic: AdmittedEpicInput,
+): Promise<AdmittedEpic> {
+  const table = admittedEpics(data);
+  const existing = await table.get(epic.plan_key);
+  if (existing) return existing;
+  const row: AdmittedEpic = { ...epic, created_at: now() };
+  try {
+    await table.insert(row);
+    return row;
+  } catch (err) {
+    // Concurrent re-admission of the same epic races on the PRIMARY KEY (plan_key); honour the
+    // idempotent no-op contract by returning the winning row rather than surfacing the collision.
+    const raced = await table.get(epic.plan_key);
+    if (raced) return raced;
+    throw err;
+  }
+}
+
+/** Stage one validated inter-epic edge (issue #292 slice S2) into the FK-free `admitted_plan_deps`
+ * table. Idempotent on the consumer→producer pair; a self-edge throws. This is the S2 door's
+ * persistence for edges — it does NOT touch `plan_deps` (whose FK requires a `plans` row S2 has not
+ * created); slice S3 materializes the durable edge from this staging. */
+export function recordAdmittedPlanDep(data: DataLayer, edge: PlanDepInput): Promise<PlanDep> {
+  return insertEdgeIdempotent(admittedPlanDeps(data), "admitted_plan_deps", edge);
+}
+
 /** All INBOUND edges for `planKey` — i.e. every producer epic this dependent waits on. Empty for a
  * root epic (no inter-epic dependencies). */
 export function inboundPlanDeps(data: DataLayer, planKey: string): Promise<PlanDep[]> {
@@ -484,6 +654,225 @@ export async function admitPlan(
   return base;
 }
 
+/** Map an error thrown by {@link admitPlan} to the HTTP status + message the admission-door
+ * operations return at the edge, or `null` when the error is not an admission decision and must be
+ * re-raised (a genuine 500). Shared by the single-issue door (`startPlanFanout`) and the set/batch
+ * door (`startEpicSet`, issue #292 S2) so both map an epic's admission failure identically — a base
+ * rule reject is a 400, the shared-base conflict a 409. Keeping this in ONE place stops the two doors
+ * drifting on which admission failure maps to which status. */
+export function admitPlanErrorResponse(err: unknown): { status: number; error: string } | null {
+  if (err instanceof MissingBaseBranchError) {
+    return {
+      status: 400,
+      error: "baseBranch is required (name the integration branch, e.g. epic/agent-protocol)",
+    };
+  }
+  if (err instanceof InvalidBaseBranchError) {
+    return {
+      status: 400,
+      error: "invalid baseBranch (must be a plausible git branch name, e.g. epic/agent-protocol)",
+    };
+  }
+  if (err instanceof BaseBranchMustExistError) {
+    return {
+      status: 400,
+      error:
+        `baseBranch "${err.branch}" does not exist and is not an epic/* branch, so it is not ` +
+        `auto-created — create it first, or use the epic/* convention`,
+    };
+  }
+  if (err instanceof DefaultBaseNotConfirmedError) {
+    return {
+      status: 400,
+      error:
+        `baseBranch "${err.branch}" is the repository default branch — every task would land ` +
+        `directly on it with no integration branch. Re-submit with confirmDefaultBase: true to proceed`,
+    };
+  }
+  if (err instanceof SharedBaseError) {
+    return {
+      status: 409,
+      error:
+        `baseBranch "${err.branch}" is already in use by another active epic. Re-submit with ` +
+        `allowSharedBase: true to stack on it, or name a distinct epic/* branch`,
+    };
+  }
+  return null;
+}
+
+// ── Set/batch admission (issue #292, slice S2) ───────────────────────────────
+// The set-admission door (`operations/startEpicSet.ts`) admits a WHOLE set of epics plus the
+// inter-epic dependency edges between them in one all-or-nothing call. The pure validation below
+// (reference integrity + DAG check) runs BEFORE any `admitPlan` side effect, so a malformed set is a
+// clean 4xx with nothing half-started (no base branch created, no edge persisted). The door's only
+// durable write is staging the admitted epics + validated edges FK-free into `admitted_epics` /
+// `admitted_plan_deps`; materializing them into `plans` / `plan_deps` and scheduling/lowering
+// (starting roots, seeding the capability readiness-gate, version binding) is slice S3.
+
+/** One inter-epic dependency edge as SUBMITTED to the set door: the `consumer` epic waits for the
+ * `producer` epic to publish the `{ package, capabilityRef }` capability. `consumer`/`producer` are
+ * epic references (`owner/repo#N` or an issue URL); the door resolves them to plan keys. This type
+ * documents the wire contract only — the actual `deps[]` arrives untyped, so {@link validateEpicSet}
+ * validates each entry against this shape at runtime rather than trusting the type. */
+export interface EpicSetDepInput {
+  consumer: string;
+  producer: string;
+  package: string;
+  capabilityRef: string;
+}
+
+/** A validated inter-epic edge — both endpoints resolved to plan keys, ready to persist as a
+ * {@link PlanDep} (`plan_key = consumer`, `depends_on_plan_key = producer`). */
+export interface ResolvedEpicSetDep {
+  consumer: string;
+  producer: string;
+  package: string;
+  capabilityRef: string;
+}
+
+/** A set-admission validation failure that carries the HTTP status the door returns at the edge
+ * (always a 4xx — a malformed set is the caller's error, not a server fault). */
+export class EpicSetValidationError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "EpicSetValidationError";
+    this.status = status;
+  }
+}
+
+/** Narrow an untyped value to a plain object so its fields can be read as `unknown`. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Pure, side-effect-free validation of a submitted epic set's SHAPE and DAG — run BEFORE any
+ * `admitPlan` call so a cycle or dangling edge is rejected with nothing half-started. Given the
+ * submitted set's plan keys (already parsed, in submission order) and the raw edges, it:
+ *   • rejects an empty set;
+ *   • rejects a duplicate epic in the set;
+ *   • parses each edge endpoint and rejects an unparseable/self/dangling edge (an endpoint not in
+ *     the submitted set);
+ *   • rejects a blank `package`/`capabilityRef`;
+ *   • rejects a cycle in the consumer→producer graph, naming the edge that closes it.
+ * Returns the edges with both endpoints resolved to plan keys. Throws {@link EpicSetValidationError}
+ * (status 400) at the first offending input. Idempotent-friendly: a duplicate EDGE (same
+ * consumer→producer submitted twice) is collapsed, not rejected, so a retried set validates.
+ *
+ * `deps` is accepted as `unknown[]` because it arrives straight from an untyped request body
+ * (`startEpicSet` forwards `body.deps` verbatim). Every entry's shape is therefore validated
+ * defensively here — a non-object entry (`null`, `{}`), or a non-string endpoint / `package` /
+ * `capabilityRef`, maps to a clean {@link EpicSetValidationError} (400), never an uncaught
+ * TypeError (500). */
+export function validateEpicSet(planKeys: string[], deps: readonly unknown[]): ResolvedEpicSetDep[] {
+  if (planKeys.length === 0) {
+    throw new EpicSetValidationError(400, "epic set is empty — submit at least one epic");
+  }
+  const inSet = new Set<string>();
+  for (const key of planKeys) {
+    if (inSet.has(key)) {
+      throw new EpicSetValidationError(400, `epic ${key} appears more than once in the submitted set`);
+    }
+    inSet.add(key);
+  }
+
+  const resolveEndpoint = (ref: string, role: "consumer" | "producer"): string => {
+    // Trim like the epic-member path (`parseIssue(ref.trim())` in startEpicSet) so an otherwise-valid
+    // padded endpoint (" owner/repo#1 ") from an untyped JSON payload is not rejected as unparseable.
+    const parsed = parseIssue(ref.trim());
+    if (!parsed) {
+      throw new EpicSetValidationError(
+        400,
+        `dependency ${role} "${ref}" could not be parsed (use owner/repo#123 or an issue URL)`,
+      );
+    }
+    if (!inSet.has(parsed.planKey)) {
+      throw new EpicSetValidationError(
+        400,
+        `dependency ${role} ${parsed.planKey} is not one of the submitted epics — every edge must ` +
+          `connect two epics in the set`,
+      );
+    }
+    return parsed.planKey;
+  };
+
+  const resolved: ResolvedEpicSetDep[] = [];
+  const seenEdges = new Set<string>();
+  // consumer plan key → set of producer plan keys it depends on (for the DAG / cycle check).
+  const adjacency = new Map<string, Set<string>>();
+  for (const rawDep of deps) {
+    if (!isRecord(rawDep)) {
+      throw new EpicSetValidationError(
+        400,
+        "each dependency must be an object with consumer, producer, package and capabilityRef fields",
+      );
+    }
+    if (typeof rawDep.consumer !== "string" || typeof rawDep.producer !== "string") {
+      throw new EpicSetValidationError(
+        400,
+        "each dependency needs string consumer and producer endpoints (owner/repo#123 or an issue URL)",
+      );
+    }
+    const consumer = resolveEndpoint(rawDep.consumer, "consumer");
+    const producer = resolveEndpoint(rawDep.producer, "producer");
+    if (consumer === producer) {
+      throw new EpicSetValidationError(400, `epic ${consumer} cannot depend on itself`);
+    }
+    const pkg = (typeof rawDep.package === "string" ? rawDep.package : "").trim();
+    const capabilityRef = (typeof rawDep.capabilityRef === "string" ? rawDep.capabilityRef : "").trim();
+    if (pkg.length === 0) {
+      throw new EpicSetValidationError(
+        400,
+        `dependency ${consumer} → ${producer} is missing a package (the producer's published package)`,
+      );
+    }
+    if (capabilityRef.length === 0) {
+      throw new EpicSetValidationError(
+        400,
+        `dependency ${consumer} → ${producer} is missing a capabilityRef (the producer's issue handle)`,
+      );
+    }
+    const edgeId = `${consumer}\u0000${producer}`;
+    if (seenEdges.has(edgeId)) continue; // duplicate edge in one submission → collapse (idempotent)
+    seenEdges.add(edgeId);
+    resolved.push({ consumer, producer, package: pkg, capabilityRef });
+    const producers = adjacency.get(consumer) ?? new Set<string>();
+    producers.add(producer);
+    adjacency.set(consumer, producers);
+  }
+
+  assertAcyclic(adjacency);
+  return resolved;
+}
+
+/** Depth-first cycle check over the consumer→producer graph. Throws {@link EpicSetValidationError}
+ * (400) naming an edge on the cycle the moment one is found — the "reject at the offending edge"
+ * guarantee. A pure in-memory walk (no I/O), so it runs before any admission side effect. */
+function assertAcyclic(adjacency: Map<string, Set<string>>): void {
+  const VISITING = 1;
+  const DONE = 2;
+  const state = new Map<string, number>();
+  const visit = (node: string, stack: string[]): void => {
+    state.set(node, VISITING);
+    stack.push(node);
+    for (const next of adjacency.get(node) ?? []) {
+      const s = state.get(next);
+      if (s === VISITING) {
+        throw new EpicSetValidationError(
+          400,
+          `dependency cycle detected: ${[...stack, next].join(" → ")} — the edge set must be a DAG`,
+        );
+      }
+      if (s !== DONE) visit(next, stack);
+    }
+    stack.pop();
+    state.set(node, DONE);
+  };
+  for (const node of adjacency.keys()) {
+    if (state.get(node) !== DONE) visit(node, []);
+  }
+}
+
 /** Register a plan row (if new) and start the plan-fanout process. Idempotent on
  * planKey: a plan already in flight is not restarted. */
 export async function startPlan(

package/app/planGateway.test.ts

@@ -0,0 +1,106 @@
+// Tests for the `plans` gateway's write-time epic-bucket projection (issue #298) and its one-shot
+// backfill. The gateway wraps the plain table so EVERY writer — startPlan, the record workers, the
+// delivery poller, the acknowledge-epic op — automatically gets a fresh `list_bucket`/`ack_open`
+// projection without passing them: the single write path is the only place `deriveEpicBucket` /
+// `epicIsAcknowledgeable` are applied. Mirrors app/featureGateway.test.ts.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { backfillPlanBuckets, plans } from "./plan.ts";
+
+// In-memory record gateway with the same semantics the real Table exposes. The `plans` proxy wraps
+// whatever data.table returns, so this exercises the real proxy.
+function memData(): { data: DataLayer; rows: any[] } {
+  const rows: any[] = [];
+  function tbl(_name: string, pk = "id") {
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+        return r ? 1 : 0;
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, rows };
+}
+
+test("insert projects list_bucket/ack_open from status without the caller passing them", async () => {
+  const { data, rows } = memData();
+  await plans(data).insert({ plan_key: "o/r#1", status: "planning" });
+  assertEquals(rows[0].list_bucket, "active");
+  assertEquals(rows[0].ack_open, 0);
+});
+
+test("status flip to done+converging keeps the epic Active (no vanish)", async () => {
+  const { data, rows } = memData();
+  rows.push({ plan_key: "o/r#2", status: "dispatched", delivery: null });
+  // record-results marks the epic done; the delivery poller then sets converging.
+  await plans(data).update("o/r#2", { status: "done" });
+  assertEquals(rows[0].list_bucket, "active");
+  await plans(data).update("o/r#2", { delivery: "converging", delivery_label: "1/2 slices merged, 1 converging" });
+  assertEquals(rows[0].list_bucket, "active");
+  assertEquals(rows[0].ack_open, 0);
+});
+
+test("delivery landing opens the Dismiss affordance (ack_open=1) but keeps it Active until acknowledged", async () => {
+  const { data, rows } = memData();
+  rows.push({ plan_key: "o/r#3", status: "done", delivery: "converging" });
+  await plans(data).update("o/r#3", { delivery: "landed", delivery_label: "2/2 slices merged" });
+  assertEquals(rows[0].list_bucket, "active");
+  assertEquals(rows[0].ack_open, 1);
+  // Operator dismisses → gateway reprojects to History, ack_open closes.
+  await plans(data).update("o/r#3", { acknowledged_at: "2024-01-01T00:00:00Z" });
+  assertEquals(rows[0].list_bucket, "history");
+  assertEquals(rows[0].ack_open, 0);
+});
+
+test("a projection-irrelevant patch (wave_label only) does not disturb the stored bucket", async () => {
+  const { data, rows } = memData();
+  rows.push({ plan_key: "o/r#4", status: "done", delivery: "landed", list_bucket: "active", ack_open: 1 });
+  await plans(data).update("o/r#4", { wave_label: "2/2" });
+  assertEquals(rows[0].list_bucket, "active");
+  assertEquals(rows[0].ack_open, 1);
+});
+
+test("a direct write to list_bucket is overridden by the canonical derivation (no bypass)", async () => {
+  const { data, rows } = memData();
+  rows.push({ plan_key: "o/r#5", status: "done", delivery: "converging" });
+  // A caller tries to force History; the gateway re-derives from status+delivery and overrides it.
+  await plans(data).update("o/r#5", { list_bucket: "history" });
+  assertEquals(rows[0].list_bucket, "active");
+});
+
+test("backfillPlanBuckets stamps only legacy (NULL list_bucket) rows, idempotently", async () => {
+  const { data, rows } = memData();
+  rows.push({ plan_key: "o/r#legacy", status: "done", delivery: "converging", list_bucket: null, ack_open: null });
+  rows.push({ plan_key: "o/r#fresh", status: "planning", list_bucket: "active", ack_open: 0 });
+  const stamped = await backfillPlanBuckets(data);
+  assertEquals(stamped, 1);
+  assertEquals(rows[0].list_bucket, "active");
+  assertEquals(rows[0].ack_open, 0);
+  // Second pass is a no-op: every row is now projected.
+  assertEquals(await backfillPlanBuckets(data), 0);
+});
+
+test("terminal failed epic buckets to History", async () => {
+  const { data, rows } = memData();
+  rows.push({ plan_key: "o/r#6", status: "dispatched" });
+  await plans(data).update("o/r#6", { status: "failed" });
+  assertEquals(rows[0].list_bucket, "history");
+  assert(!rows[0].ack_open);
+});

package/app/service.ts

@@ -33,7 +33,7 @@ import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./mergeProtocol.ts";
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
-import { planReviews, plans, planTaskDeps, planTasks } from "./plan.ts";
+import { backfillPlanBuckets, planReviews, plans, planTaskDeps, planTasks } from "./plan.ts";
 import { derivePromotionState, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
 import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
@@ -1773,6 +1773,11 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
  * on every poll. */
 let featureStagesBackfilled = false;
 
+/** One-shot guard so the epic-bucket backfill (`backfillPlanBuckets`, #298) runs at most once per
+ * process, on the first `pollOnce` — re-projecting pre-migration-042 `plans` rows whose
+ * `list_bucket` is still NULL. The gateway keeps every future write fresh; idempotent regardless. */
+let planBucketsBackfilled = false;
+
 export async function pollOnce(
   data: DataLayer,
   engine: EngineClient,
@@ -1789,6 +1794,13 @@ export async function pollOnce(
     await backfillFeatureStages(data);
     featureStagesBackfilled = true;
   }
+  // One-shot: re-project any pre-#298 `plans` rows whose `list_bucket` is still NULL, so a legacy
+  // epic buckets correctly into Active/History from the first pass. Guard armed only after success so
+  // a transient failure retries next pass (mirrors the feature-stage backfill above).
+  if (!planBucketsBackfilled) {
+    await backfillPlanBuckets(data);
+    planBucketsBackfilled = true;
+  }
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
   await pollDelivery(data);

package/db/migrations/044_plan_list_bucket.sql

@@ -0,0 +1,32 @@
+-- 044_plan_list_bucket.sql — issue #298: bucket EPICS on the derived `delivery` rollup, not raw
+-- `plan.status`, so a `done` epic whose slice PRs are still CONVERGING — or one that has fully LANDED
+-- but still needs its integration→main promotion PR — does NOT silently vanish from the Active epic
+-- lists the instant `status = done`. Mirrors the feature-run Active/History tick-off partition
+-- (038/039 `feature_runs`): reify the partition as a derived, write-time-projected column so the
+-- declarative epic/overview page tabs can filter with only stored `{"field":…}` `in` clauses (the
+-- dataGrid page DSL has no OR / IS NULL), and give epics the same operator "Dismiss" affordance
+-- feature runs already have.
+--
+-- Columns (all maintained by the `plans` gateway — app/plan.ts — from the pure `deriveEpicBucket` /
+-- `epicIsAcknowledgeable` helpers in app/delivery.ts on every write, never hand-derived in SQL, the
+-- page, or a poller):
+--   • acknowledged_at — NULL until an operator dismisses a RESOLVED epic (acknowledge-epic) — landed
+--                       or resolved-not-landed (`delivery=null`); only still-`converging` epics are
+--                       rejected. The twin of feature_runs.acknowledged_at (039).
+--   • list_bucket     — 'active' | 'history': deriveEpicBucket(status, delivery, acknowledged_at).
+--                       Active = live epics (planning/dispatched) + `done` epics not yet acknowledged
+--                       (still converging, landed-but-unpromoted, or resolved-not-landed); History =
+--                       acknowledged `done` epics and terminal failed/abandoned epics.
+--   • ack_open        — 1 | 0: 1 iff the epic is a RESOLVED (`done`, not `converging`) but
+--                       unacknowledged epic — the Active states that carry the Dismiss affordance — so
+--                       the page's `showWhenField` gates the button precisely. Mirrors
+--                       feature_runs.escalation_open (040).
+--
+-- Forward-only, additive (expand): all nullable with no default, so pre-#298 rows grandfather in as
+-- NULL and never gate control flow. `backfillPlanBuckets` (app/plan.ts) stamps legacy rows once at
+-- boot, and the gateway keeps every future write fresh. Numbered after the current highest prefix on
+-- origin/main (041); the runner wraps each file in its own transaction, so this file must NOT contain
+-- BEGIN/COMMIT.
+ALTER TABLE plans ADD COLUMN acknowledged_at TEXT;
+ALTER TABLE plans ADD COLUMN list_bucket TEXT;
+ALTER TABLE plans ADD COLUMN ack_open INTEGER;