@nanobpm/nano-workforce 0.88.1 → 0.89.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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/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/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;
 }

package/app/promotion.test.ts

@@ -0,0 +1,56 @@
+// Pure derivation tests for epic promotion (issue #299). `app/promotion.ts` is the I/O-free core of
+// the "promote a landed epic's integration branch to the default branch" automation: the promotable
+// predicate, the epic-card state derivation, and the promotion PR title/body rendering. The poller
+// (`pollPromotion`) is exercised separately in `app/promotionPoll.test.ts`.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { derivePromotionState, isEpicIntegrationBranch, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
+
+test("isPromotable: landed on an epic/* base is promotable", () => {
+  assert(isPromotable({ delivery: "landed", base_branch: "epic/test-dsl" }));
+});
+
+test("isPromotable: a main-based epic has nothing to promote", () => {
+  assert(!isPromotable({ delivery: "landed", base_branch: "main" }));
+  assert(!isPromotable({ delivery: "landed", base_branch: null }));
+});
+
+test("isPromotable: a still-converging epic is never promoted, even on an epic/* base", () => {
+  assert(!isPromotable({ delivery: "converging", base_branch: "epic/x" }));
+  assert(!isPromotable({ delivery: null, base_branch: "epic/x" }));
+});
+
+test("isEpicIntegrationBranch: only epic/* branches match", () => {
+  assert(isEpicIntegrationBranch("epic/foo"));
+  assert(!isEpicIntegrationBranch("main"));
+  assert(!isEpicIntegrationBranch("feat/epic-ish"));
+  assert(!isEpicIntegrationBranch(null));
+});
+
+test("derivePromotionState: ready → open → promoted progression", () => {
+  assertEquals(derivePromotionState(false, false), "ready");
+  assertEquals(derivePromotionState(true, false), "open");
+  assertEquals(derivePromotionState(true, true), "promoted");
+});
+
+test("promotionPrTitle: names branch, target, and epic identity", () => {
+  assertEquals(
+    promotionPrTitle("epic/test-dsl", "main", "Assertion DSL"),
+    "Promote epic/test-dsl → main: Assertion DSL",
+  );
+});
+
+test("promotionPrBody: closes the epic issue and lists the merged slices", () => {
+  const body = promotionPrBody("epic/x", "main", "o/r#295", ["o/r#299", "o/r#304"]);
+  assert(body.includes("epic/x"));
+  assert(body.includes("main"));
+  assert(body.includes("Closes o/r#295"));
+  assert(body.includes("- o/r#299"));
+  assert(body.includes("- o/r#304"));
+});
+
+test("promotionPrBody: omits the slice list when there are none", () => {
+  const body = promotionPrBody("epic/x", "main", "o/r#295", []);
+  assert(body.includes("Closes o/r#295"));
+  assert(!body.includes("Merged slices:"));
+});

package/app/promotion.ts

@@ -0,0 +1,84 @@
+// Epic promotion derivation (issue #299): the pure, I/O-free core of the "promote a landed epic's
+// integration branch to the default branch" automation. Extracted from `service.ts` (mirroring how
+// `deriveDelivery` lives in `delivery.ts`) so the promotion predicate + state derivation + PR
+// title/body rendering are unit-testable without a data layer or GitHub transport.
+//
+// The gap this closes: when an epic targets a custom `epic/*` integration branch, its slices PR
+// *into* that branch. Once every slice merges (`plans.delivery = landed`, projected by
+// `pollDelivery`), the epic is delivered ON the integration branch — but nothing opens the final
+// `epic/* → <default>` promotion PR. `pollPromotion` (app/service.ts) uses these helpers to open
+// exactly one such PR per landed epic and drive it through the same convergence + merge protocol.
+
+/** The epic-card promotion progression for a landed epic (issue #299 point 3), denormalised onto
+ * `plans.promotion_state`:
+ *   • `ready`    — landed on an `epic/*` base; the promotion PR has not been opened yet.
+ *   • `open`     — the promotion PR is open and converging toward merge.
+ *   • `promoted` — the promotion PR merged; the epic is delivered on the default branch. */
+export type PromotionState = "ready" | "open" | "promoted";
+
+/** The subset of a plan the promotion derivation reads. */
+export interface PromotablePlan {
+  /** The derived delivery signal (`deriveDelivery`): only a `landed` epic is ever promotable. */
+  delivery: string | null;
+  /** The epic's target integration branch, e.g. `epic/test-dsl`. NULL / non-`epic/*` ⇒ nothing to
+   * promote (a `main`-based epic's slices already landed on the default branch). */
+  base_branch: string | null;
+}
+
+/** Whether `branch` is an auto-created `epic/*` integration branch (mirrors github.ts's
+ * `isEpicBranch` — kept local so this module stays pure/dependency-free). */
+export function isEpicIntegrationBranch(branch: string | null): branch is string {
+  return !!branch && branch.startsWith("epic/");
+}
+
+/** Whether an epic is eligible for auto-promotion: its fan-out has LANDED (every slice PR merged —
+ * the `deriveDelivery` `landed` predicate, which already encodes `prsInFlight == 0 && prsMerged ==
+ * prsOpened && prsOpened > 0`, so a still-converging epic is never promoted) AND it targets a custom
+ * `epic/*` integration branch. A `main`-based epic (slices went straight to the default branch) has
+ * nothing to promote. */
+export function isPromotable(plan: PromotablePlan): boolean {
+  return plan.delivery === "landed" && isEpicIntegrationBranch(plan.base_branch);
+}
+
+/** Derive the promotion-state projection for a promotable epic from whether its promotion PR exists
+ * yet and whether that PR has merged. Pure; the poller writes the result onto `plans.promotion_state`.
+ *   • no PR yet            → `ready`
+ *   • PR exists, unmerged  → `open`
+ *   • PR merged            → `promoted` */
+export function derivePromotionState(hasPr: boolean, prMerged: boolean): PromotionState {
+  if (prMerged) return "promoted";
+  if (hasPr) return "open";
+  return "ready";
+}
+
+/** The title for an epic's promotion PR: names the integration branch, the target it promotes into,
+ * and the epic's human identity. */
+export function promotionPrTitle(base: string, target: string, epicTitle: string): string {
+  return `Promote ${base} → ${target}: ${epicTitle}`;
+}
+
+/** Render the promotion PR body: a short explanation, the parent epic issue (as `Closes` so the
+ * epic closes when the promotion lands — the epic is only truly delivered once its integration
+ * branch reaches the default branch), and the list of merged slice PRs it carries. `slicePrKeys`
+ * are `owner/repo#N` keys; a `Depends-on:` is deliberately NOT emitted — the slices have already
+ * merged into the integration branch, so the promotion PR has no live dependency. */
+export function promotionPrBody(
+  base: string,
+  target: string,
+  issueRef: string,
+  slicePrKeys: readonly string[],
+): string {
+  const lines = [
+    `Automated promotion of the landed epic integration branch \`${base}\` into \`${target}\`.`,
+    "",
+    `Every slice of this epic has merged into \`${base}\`; this PR delivers the whole epic to ` +
+      `\`${target}\`. It converges and merges through the standard review + merge protocol.`,
+    "",
+    `Closes ${issueRef}`,
+  ];
+  if (slicePrKeys.length > 0) {
+    lines.push("", "Merged slices:");
+    for (const key of slicePrKeys) lines.push(`- ${key}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/app/promotionPoll.test.ts

@@ -0,0 +1,255 @@
+// Integration tests for the epic promotion poller pass (issue #299). `pollPromotion` is the missing
+// counterpart to `ensureBaseBranch`: once an epic has LANDED on its custom `epic/*` integration
+// branch (every slice PR merged → `plans.delivery = landed`), it opens exactly ONE `epic/* →
+// <default>` promotion PR and enrolls it into the convergence + merge loop. These tests exercise the
+// issue's red/green plan against an in-memory data layer + a stubbed GitHub (token) transport + a
+// recording engine: open exactly one PR, never a duplicate on re-run, never for a converging epic,
+// and never for a `main`-based epic.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { resetDefaultBranchCache } from "./github.ts";
+import { pollPromotion } from "./service.ts";
+
+// In-memory record gateway (all/get/find/insert/update/delete), mirroring app/delivery.test.ts but
+// with `delete` (submitPr's `registerDependencies` clears the PR's dep set on submit).
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  const stores: Record<string, any[]> = {};
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    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);
+      },
+      async delete(id: any) {
+        for (let i = rows.length - 1; i >= 0; i--) if (rows[i][pk] === id) rows.splice(i, 1);
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+// A recording engine stub: every `submitPr` starts a convergence instance via `createInstance`.
+function recordingEngine(): { engine: EngineClient; instances: any[] } {
+  const instances: any[] = [];
+  const engine = {
+    async createInstance(req: any) {
+      instances.push(req);
+      return { processInstanceKey: `pi-${instances.length}` };
+    },
+  } as any as EngineClient;
+  return { engine, instances };
+}
+
+// A fake GitHub repo model served over the token transport. Tracks the default branch and the PRs
+// keyed by head branch; records every create so a test can assert exactly-once.
+interface FakeRepo {
+  repo: string;
+  defaultBranch: string;
+  prsByHead: Map<string, { number: number; state: string; baseRef: string }[]>;
+  creates: { head: string; base: string; title: string; number: number }[];
+  nextNumber: number;
+}
+
+function githubFetch(state: FakeRepo) {
+  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;
+    const json = (obj: unknown, status = 200) =>
+      Promise.resolve(new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } }));
+
+    if (method === "GET" && path === `/repos/${state.repo}`) {
+      return json({ default_branch: state.defaultBranch });
+    }
+    if (method === "GET" && path === `/repos/${state.repo}/pulls`) {
+      // listPrsForHead: ?head=owner:branch
+      const head = (u.searchParams.get("head") ?? "").split(":").pop() ?? "";
+      const list = state.prsByHead.get(head) ?? [];
+      return json(
+        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; title?: string };
+      const head = String(body.head ?? "");
+      const number = state.nextNumber++;
+      state.creates.push({ head, base: String(body.base ?? ""), title: String(body.title ?? ""), number });
+      const arr = state.prsByHead.get(head) ?? [];
+      arr.push({ number, state: "open", baseRef: String(body.base ?? "") });
+      state.prsByHead.set(head, arr);
+      return json({ number, html_url: `https://github.com/${state.repo}/pull/${number}` }, 201);
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(state: FakeRepo, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  const prevToken = process.env.GITHUB_TOKEN;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  // Leave GITHUB_TOKEN empty so submitPr's best-effort PR-meta enrichment is skipped (no fetch),
+  // while pollPromotion's own GitHub calls use the explicit "tok" argument.
+  delete process.env.GITHUB_TOKEN;
+  globalThis.fetch = githubFetch(state) as typeof fetch;
+  resetDefaultBranchCache();
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    resetDefaultBranchCache();
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    if (prevToken === undefined) delete process.env.GITHUB_TOKEN;
+    else process.env.GITHUB_TOKEN = prevToken;
+  }
+}
+
+function freshRepo(defaultBranch = "main"): FakeRepo {
+  return { repo: "o/r", defaultBranch, prsByHead: new Map(), creates: [], nextNumber: 500 };
+}
+
+test("pollPromotion: a landed epic on an epic/* base opens exactly one epic/*→default PR", async () => {
+  const { data, stores } = memData();
+  const { engine, instances } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#295", repo: "o/r", title: "Assertion DSL", status: "done", base_branch: "epic/test-dsl", delivery: "landed", promotion_pr: null, promotion_state: null },
+  ];
+  stores.plan_tasks = [
+    { id: 1, plan_key: "o/r#295", pr_key: "o/r#299" },
+    { id: 2, plan_key: "o/r#295", pr_key: "o/r#304" },
+  ];
+  stores.pull_requests = [
+    { pr_key: "o/r#299", status: "merged" },
+    { pr_key: "o/r#304", status: "merged" },
+  ];
+  const state = freshRepo();
+
+  await withGithub(state, () => pollPromotion(data, engine, "tok"));
+
+  assertEquals(state.creates.length, 1);
+  assertEquals(state.creates[0].head, "epic/test-dsl");
+  assertEquals(state.creates[0].base, "main");
+  assertEquals(stores.plans[0].promotion_pr, "o/r#500");
+  assertEquals(stores.plans[0].promotion_state, "open");
+  // The promotion PR was enrolled into the convergence loop (a real PR, not an auto-merge).
+  assertEquals(instances.length, 1);
+  assertEquals(instances[0].variables.prKey, "o/r#500");
+  const prRow = stores.pull_requests.find((p) => p.pr_key === "o/r#500");
+  assert(prRow, "promotion PR row registered by submitPr");
+});
+
+test("pollPromotion: re-running is idempotent — no duplicate promotion PR", async () => {
+  const { data, stores } = memData();
+  const { engine } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#295", repo: "o/r", title: "Assertion DSL", status: "done", base_branch: "epic/test-dsl", delivery: "landed", promotion_pr: null, promotion_state: null },
+  ];
+  stores.plan_tasks = [{ id: 1, plan_key: "o/r#295", pr_key: "o/r#299" }];
+  stores.pull_requests = [{ pr_key: "o/r#299", status: "merged" }];
+  const state = freshRepo();
+
+  await withGithub(state, async () => {
+    await pollPromotion(data, engine, "tok");
+    await pollPromotion(data, engine, "tok");
+    await pollPromotion(data, engine, "tok");
+  });
+
+  assertEquals(state.creates.length, 1, "exactly one promotion PR across three passes");
+  assertEquals(stores.plans[0].promotion_pr, "o/r#500");
+});
+
+test("pollPromotion: a still-converging epic opens no promotion PR", async () => {
+  const { data, stores } = memData();
+  const { engine } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#296", repo: "o/r", title: "WIP", status: "done", base_branch: "epic/wip", delivery: "converging", promotion_pr: null, promotion_state: null },
+  ];
+  stores.plan_tasks = [{ id: 1, plan_key: "o/r#296", pr_key: "o/r#310" }];
+  stores.pull_requests = [{ pr_key: "o/r#310", status: "converging" }];
+  const state = freshRepo();
+
+  await withGithub(state, () => pollPromotion(data, engine, "tok"));
+
+  assertEquals(state.creates.length, 0);
+  assertEquals(stores.plans[0].promotion_pr, null);
+  assertEquals(stores.plans[0].promotion_state, null);
+});
+
+test("pollPromotion: a main-based epic has nothing to promote", async () => {
+  const { data, stores } = memData();
+  const { engine } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#297", repo: "o/r", title: "Direct", status: "done", base_branch: "main", delivery: "landed", promotion_pr: null, promotion_state: null },
+  ];
+  stores.plan_tasks = [{ id: 1, plan_key: "o/r#297", pr_key: "o/r#320" }];
+  stores.pull_requests = [{ pr_key: "o/r#320", status: "merged" }];
+  const state = freshRepo();
+
+  await withGithub(state, () => pollPromotion(data, engine, "tok"));
+
+  assertEquals(state.creates.length, 0);
+  assertEquals(stores.plans[0].promotion_pr, null);
+  assertEquals(stores.plans[0].promotion_state, null);
+});
+
+test("pollPromotion: reuses an existing PR from the integration branch (crash-recovery idempotency)", async () => {
+  const { data, stores } = memData();
+  const { engine } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#295", repo: "o/r", title: "Assertion DSL", status: "done", base_branch: "epic/test-dsl", delivery: "landed", promotion_pr: null, promotion_state: null },
+  ];
+  stores.plan_tasks = [{ id: 1, plan_key: "o/r#295", pr_key: "o/r#299" }];
+  stores.pull_requests = [{ pr_key: "o/r#299", status: "merged" }];
+  const state = freshRepo();
+  // A prior pass created the PR on GitHub but crashed before persisting `promotion_pr`.
+  state.prsByHead.set("epic/test-dsl", [{ number: 777, state: "open", baseRef: "main" }]);
+
+  await withGithub(state, () => pollPromotion(data, engine, "tok"));
+
+  assertEquals(state.creates.length, 0, "existing PR reused, not duplicated");
+  assertEquals(stores.plans[0].promotion_pr, "o/r#777");
+  assertEquals(stores.plans[0].promotion_state, "open");
+});
+
+test("pollPromotion: projects `promoted` once the promotion PR merges", async () => {
+  const { data, stores } = memData();
+  const { engine } = recordingEngine();
+  stores.plans = [
+    { plan_key: "o/r#295", repo: "o/r", title: "Assertion DSL", status: "done", base_branch: "epic/test-dsl", delivery: "landed", promotion_pr: "o/r#500", promotion_state: "open" },
+  ];
+  stores.plan_tasks = [{ id: 1, plan_key: "o/r#295", pr_key: "o/r#299" }];
+  stores.pull_requests = [
+    { pr_key: "o/r#299", status: "merged" },
+    { pr_key: "o/r#500", status: "merged" },
+  ];
+  const state = freshRepo();
+
+  await withGithub(state, () => pollPromotion(data, engine, "tok"));
+
+  assertEquals(state.creates.length, 0);
+  assertEquals(stores.plans[0].promotion_state, "promoted");
+});

package/app/service.ts

@@ -17,6 +17,8 @@ import {
   classifyMergeability,
   coalesceTitle,
   ensureFreshHeadRun,
+  ensurePromotionPr,
+  fetchDefaultBranch,
   fetchPrHead,
   fetchPrMeta,
   fetchPrReviews,
@@ -32,6 +34,7 @@ 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 { derivePromotionState, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
 import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
 import {
@@ -1347,6 +1350,91 @@ export async function pollDelivery(data: DataLayer) {
   }
 }
 
+/** Idempotent promotion pass (issue #299): open — and then track — the `epic/* → <default>`
+ * promotion PR for every epic that has LANDED on a custom integration branch. This is the missing
+ * counterpart to `ensureBaseBranch`: that creates the `epic/*` branch slices merge into; this
+ * delivers the fully-landed branch to the default branch. Runs AFTER `pollDelivery` so it reads the
+ * freshly-projected `delivery = landed` signal.
+ *
+ * Per promotable plan (`isPromotable`: `delivery = landed` AND base is `epic/*`):
+ *   • No promotion PR yet → open ONE `epic/* → <default>` PR (idempotent against a remote head-branch
+ *     lookup, so a crash between GitHub-create and the `promotion_pr` write can't duplicate it),
+ *     record `promotion_pr`, mark `promotion_state = open`, and enroll it into the convergence + merge
+ *     loop via `submitPr` (a real PR that must go green + converge before it merges — never an
+ *     auto-merge). If the PR can't be opened this pass (no default branch resolvable, no transport),
+ *     leave it at `promotion_state = ready` and retry next pass.
+ *   • Promotion PR already recorded → project `promotion_state` from its live status
+ *     (`merged → promoted`, else `open`); if its `pull_requests` row is absent (a prior `submitPr`
+ *     failed / DB desync) re-enroll it (idempotent).
+ *
+ * A `main`-based epic (base is not `epic/*`) is never promotable — its slices already landed on the
+ * default branch, so there is nothing to promote. Best-effort + per-plan isolated. */
+export async function pollPromotion(data: DataLayer, engine: EngineClient, token: string) {
+  // Preload every PR status once per pass (mirrors pollDelivery — avoids an N+1 `prs(data).get`).
+  const statusByPrKey = new Map<string, string>();
+  for (const pr of await prs(data).all()) statusByPrKey.set(pr.pr_key, pr.status);
+  for (const plan of await plans(data).all()) {
+    if (!isPromotable(plan)) continue;
+    const base = plan.base_branch;
+    if (!base) continue; // narrowed by isPromotable, but keep the type-checker honest
+    try {
+      // Already opened → project state from the promotion PR's live status, and re-enroll it if its
+      // convergence row went missing (a prior submit failed, or the app/engine store desynced).
+      if (plan.promotion_pr) {
+        const prStatus = statusByPrKey.get(plan.promotion_pr) ?? null;
+        const nextState = derivePromotionState(true, prStatus === "merged");
+        if (plan.promotion_state !== nextState) {
+          await plans(data).update(plan.plan_key, { promotion_state: nextState, updated_at: now() });
+        }
+        if (prStatus === null) {
+          const parsed = parsePr(plan.promotion_pr);
+          if (parsed) await submitPr(data, engine, parsed);
+        }
+        continue;
+      }
+      // Not opened yet: this epic is ready to promote. Resolve the target (default) branch; without
+      // it we can't open the PR this pass, so surface `ready` and retry.
+      const target = await fetchDefaultBranch(plan.repo, token);
+      if (!target || target === base) {
+        // `target === base` is a defensive guard (an `epic/*` base can't be the default), but never
+        // open a branch-into-itself PR. Either way, mark ready and retry.
+        if (plan.promotion_state !== "ready") {
+          await plans(data).update(plan.plan_key, { promotion_state: "ready", updated_at: now() });
+        }
+        continue;
+      }
+      const tasks = await planTasks(data).find({ plan_key: plan.plan_key });
+      const slicePrKeys = tasks.map((t) => t.pr_key).filter((k): k is string => !!k);
+      const epicTitle = coalesceTitle(plan.title, plan.plan_key);
+      const title = promotionPrTitle(base, target, epicTitle);
+      const body = promotionPrBody(base, target, plan.plan_key, slicePrKeys);
+      const result = await ensurePromotionPr(plan.repo, base, target, title, body, token);
+      if (!result) {
+        // No transport this pass — surface ready-to-promote and retry.
+        if (plan.promotion_state !== "ready") {
+          await plans(data).update(plan.plan_key, { promotion_state: "ready", updated_at: now() });
+        }
+        continue;
+      }
+      const promotionPrKey = `${plan.repo}#${result.number}`;
+      // Persist the idempotency key + state BEFORE enrolling, so a submit failure can never lead a
+      // later pass to open a second PR (it will see `promotion_pr` set and only re-enroll).
+      await plans(data).update(plan.plan_key, {
+        promotion_pr: promotionPrKey,
+        promotion_state: "open",
+        updated_at: now(),
+      });
+      const parsed = parsePr(promotionPrKey);
+      if (parsed) await submitPr(data, engine, parsed);
+      console.log(
+        `[poller] promotion PR ${result.created ? "opened" : "reused"} ${promotionPrKey} (${base} -> ${target})`,
+      );
+    } catch (err) {
+      console.error(`[poller] promotion ${plan.plan_key}: ${err}`);
+    }
+  }
+}
+
 /** 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
@@ -1699,6 +1787,7 @@ export async function pollOnce(
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
   await pollDelivery(data);
+  await pollPromotion(data, engine, token);
   await pollFeatureDelivery(data);
   await pollLineage(data);
   await pollFeatureEscalations(data, engine);

package/db/migrations/042_plan_promotion.sql

@@ -0,0 +1,31 @@
+-- 042_plan_promotion.sql — issue #299: automate the epic integration-branch → default-branch
+-- promotion PR once an epic LANDS on its custom `epic/*` integration branch.
+--
+-- Today an epic that targets a custom `epic/*` integration branch fans slices out that PR *into*
+-- that branch; once every slice merges (`plans.delivery = landed`, projected by 029), the epic is
+-- delivered on the integration branch but NOTHING opens the final `epic/* → <default>` promotion
+-- PR — the operator has to notice, find the branch, and raise it by hand. This migration adds the
+-- durable read/idempotency surface the poller's new `pollPromotion` pass needs to open (and then
+-- track) exactly one promotion PR per landed epic, reusing the same convergence + merge protocol as
+-- every other PR:
+--
+--   • promotion_pr    — the `owner/repo#N` key of the promotion PR the poller opened for this epic,
+--                       or NULL until one exists. This is the PRIMARY idempotency key: a pass that
+--                       finds it set never opens a second PR (the poller also reconciles against a
+--                       remote head-branch lookup, so a crash between GitHub-create and this write
+--                       can never duplicate the PR either).
+--   • promotion_state — the epic-card progression for the landed→delivered arc (issue #298's
+--                       "keep landed epics visible until acknowledged"): one of
+--                         'ready'    — landed on an `epic/*` base, promotion PR not yet opened.
+--                         'open'     — the promotion PR is open and converging toward merge.
+--                         'promoted' — the promotion PR merged; the epic is delivered on the
+--                                      default branch.
+--                       NULL until the epic first becomes promotable (grandfathers pre-#299 rows
+--                       and every `main`-based epic, which has nothing to promote).
+--
+-- Additive/derived only: no change to the plan lifecycle (`status`) — both columns are projected
+-- idempotently by the poller, mirroring the `delivery` / `delivery_label` read-model columns (029).
+-- 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 promotion_pr TEXT;
+ALTER TABLE plans ADD COLUMN promotion_state TEXT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.88.1",
+  "version": "0.89.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/epic-detail.page.json

@@ -61,6 +61,7 @@
           { "field": "epic_phase", "header": "Phase" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
+          { "field": "promotion_state", "header": "Promotion" },
           { "field": "wave_label", "header": "Wave" },
           { "field": "task_count", "header": "Tasks" },
           { "field": "updated_at", "header": "Updated", "width": "9rem" }
@@ -72,6 +73,7 @@
             { "field": "issue_number", "label": "Issue number" },
             { "field": "base_branch", "label": "Base branch (blank = repo default)" },
             { "field": "delivery_label", "label": "Delivery rollup (slices merged / converging)" },
+            { "field": "promotion_pr", "label": "Promotion PR (epic/* → default branch)" },
             { "field": "outcome", "label": "Outcome" }
           ]
         }

package/pages/epic.page.json

@@ -79,6 +79,7 @@
           { "field": "epic_phase", "header": "Phase" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
+          { "field": "promotion_state", "header": "Promotion" },
           { "field": "base_branch", "header": "Base branch" },
           { "field": "wave_label", "header": "Wave" },
           { "field": "task_count", "header": "Tasks" },