@nanobpm/nano-workforce 0.88.1 → 0.90.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.90.0](https://github.com/nanobpm/nano-workforce/compare/v0.89.0...v0.90.0) (2026-08-19)
+
+
+### Features
+
+* **convergence:** surface epic / cross-slice lineage on the PR-row detail ([#307](https://github.com/nanobpm/nano-workforce/issues/307)) ([7010b88](https://github.com/nanobpm/nano-workforce/commit/7010b88889529aec173c552bab2a1e7b881ba9da)), closes [nanobpm/nano-workforce#304](https://github.com/nanobpm/nano-workforce/issues/304)
+
+# [0.89.0](https://github.com/nanobpm/nano-workforce/compare/v0.88.1...v0.89.0) (2026-08-19)
+
+
+### Features
+
+* auto-open the epic integration-branch → default-branch promotion PR on landing ([#299](https://github.com/nanobpm/nano-workforce/issues/299)) ([#300](https://github.com/nanobpm/nano-workforce/issues/300)) ([24a8854](https://github.com/nanobpm/nano-workforce/commit/24a885484ae69bd654edd4d05fa198561e2db5dd))
+
 ## [0.88.1](https://github.com/nanobpm/nano-workforce/compare/v0.88.0...v0.88.1) (2026-08-18)
 
 

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, coalesceTitle, ensureBaseBranch, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError } from "./github.ts";
+import { BaseBranchMustExistError, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError, listPrsForHead } from "./github.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
 // files (named `f{index}`), setting a `Link: rel="next"` header whenever a later page exists.
@@ -335,3 +335,96 @@ test("coalesceTitle: skips a blank middle candidate to the next non-blank one",
   assertEquals(coalesceTitle("", "Prior title", "owner/repo#1"), "Prior title");
   assertEquals(coalesceTitle(null, "  ", "owner/repo#1"), "owner/repo#1");
 });
+
+// ── Epic promotion PR helpers (issue #299) ──────────────────────────────────
+// The promotion pass opens exactly one `epic/* → <default>` PR per landed epic. These unit tests
+// pin the GitHub token-transport primitives it relies on: reading PRs by head branch (idempotency
+// reconciliation), creating a PR, and the `ensurePromotionPr` reuse-vs-create decision.
+interface FakePulls {
+  repo: string;
+  // head branch → list of PRs opened from it
+  byHead: Map<string, { number: number; state: string; baseRef: string }[]>;
+  creates: { head: string; base: string; number: number }[];
+  next: number;
+}
+
+function pullsFetch(state: FakePulls) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = new URL(String(url));
+    const method = (init?.method ?? "GET").toUpperCase();
+    const path = u.pathname;
+    if (method === "GET" && path === `/repos/${state.repo}/pulls`) {
+      const head = (u.searchParams.get("head") ?? "").split(":").pop() ?? "";
+      const list = state.byHead.get(head) ?? [];
+      return Promise.resolve(
+        jsonResponse(
+          list.map((p) => ({
+            number: p.number,
+            html_url: `https://github.com/${state.repo}/pull/${p.number}`,
+            state: p.state,
+            base: { ref: p.baseRef },
+          })),
+        ),
+      );
+    }
+    if (method === "POST" && path === `/repos/${state.repo}/pulls`) {
+      // biome-ignore lint/plugin: test fixture parsing an external body shape
+      const body = JSON.parse(String(init?.body ?? "{}")) as { head?: string; base?: string };
+      const head = String(body.head ?? "");
+      const base = String(body.base ?? "");
+      const number = state.next++;
+      state.creates.push({ head, base, number });
+      const arr = state.byHead.get(head) ?? [];
+      arr.push({ number, state: "open", baseRef: base });
+      state.byHead.set(head, arr);
+      return Promise.resolve(jsonResponse({ number, html_url: `https://github.com/${state.repo}/pull/${number}` }, 201));
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  };
+}
+
+async function withPulls<T>(state: FakePulls, 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 = pullsFetch(state) as typeof fetch;
+  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;
+  }
+}
+
+function freshPulls(): FakePulls {
+  return { repo: "o/r", byHead: new Map(), creates: [], next: 500 };
+}
+
+test("listPrsForHead: returns the PRs opened from a head branch", async () => {
+  const state = freshPulls();
+  state.byHead.set("epic/x", [{ number: 12, state: "open", baseRef: "main" }]);
+  const list = await withPulls(state, () => listPrsForHead("o/r", "epic/x", "tok"));
+  assertEquals(list?.length, 1);
+  assertEquals(list?.[0].number, 12);
+  assertEquals(list?.[0].baseRef, "main");
+});
+
+test("createPullRequest: opens a PR and returns its number + url", async () => {
+  const state = freshPulls();
+  const pr = await withPulls(state, () => createPullRequest("o/r", "epic/x", "main", "T", "B", "tok"));
+  assertEquals(pr?.number, 500);
+  assertEquals(state.creates.length, 1);
+  assertEquals(state.creates[0].base, "main");
+});
+
+test("ensurePromotionPr: creates when none exists, then reuses on a re-run (idempotent)", async () => {
+  const state = freshPulls();
+  const first = await withPulls(state, () => ensurePromotionPr("o/r", "epic/x", "main", "T", "B", "tok"));
+  assertEquals(first?.created, true);
+  assertEquals(first?.number, 500);
+  const second = await withPulls(state, () => ensurePromotionPr("o/r", "epic/x", "main", "T", "B", "tok"));
+  assertEquals(second?.created, false);
+  assertEquals(second?.number, 500);
+  assertEquals(state.creates.length, 1);
+});

package/app/github.ts

@@ -1091,3 +1091,153 @@ export async function ensureBaseBranch(
   const created = await createBranchRef(repo, branch, defaultSha, token);
   return created ? "created" : "exists";
 }
+
+// ── Epic promotion PR (issue #299) ──────────────────────────────────────────
+// Once an epic's slices have all merged into its `epic/*` integration branch, the poller opens a
+// single `epic/* → <default>` promotion PR to deliver the epic. These helpers are the GitHub side
+// of that: discover an already-open promotion PR (idempotency against a crash between create and
+// the DB write) and, when none exists, create it.
+
+/** A pull request discovered for a head branch — the subset the promotion idempotency check reads. */
+export interface HeadPr {
+  number: number;
+  url: string;
+  state: string;
+  baseRef: string | null;
+}
+
+/** List the PRs (any state) whose HEAD branch is `headBranch` on `repo`. Used to reconcile the
+ * promotion PR idempotently: an `epic/*` integration branch is only ever the HEAD of its promotion
+ * PR (slices target it as their BASE), so any result is that promotion PR. Returns `null` when no
+ * transport is usable (idle — the caller retries next pass). */
+export async function listPrsForHead(
+  repo: string,
+  headBranch: string,
+  token: string,
+): Promise<HeadPr[] | null> {
+  if (await useGh()) {
+    const out = await runGh([
+      "pr",
+      "list",
+      "--repo",
+      repo,
+      "--head",
+      headBranch,
+      "--state",
+      "all",
+      "--json",
+      "number,url,state,baseRefName",
+      "--limit",
+      "20",
+    ]);
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const arr = JSON.parse(out) as { number?: number; url?: string; state?: string; baseRefName?: string | null }[];
+    return arr.map((p) => ({
+      number: Number(p.number),
+      url: p.url ?? "",
+      state: (p.state ?? "").toLowerCase(),
+      baseRef: p.baseRefName ?? null,
+    }));
+  }
+  if (!token) return null;
+  const owner = repo.split("/")[0];
+  const r = await fetch(
+    `https://api.github.com/repos/${repo}/pulls?state=all&head=${encodeURIComponent(`${owner}:${headBranch}`)}&per_page=20`,
+    { headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" } },
+  );
+  if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
+  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+  const arr = (await r.json()) as { number?: number; html_url?: string; state?: string; base?: { ref?: string | null } }[];
+  return arr.map((p) => ({
+    number: Number(p.number),
+    url: p.html_url ?? "",
+    state: (p.state ?? "").toLowerCase(),
+    baseRef: p.base?.ref ?? null,
+  }));
+}
+
+/** The identity of a freshly-created (or reused) PR. */
+export interface CreatedPr {
+  number: number;
+  url: string;
+}
+
+/** Open a pull request from `headBranch` into `baseBranch` on `repo`. Returns the new PR's
+ * number + URL, or `null` when no transport is usable (idle — the caller retries next pass). Throws
+ * on a genuine create failure so the caller logs and retries rather than silently losing the PR. */
+export async function createPullRequest(
+  repo: string,
+  headBranch: string,
+  baseBranch: string,
+  title: string,
+  body: string,
+  token: string,
+): Promise<CreatedPr | null> {
+  if (await useGh()) {
+    const out = await runGh([
+      "pr",
+      "create",
+      "--repo",
+      repo,
+      "--base",
+      baseBranch,
+      "--head",
+      headBranch,
+      "--title",
+      title,
+      "--body",
+      body,
+    ]);
+    // `gh pr create` prints the new PR's URL on stdout; parse its number from the canonical path.
+    const url = out.trim().split(/\s+/).pop() ?? "";
+    const m = url.match(/\/pull\/(\d+)/);
+    if (!m) throw new Error(`could not parse a PR number from \`gh pr create\` output: ${out.trim()}`);
+    return { number: Number(m[1]), url };
+  }
+  if (!token) return null;
+  const r = await fetch(`https://api.github.com/repos/${repo}/pulls`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      accept: "application/vnd.github+json",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ title, head: headBranch, base: baseBranch, body }),
+  });
+  if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}: ${(await r.text()).slice(0, 300)}`.trim());
+  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+  const j = (await r.json()) as { number?: number; html_url?: string };
+  return { number: Number(j.number), url: j.html_url ?? "" };
+}
+
+/** The outcome of `ensurePromotionPr`: the promotion PR's number + URL and whether THIS call
+ * created it (`created: false` ⇒ an existing one was reused, keeping the open idempotent). */
+export interface EnsurePromotionPrResult extends CreatedPr {
+  created: boolean;
+}
+
+/** Idempotently guarantee the `headBranch → baseBranch` promotion PR exists on `repo`. First
+ * reconciles against GitHub — an `epic/*` integration branch is only ever the HEAD of its own
+ * promotion PR, so ANY open/merged PR from it IS that promotion PR and is reused (this closes the
+ * window where a crash between GitHub-create and the DB write would otherwise duplicate the PR).
+ * Only when none exists is a new one created. Returns `null` when no transport is usable. */
+export async function ensurePromotionPr(
+  repo: string,
+  headBranch: string,
+  baseBranch: string,
+  title: string,
+  body: string,
+  token: string,
+): Promise<EnsurePromotionPrResult | null> {
+  const existing = await listPrsForHead(repo, headBranch, token);
+  if (existing === null) return null; // no transport → retry next pass
+  // Prefer a PR that already targets the intended base; otherwise reuse any PR from this branch
+  // (the head is unique to the promotion PR, so this can only be it).
+  const reuse = existing.find((p) => p.baseRef === baseBranch) ?? existing[0];
+  if (reuse && Number.isFinite(reuse.number) && reuse.number > 0) {
+    return { number: reuse.number, url: reuse.url, created: false };
+  }
+  const created = await createPullRequest(repo, headBranch, baseBranch, title, body, token);
+  if (!created) return null;
+  return { ...created, created: true };
+}

package/app/lineage.test.ts

@@ -75,7 +75,7 @@ test("feature: an escalated run surfaces the escalation stage", () => {
 
 test("epic: rolls up N slice PRs and stays active while any is in flight", () => {
   const t = deriveLineage(
-    { kind: "epic", key: "o/r#9", title: "Big epic", issueUrl: "u", status: "done", processKey: "e1" },
+    { kind: "epic", key: "o/r#9", title: "Big epic", issueUrl: "u", status: "done", processKey: "e1", epicPhase: "Implementing (wave 2/3)" },
     [
       pr({ prKey: "o/r#10", status: "merged" }),
       pr({ prKey: "o/r#11", status: "converging", processKey: "c11" }),
@@ -85,6 +85,7 @@ test("epic: rolls up N slice PRs and stays active while any is in flight", () =>
   assertEquals(t.kind, "epic");
   assertEquals(t.stage, "converging");
   assertEquals(t.stageLabel, "1/3 slices merged, 1 converging");
+  assertEquals(t.epicPhaseLabel, "Implementing (wave 2/3)", "an epic thread carries its stamped epic_phase down to member PRs");
   assertEquals(t.processKey, "c11");
   assertEquals(t.prCount, 3);
   assert(t.active);
@@ -92,17 +93,18 @@ test("epic: rolls up N slice PRs and stays active while any is in flight", () =>
 
 test("epic: all slices merged settles as merged", () => {
   const t = deriveLineage(
-    { kind: "epic", key: "o/r#9", title: "Big epic", issueUrl: "u", status: "done", processKey: "e1" },
+    { kind: "epic", key: "o/r#9", title: "Big epic", issueUrl: "u", status: "done", processKey: "e1", epicPhase: null },
     [pr({ prKey: "o/r#10", status: "merged" }), pr({ prKey: "o/r#11", status: "merged" })],
   );
   assertEquals(t.stage, "merged");
   assertEquals(t.stageLabel, "2/2 slices merged");
+  assertEquals(t.epicPhaseLabel, "2/2 slices merged", "a grandfathered epic (no epic_phase) falls back to its delivery-rollup stage label");
   assert(!t.active);
 });
 
 test("epic: mixed terminal (none in flight, not all merged) is resolved, not landed", () => {
   const t = deriveLineage(
-    { kind: "epic", key: "o/r#9", title: "E", issueUrl: "u", status: "done", processKey: "e1" },
+    { kind: "epic", key: "o/r#9", title: "E", issueUrl: "u", status: "done", processKey: "e1", epicPhase: "Finalizing" },
     [pr({ prKey: "o/r#10", status: "merged" }), pr({ prKey: "o/r#11", status: "abandoned" })],
   );
   assertEquals(t.stage, "resolved");
@@ -111,13 +113,23 @@ test("epic: mixed terminal (none in flight, not all merged) is resolved, not lan
 
 test("epic: planning with no PRs yet", () => {
   const t = deriveLineage(
-    { kind: "epic", key: "o/r#9", title: "E", issueUrl: "u", status: "planning", processKey: "e1" },
+    { kind: "epic", key: "o/r#9", title: "E", issueUrl: "u", status: "planning", processKey: "e1", epicPhase: "Planning" },
     [],
   );
   assertEquals(t.stage, "planning");
   assert(t.active);
 });
 
+test("feature/self-rooted threads carry no epic phase label", () => {
+  const feat = deriveLineage(
+    { kind: "feature", key: "o/r#1", title: "X", issueUrl: "u", status: "converging", processKey: "f1" },
+    [pr({ prKey: "o/r#2", status: "converging" })],
+  );
+  assertEquals(feat.epicPhaseLabel, null, "a feature PR is not an epic slice");
+  const self = deriveLineage({ kind: "pr", key: "o/r#5" }, [pr({ prKey: "o/r#5", status: "converging" })]);
+  assertEquals(self.epicPhaseLabel, null, "a self-rooted PR is not an epic slice");
+});
+
 // ── self-rooted (human/webhook) PR ───────────────────────────────────────────────────────────
 
 test("pr: a human/webhook PR with no origin is its own root", () => {
@@ -174,7 +186,7 @@ test("pollLineage: projects feature, epic, and self-rooted threads onto lineage_
     { feature_key: "o/r#1", title: "Feature", issue_url: "u1", status: "converging", process_key: "f1", pr_key: "o/r#100" },
   ];
   stores.plans = [
-    { plan_key: "o/r#2", title: "Epic", issue_url: "u2", status: "done", process_key: "e1" },
+    { plan_key: "o/r#2", title: "Epic", issue_url: "u2", status: "done", process_key: "e1", epic_phase: "Implementing (wave 1/2)" },
   ];
   stores.plan_tasks = [
     { id: 1, plan_key: "o/r#2", pr_key: "o/r#200" },
@@ -212,6 +224,14 @@ test("pollLineage: projects feature, epic, and self-rooted threads onto lineage_
   assertEquals(human?.stage, "merged");
   assertEquals(human?.active, 0);
 
+  // Epic-phase projection (#304): each epic slice PR gets its parent epic's phase label; the feature
+  // and self-rooted PRs (not epic slices) are left NULL, so their PR-row detail shows no epic panel.
+  const prById = (k: string) => stores.pull_requests.find((r: any) => r.pr_key === k);
+  assertEquals(prById("o/r#200").epic_phase_label, "Implementing (wave 1/2)", "epic slice S1 carries the epic phase");
+  assertEquals(prById("o/r#201").epic_phase_label, "Implementing (wave 1/2)", "epic slice S2 carries the epic phase");
+  assertEquals(prById("o/r#100").epic_phase_label ?? null, null, "a feature PR is not an epic slice");
+  assertEquals(prById("o/r#300").epic_phase_label ?? null, null, "a self-rooted PR is not an epic slice");
+
   // Idempotent: a second pass with no state change writes nothing new (same row count, same ts).
   const before = stores.lineage_threads.map((r: LineageThreadRow) => r.updated_at);
   await pollLineage(data);

package/app/lineage.ts

@@ -56,6 +56,10 @@ export type LineageOrigin =
       issueUrl: string | null;
       status: string;
       processKey: string | null;
+      // The epic's derived domain phase (`plans.epic_phase`, 038_plan_epic_phase.sql) — e.g.
+      // "Implementing (wave 3/5)". NULL for pre-#261 epics that never stamped a phase; the thread
+      // then falls back to its delivery-rollup `stageLabel` for the projected `epicPhaseLabel`.
+      epicPhase: string | null;
     }
   | {
       // A human/webhook PR with no originating request: its own root.
@@ -73,6 +77,12 @@ export interface LineageThread {
   stage: LineageStage;
   /** Human narrative rollup for the timeline (e.g. "Converging (round 2)", "3/5 slices merged, …"). */
   stageLabel: string;
+  /** The epic-phase/stage label projected onto each member PR's `pull_requests.epic_phase_label`, so
+   *  the Convergence PR-row detail can show an epic slice its parent epic's phase (issue #304). For an
+   *  epic thread it is the epic's `epic_phase` (e.g. "Implementing (wave 3/5)"), falling back to the
+   *  delivery-rollup `stageLabel` when the epic never stamped a phase. NULL for feature/self-rooted
+   *  threads — their member PRs are not epic slices, so the epic panel stays empty for them. */
+  epicPhaseLabel: string | null;
   /** The active-frontier process instance (for the processExplorer link), best-effort. */
   processKey: string | null;
   prKeys: string[];
@@ -238,6 +248,12 @@ export function deriveLineage(origin: LineageOrigin, prsIn: readonly LineagePr[]
   }
 
   const active = !TERMINAL_STAGES.includes(stage);
+  // Epic slices carry their parent epic's phase down to the PR-row detail (issue #304): prefer the
+  // epic's own stamped `epic_phase`, falling back to the delivery-rollup `stageLabel` for a
+  // grandfathered epic that never stamped one. Feature/self-rooted threads are not epics, so their
+  // member PRs get no epic label.
+  const epicPhaseLabel =
+    origin.kind === "epic" ? (origin.epicPhase ?? stageLabel) : null;
   return {
     rootRequestKey: origin.key,
     kind: origin.kind,
@@ -245,6 +261,7 @@ export function deriveLineage(origin: LineageOrigin, prsIn: readonly LineagePr[]
     issueUrl: origin.kind === "pr" ? null : origin.issueUrl,
     stage,
     stageLabel,
+    epicPhaseLabel,
     processKey,
     prKeys,
     prCount: prKeys.length,
@@ -287,6 +304,9 @@ interface PrRow {
   process_key: string | null;
   outcome: string | null;
   root_request_key: string | null;
+  // Epic-phase projection this module maintains (issue #304, migration 043): the parent epic's phase
+  // label for an epic slice PR, NULL otherwise. Read here only to keep the write idempotent.
+  epic_phase_label: string | null;
 }
 
 const prRows = (data: DataLayer) => data.table<PrRow>("pull_requests", "pr_key");
@@ -324,7 +344,9 @@ function toLineagePr(row: PrRow): LineagePr {
 
 /** Assemble the origin + PR set for every root from the live gateway rows, then derive each thread.
  * Reused by both `getLineage` (single root, on demand) and `pollLineage` (all roots, projected). */
-async function collectThreads(data: DataLayer): Promise<Map<string, LineageThread>> {
+async function collectThreads(
+  data: DataLayer,
+): Promise<{ threads: Map<string, LineageThread>; allPrs: PrRow[] }> {
   const allPrs = await prRows(data).all();
   const prByKey = new Map<string, PrRow>();
   for (const pr of allPrs) prByKey.set(pr.pr_key, pr);
@@ -388,7 +410,7 @@ async function collectThreads(data: DataLayer): Promise<Map<string, LineageThrea
     threads.set(rootKey, deriveLineage({ kind: "pr", key: rootKey }, prs.map(toLineagePr)));
   }
 
-  return threads;
+  return { threads, allPrs };
 }
 
 /** Union the PRs a feature root owns: those threaded to it + its own denormalised `pr_key`. */
@@ -446,6 +468,7 @@ function epicOrigin(plan: Plan): LineageOrigin {
     issueUrl: plan.issue_url,
     status: plan.status,
     processKey: plan.process_key,
+    epicPhase: plan.epic_phase,
   };
 }
 
@@ -455,7 +478,7 @@ export async function getLineage(
   data: DataLayer,
   rootRequestKey: string,
 ): Promise<LineageThread | null> {
-  const threads = await collectThreads(data);
+  const { threads } = await collectThreads(data);
   return threads.get(rootRequestKey) ?? null;
 }
 
@@ -463,7 +486,7 @@ export async function getLineage(
  * deterministic order (the projection has no per-thread timestamp to sort on, and equal-`active`
  * ties would otherwise be nondeterministic across passes). */
 export async function listLineage(data: DataLayer): Promise<LineageThread[]> {
-  const threads = await collectThreads(data);
+  const { threads } = await collectThreads(data);
   return [...threads.values()].sort(
     (a, b) => Number(b.active) - Number(a.active) || a.rootRequestKey.localeCompare(b.rootRequestKey),
   );
@@ -474,8 +497,9 @@ export async function listLineage(data: DataLayer): Promise<LineageThread[]> {
  * when the projection actually changes. Best-effort; per-root failures are isolated. */
 export async function pollLineage(data: DataLayer): Promise<void> {
   let threads: Map<string, LineageThread>;
+  let allPrs: PrRow[];
   try {
-    threads = await collectThreads(data);
+    ({ threads, allPrs } = await collectThreads(data));
   } catch (err) {
     console.error(`[poller] lineage collect: ${err}`);
     return;
@@ -534,4 +558,35 @@ export async function pollLineage(data: DataLayer): Promise<void> {
       console.error(`[poller] lineage ${thread.rootRequestKey}: ${err}`);
     }
   }
+  await projectEpicPhaseLabels(data, threads, allPrs);
+}
+
+/** Denormalise each epic thread's phase label down onto its member PRs' `pull_requests.epic_phase_label`
+ * (issue #304), so the Convergence PR-row detail can show an escalated slice its parent epic's phase
+ * without a cross-join to `plans` / `lineage_threads`. Every PR belongs to exactly one thread, so a
+ * PR whose thread is a feature/self-root is cleared to NULL — no stale epic label survives if a PR is
+ * re-rooted. Idempotent: writes only the rows whose label actually changed. Mirrors the write-time
+ * projection convention (`delivery_label`, `epic_phase`). Best-effort; failures are isolated. */
+async function projectEpicPhaseLabels(
+  data: DataLayer,
+  threads: Map<string, LineageThread>,
+  allPrs: PrRow[],
+): Promise<void> {
+  // Desired label per member PR: an epic thread stamps its `epicPhaseLabel`, every other thread NULL.
+  const desired = new Map<string, string | null>();
+  for (const thread of threads.values()) {
+    for (const key of thread.prKeys) desired.set(key, thread.epicPhaseLabel);
+  }
+  // Reuse the PR rows `collectThreads` already read this pass rather than re-scanning the whole
+  // `pull_requests` table — the projection only writes the rows whose label actually changed.
+  const table = prRows(data);
+  for (const pr of allPrs) {
+    const want = desired.get(pr.pr_key) ?? null;
+    if ((pr.epic_phase_label ?? null) === want) continue; // steady state — no write
+    try {
+      await table.update(pr.pr_key, { epic_phase_label: want });
+    } catch (err) {
+      console.error(`[poller] lineage epic-phase ${pr.pr_key}: ${err}`);
+    }
+  }
 }

package/app/migration042.test.ts

@@ -0,0 +1,51 @@
+// Regression guard for migration 042 (issue #299): the promotion columns on `plans`. Proves the
+// migration applies cleanly onto the pre-#299 `plans` shape and that a landed epic can record its
+// promotion PR + state.
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals } from "#test-assert";
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  // Minimal pre-#299 `plans` shape the migration extends (only the columns this test touches).
+  db.exec(
+    "CREATE TABLE plans (plan_key TEXT PRIMARY KEY, base_branch TEXT, delivery TEXT, delivery_label TEXT);",
+  );
+  db.prepare("INSERT INTO plans (plan_key, base_branch, delivery) VALUES (?, ?, ?)").run(
+    "o/r#295",
+    "epic/test-dsl",
+    "landed",
+  );
+  const sql = readFileSync(
+    fileURLToPath(new URL("../db/migrations/042_plan_promotion.sql", import.meta.url)),
+    "utf8",
+  );
+  db.exec(sql);
+  return db;
+}
+
+test("migration 042 applies cleanly and adds nullable promotion columns", () => {
+  const db = migratedDb();
+  const row = db
+    .prepare("SELECT promotion_pr, promotion_state FROM plans WHERE plan_key = ?")
+    .get("o/r#295") as { promotion_pr: string | null; promotion_state: string | null };
+  // Grandfathered: both columns default to NULL on the existing row.
+  assertEquals(row.promotion_pr, null);
+  assertEquals(row.promotion_state, null);
+});
+
+test("migration 042 lets a landed epic record its promotion PR + state", () => {
+  const db = migratedDb();
+  db.prepare("UPDATE plans SET promotion_pr = ?, promotion_state = ? WHERE plan_key = ?").run(
+    "o/r#500",
+    "open",
+    "o/r#295",
+  );
+  const row = db
+    .prepare("SELECT promotion_pr, promotion_state FROM plans WHERE plan_key = ?")
+    .get("o/r#295") as { promotion_pr: string; promotion_state: string };
+  assertEquals(row.promotion_pr, "o/r#500");
+  assertEquals(row.promotion_state, "open");
+});

package/app/migration043.test.ts

@@ -0,0 +1,62 @@
+// Regression guard for migration 043's epic_phase_label backfill (issue #304). The Convergence
+// PR-row detail surfaces an epic slice's parent-epic phase via `pull_requests.epic_phase_label`. The
+// column is maintained going forward by `pollLineage` (`projectEpicPhaseLabels`), but pre-existing
+// rows must be backfilled at deploy time so the epic panel is populated before the first poll pass:
+// an epic slice PR (its `root_request_key` is an epic `plans.plan_key`) takes that epic's
+// `plans.epic_phase`; a feature/self-rooted PR (no matching plan) stays NULL — no empty epic panel.
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals } from "#test-assert";
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  // Minimal pre-043 shape: pull_requests WITH root_request_key (037) but WITHOUT epic_phase_label
+  // (043 ADD COLUMNs it), plus the plans table the backfill joins on for the epic phase.
+  db.exec(`
+    CREATE TABLE pull_requests (pr_key TEXT PRIMARY KEY, repo TEXT, number INTEGER, url TEXT,
+      status TEXT, root_request_key TEXT, created_at TEXT, updated_at TEXT);
+    CREATE TABLE plans (plan_key TEXT PRIMARY KEY, epic_phase TEXT);
+  `);
+  const ins = (k: string, root: string) =>
+    db
+      .prepare(
+        `INSERT INTO pull_requests (pr_key, repo, number, url, status, root_request_key, created_at, updated_at)
+         VALUES (?, 'o/r', 1, 'u', 'converging', ?, 't', 't')`,
+      )
+      .run(k, root);
+  ins("o/r#20", "o/r#2"); // epic slice of a phased epic
+  ins("o/r#21", "o/r#3"); // epic slice of a grandfathered epic (epic_phase NULL)
+  ins("o/r#30", "o/r#30"); // self-rooted (human/webhook) PR — root is its own key, no plan
+  ins("o/r#40", "o/r#1"); // feature-rooted PR — root is a feature key, no matching plan
+  db.prepare("INSERT INTO plans (plan_key, epic_phase) VALUES ('o/r#2', 'Implementing (wave 3/5)')").run();
+  db.prepare("INSERT INTO plans (plan_key, epic_phase) VALUES ('o/r#3', NULL)").run();
+
+  const sql = readFileSync(
+    fileURLToPath(new URL("../db/migrations/043_pr_epic_phase.sql", import.meta.url)),
+    "utf8",
+  );
+  db.exec(sql);
+  return db;
+}
+
+test("migration 043 backfills epic slice PRs with their epic's phase and leaves non-epic PRs NULL", () => {
+  const db = migratedDb();
+  const labelOf = (k: string) =>
+    (
+      db.prepare("SELECT epic_phase_label AS l FROM pull_requests WHERE pr_key = ?").get(k) as {
+        l: string | null;
+      }
+    ).l;
+
+  // An epic slice roots on its epic's plan_key, so it inherits that epic's stamped phase.
+  assertEquals(labelOf("o/r#20"), "Implementing (wave 3/5)");
+  // A slice of a grandfathered epic (epic_phase NULL) stays NULL — the poller reconciles the
+  // delivery-rollup fallback on its next pass; the migration only seeds the stamped phase.
+  assertEquals(labelOf("o/r#21"), null);
+  // A self-rooted PR has no matching plan → no epic panel.
+  assertEquals(labelOf("o/r#30"), null);
+  // A feature-rooted PR has no matching plan → no epic panel.
+  assertEquals(labelOf("o/r#40"), null);
+});

package/app/plan.ts

@@ -89,6 +89,17 @@ export interface Plan {
   // view can show which phase the epic is IN rather than only the process-instance terminal status.
   // Display-only; NULL until the lifecycle first stamps it (grandfathers pre-#261 rows).
   epic_phase: string | null;
+  // Epic integration-branch → default-branch promotion (042_plan_promotion.sql, #299). When an epic
+  // targets a custom `epic/*` integration branch and every slice PR has merged (`delivery = landed`),
+  // the poller's `pollPromotion` pass opens exactly ONE `epic/* → <default>` promotion PR and drives
+  // it through the same convergence + merge protocol as every other PR (see app/promotion.ts).
+  //   • promotion_pr    — the `owner/repo#N` key of that promotion PR, or NULL until one is opened.
+  //                       PRIMARY idempotency key: a set value never re-opens a second PR.
+  //   • promotion_state — the epic-card progression 'ready' → 'open' → 'promoted', or NULL until the
+  //                       epic first becomes promotable (also NULL forever for a `main`-based epic,
+  //                       which has nothing to promote). Display-only; projected by the poller.
+  promotion_pr: string | null;
+  promotion_state: string | null;
   created_at: string;
   updated_at: string;
 }