gh-stack 0.11.0 → 0.14.1

package/README.md

@@ -85,8 +85,9 @@ create <branch-name> [--description <desc>]
 
 submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file <f>] [--dry-run]
     Push all downstack branches to GitHub, create PRs for branches
-    that don't have them, and update all PR descriptions with stack
-    visualization. Idempotent — safe to run repeatedly.
+    that don't have them, number each PR title with its stack position
+    `(N/M)`, and update all PR descriptions with stack visualization.
+    Idempotent — safe to run repeatedly.
 
     Self-healing: if the current branch isn't tracked in a stack yet,
     submit auto-detects the chain from trunk → current, registers (or
@@ -95,9 +96,14 @@ submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file
     from the top of a bare chain of local branches converges to the
     expected end state (stack registered, branches pushed, PRs created).
 
-    --title/-t and --body/-b provide PR details directly (skips prompts).
-    --body-file reads body from a file. In --yes mode without --title,
-    auto-generates PR titles from branch names.
+    --title/-t and --body/-b set the title/body for the branch you're on.
+    They work whether the PR is new OR already exists — on an existing PR
+    they update it in place: the title keeps its (N/M) stack position and
+    the body is replaced with the "📚 Stacked on" block re-merged in. Use
+    this instead of `gh pr edit` (which would wipe the stack viz block) to
+    let an agent or script regenerate a PR's title/description safely.
+    --body-file reads the body from a file. In --yes mode without --title,
+    titles are auto-generated from branch names.
 ```
 
 ### Stack Navigation
@@ -148,20 +154,41 @@ sync [--dry-run]
     Fetch main, rebase the base branch onto main, then restack all
     children. Snapshots every branch's pre-sync tip so children can be
     correctly rebased even though their parent's history was rewritten.
+    If the bottom PR(s) already merged on main outside gh-stack (e.g.
+    the GitHub web UI), sync detects this and advances the stack past
+    them — re-rooting the survivor onto main with `--onto` so only its
+    own commits replay — instead of replaying the now-squashed commits
+    and conflicting.
 
 merge [--dry-run] [-d|--delete-branch] [--collapse]
-    Squash-merge the stack top-down via GitHub (PR3 → PR2 → PR1),
-    then enables auto-merge for the base PR into main. All merges
-    happen on GitHub so PRs show as "Merged", Linear tickets close
-    automatically, and GitHub Actions fire normally. Skips already-
+merge --approved [--dry-run] [-d|--delete-branch]
+    Default (top-down collapse): squash-merge the stack top-down via
+    GitHub (PR3 → PR2 → PR1), then enables auto-merge for the base PR
+    into main. The whole stack lands on main as a single squash commit.
+    All merges happen on GitHub so PRs show as "Merged", Linear tickets
+    close automatically, and GitHub Actions fire normally. Skips already-
     merged PRs (safe to re-run). Waits for GitHub between merges, and
     self-heals its spurious "Head branch is out of date" (a stale PR
-    head pointer after a child squash) by re-syncing and retrying.
+    head pointer after a child squash) by re-syncing and retrying. Before
+    handing the base PR to auto-merge it confirms the PR is mergeable: a
+    real conflict with main stops the merge (the stack is left intact —
+    resolve with `gh-stack sync`, then re-run), while merely waiting on
+    pending checks is fine (auto-merge gates on them).
     --collapse  Stop after collapsing the stack into the base PR;
                 leaves the base PR open against main so you can
                 review the cumulative diff on GitHub. Re-run
                 `gh-stack merge` (without --collapse) to finish.
 
+    --approved (bottom-up, merge what's ready): merge approved PRs from
+    the BOTTOM up, each as its own squash commit on main, and leave the
+    unreviewed tail as a clean stack re-rooted on main. Stops at the
+    first PR that isn't approved. For each approved bottom PR it squash-
+    merges to main, re-roots the next branch onto main (replaying only
+    its own commits), pushes it, and repoints its PR base to main. A PR
+    already merged outside gh-stack is detected and advanced past, not
+    re-merged. For the "merge PRs as they get reviewed, keep stacking
+    the rest" workflow.
+
 split [<branch>] [--name <name>]
     Cut a stack into two at <branch>. The cut branch and every branch
     above it move into a NEW stack whose base is the cut branch's parent
@@ -279,19 +306,36 @@ gh-stack solves this by snapshotting every branch's tip **before** any destructi
 
 Snapshots also power `gh-stack undo`, so the same data structure does double duty.
 
+### Stack Position in PR Titles
+
+`submit` keeps each PR's **title** suffixed with its stack position as `(N/M)`,
+so you can see the order from a bare "needs your review" list — where only
+titles show, not descriptions — and review bottom-up:
+
+```
+feat(paid-subs): tiers overview list [BEE-20531] (1/4)
+feat(paid-subs): tier detail page [BEE-20550] (2/4)
+feat(paid-subs): tier create wizard [BEE-20579] (3/4)
+feat(paid-subs): advanced settings step [BEE-20587] (4/4)
+```
+
+Parentheses (not brackets) avoid colliding with `[BEE-1234]` ticket tags. It's
+self-healing and idempotent: re-running `submit` after adding or reordering a
+branch renumbers the whole stack, and a no-op re-submit changes nothing. The
+position is the only managed part of the title — your text (and ticket tags)
+are preserved. Single-PR stacks get no suffix.
+
 ### Stack Visualization
 
-`submit` automatically adds a stack section to all PR descriptions, with each
-branch numbered by its position in the stack (handy for spotting "which one is
-PR 6 of 12"):
+`submit` also adds a stack section to every PR description:
 
 ```
 ### 📚 Stacked on
 ⚫ main
 ┃
-┣━ 1. #123 Backend models
+┣━ #123 feat: backend models (1/2)
 ┃
-┗━ 2. #124 Frontend UI 👈
+┗━ #124 feat: frontend UI (2/2) 👈
 ```
 
 The block is rendered entirely from local metadata plus one repo-identity
@@ -395,9 +439,12 @@ gh-stack top         # jump to tip
 # Check status
 gh-stack status
 
-# When PRs are approved, merge the stack
+# When the whole stack is approved, merge it down as one squash commit
 gh-stack merge       # squash-merges down, pushes, enables auto-merge
 
+# Or: merge PRs as they get approved, bottom-up, keep stacking the rest
+gh-stack merge --approved   # merges approved bottom PRs, re-roots the tail on main
+
 # Or: collapse first to review the cumulative diff before shipping
 gh-stack merge --collapse   # squash-merges PRn..PR2 into PR1, stops there
 # ...review base PR on GitHub...

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gh-stack",
-  "version": "0.11.0",
+  "version": "0.14.1",
   "description": "Stacked PR manager for squash-merge workflows",
   "author": "Kiliman <kiliman@gmail.com>",
   "license": "MIT",

package/src/commands/merge.ts

@@ -6,13 +6,15 @@ import * as git from "../lib/git.ts";
 import {
   findStackForBranch,
   getOrderedBranches,
+  removeBranchFromStack,
   stackBase,
   writeMetadata,
 } from "../lib/metadata.ts";
-import { ensureMetadata, ensureValidStack } from "../lib/safety.ts";
+import { ensureMetadata, ensureCleanWorkingTree, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
-import { getBranchRefSha, getPrMergeState, resyncPrHead } from "../lib/github.ts";
+import { getBranchRefSha, getPrInfo, getPrMergeState, resyncPrHead } from "../lib/github.ts";
 import { confirmAction } from "../lib/ui.ts";
+import { planMerges, advanceNewBottom, type BranchReview } from "../lib/advance.ts";
 
 const MAX_RETRIES = 12;
 const RETRY_DELAY_MS = 5000;
@@ -145,9 +147,44 @@ async function ensureFreshHead(
   return true;
 }
 
+/** A PR's merge readiness, distilled from GitHub's `state` / `mergeable` /
+ *  `mergeStateStatus` triple into the decision the merge flow actually needs. */
+export type MergeVerdict = "merged" | "closed" | "conflict" | "ready" | "blocked" | "pending";
+
+/**
+ * Classify a PR's merge state. The crucial distinction is **conflict vs.
+ * blocked**: a `CONFLICTING`/`DIRTY` PR can never merge until someone resolves
+ * the conflict (so auto-merge would silently never fire — see the base-PR path),
+ * whereas a `BLOCKED` PR (required check still running/failing) is merely not
+ * ready *yet* and is a legitimate target for `--auto`.
+ *
+ *   merged   — already merged
+ *   closed   — closed without merging
+ *   conflict — mergeable=CONFLICTING or mergeStateStatus=DIRTY (won't self-resolve)
+ *   pending  — GitHub still computing mergeability (UNKNOWN)
+ *   blocked  — mergeable but gated on required checks/reviews
+ *   ready    — mergeable and clean (CLEAN/HAS_HOOKS/UNSTABLE/BEHIND)
+ */
+export function classifyMergeState(state: {
+  state: string;
+  mergeable: string;
+  mergeStateStatus: string;
+}): MergeVerdict {
+  if (state.state === "MERGED") return "merged";
+  if (state.state === "CLOSED") return "closed";
+  if (state.mergeable === "CONFLICTING" || state.mergeStateStatus === "DIRTY") return "conflict";
+  // Mergeability not computed yet — caller should keep polling.
+  if (state.mergeable === "UNKNOWN" || state.mergeStateStatus === "UNKNOWN") return "pending";
+  if (state.mergeStateStatus === "BLOCKED") return "blocked";
+  return "ready";
+}
+
 /**
- * Wait for a PR to become mergeable after a previous merge lands.
- * GitHub needs time to process the new commit on the target branch.
+ * Wait for a PR to become cleanly mergeable after a previous merge lands.
+ * GitHub needs time to process the new commit on the target branch. Returns
+ * false fast on a definitive conflict (waiting can't help) and on a closed PR;
+ * keeps polling only while GitHub is still computing or the PR is blocked on
+ * pending checks.
  */
 async function waitForMergeable(
   prNumber: number,
@@ -157,13 +194,9 @@ async function waitForMergeable(
     const state = await getPrMergeState(prNumber);
     if (!state) return false;
 
-    if (state.state === "MERGED") return true; // Already merged
-    if (state.state === "CLOSED") return false;
-
-    // "CLEAN", "HAS_HOOKS", "UNSTABLE" are all mergeable states
-    if (state.mergeable === "MERGEABLE" && state.mergeStateStatus !== "BLOCKED") {
-      return true;
-    }
+    const verdict = classifyMergeState(state);
+    if (verdict === "merged" || verdict === "ready") return true;
+    if (verdict === "conflict" || verdict === "closed") return false; // waiting won't help
 
     spinner.message(`Waiting for PR #${prNumber} to be ready... (${attempt}/${MAX_RETRIES})`);
     await Bun.sleep(RETRY_DELAY_MS);
@@ -171,10 +204,36 @@ async function waitForMergeable(
   return false;
 }
 
+/**
+ * Poll until GitHub has *computed* a PR's mergeability, then return the verdict.
+ * Unlike `waitForMergeable` this does NOT keep waiting on a `blocked` PR —
+ * blocked-on-pending-checks is a fine target for auto-merge, so the base-PR
+ * path wants to know that and proceed rather than burn the poll budget. Only a
+ * still-`pending` (UNKNOWN) state is polled; returns `pending` if it never
+ * settles within the budget.
+ */
+async function pollMergeVerdict(
+  prNumber: number,
+  spinner: ReturnType<typeof p.spinner>,
+): Promise<MergeVerdict> {
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    const state = await getPrMergeState(prNumber);
+    if (!state) return "pending";
+
+    const verdict = classifyMergeState(state);
+    if (verdict !== "pending") return verdict;
+
+    spinner.message(`Checking PR #${prNumber} mergeability... (${attempt}/${MAX_RETRIES})`);
+    await Bun.sleep(RETRY_DELAY_MS);
+  }
+  return "pending";
+}
+
 export default async function merge(args: string[]): Promise<void> {
   const dryRun = args.includes("--dry-run");
   const deleteFlag = args.includes("--delete-branch") || args.includes("-d");
   const collapse = args.includes("--collapse") || args.includes("--stop-at-base");
+  const approved = args.includes("--approved");
 
   if (args.includes("--help")) {
     console.log(`
@@ -182,9 +241,23 @@ gh-stack merge — Squash-merge stack via GitHub
 
 USAGE
   gh-stack merge [--dry-run] [-d|--delete-branch] [--collapse]
+  gh-stack merge --approved [--dry-run] [-d|--delete-branch]
+
+DEFAULT (top-down collapse)
+  Squash-merges the stack from top to bottom via GitHub:
+    PR3 → squash into PR2, PR2 → squash into PR1, PR1 → auto-merge into main.
+  The whole stack lands on main as a single squash commit.
+
+--approved (bottom-up, merge what's ready)
+  Merges approved PRs from the BOTTOM of the stack up, each as its own
+  squash commit on main, and leaves the unreviewed tail as a clean stack
+  re-rooted on main. Stops at the first PR that isn't approved. For the
+  "merge PRs as they get reviewed, keep stacking the rest" workflow.
 
-Squash-merges the stack from top to bottom via GitHub:
-  PR3 → squash into PR2, PR2 → squash into PR1, PR1 → auto-merge into main.
+  For each approved bottom PR it: squash-merges to main, re-roots the next
+  branch onto main (replaying only its own commits — no replay of the
+  squashed work), pushes it, and repoints its PR base to main. A PR already
+  merged outside gh-stack is detected and advanced past, not re-merged.
 
 All merges happen on GitHub, so PRs show as "Merged", Linear tickets
 close automatically, and all GitHub Actions/webhooks fire normally.
@@ -195,8 +268,11 @@ spurious "Head branch is out of date" (a stale PR head pointer after a
 child squash) by re-syncing the branch and retrying — only a genuine
 conflict or failing required check is reported as a hard failure.
 
+A snapshot is taken first; ${pc.green("gh-stack undo")} restores the prior state.
+
 OPTIONS
   -d, --delete-branch  Delete remote branches after merging
+      --approved       Merge approved PRs bottom-up; leave the rest as PRs
       --dry-run        Show what would happen without doing anything
       --collapse       Stop after collapsing the stack into the base PR;
                        do NOT merge base PR into main. Lets you review the
@@ -207,6 +283,11 @@ OPTIONS
     return;
   }
 
+  if (approved) {
+    await mergeApproved(deleteFlag, dryRun);
+    return;
+  }
+
   const meta = await ensureMetadata();
   const currentBranch = await git.currentBranch();
   const stackName = findStackForBranch(meta, currentBranch);
@@ -460,15 +541,50 @@ OPTIONS
 
   const autoSpinner = p.spinner();
 
-  // Wait for base PR to be ready (may need time after last intermediate merge).
-  // The last intermediate merge moved this branch, so — like the cascade — the
-  // base PR's head can be stuck behind the live ref; heal it before enabling
-  // auto-merge, then once more if GitHub still rejects the first attempt.
-  autoSpinner.start(`Waiting for PR #${basePr} to be ready...`);
+  // Confirm the base PR can ACTUALLY merge before handing off to auto-merge.
+  // A conflicting PR silently accepts `--auto` but never fires — so enabling
+  // auto-merge and archiving on a conflict reports a false success and leaves
+  // an un-mergeable PR stranded. Heal a possibly-stale PR head first (the last
+  // intermediate merge moved this branch), then poll until GitHub finishes
+  // computing mergeability and classify the result.
+  autoSpinner.start(`Checking PR #${basePr} is mergeable...`);
   await ensureFreshHead(basePr!, baseBranch, autoSpinner);
-  await waitForMergeable(basePr!, autoSpinner);
-
-  autoSpinner.message(`Enabling auto-merge for PR #${basePr}...`);
+  const verdict = await pollMergeVerdict(basePr!, autoSpinner);
+
+  // Conflict / closed / never-settled → STOP. Do not enable auto-merge, do not
+  // archive: leave the stack intact so a re-run finishes it after resolution.
+  if (verdict === "conflict" || verdict === "closed" || verdict === "pending") {
+    autoSpinner.stop(
+      pc.red(
+        verdict === "conflict"
+          ? `PR #${basePr} has merge conflicts with main`
+          : verdict === "closed"
+            ? `PR #${basePr} is closed — not merging`
+            : `Could not confirm PR #${basePr} is mergeable`,
+      ),
+    );
+    console.log();
+    if (verdict === "conflict") {
+      p.log.error(
+        `${pc.yellow(baseBranch)} conflicts with ${pc.green("main")} — auto-merge would never fire.`,
+      );
+      p.log.info("Resolve the conflict, then finish the merge:");
+      console.log(
+        `    ${pc.green("gh-stack sync")}     ${pc.dim("# rebase the base onto main & resolve conflicts")}`,
+      );
+      console.log(
+        `    ${pc.green("gh-stack merge")}    ${pc.dim("# finishes base PR → main + archives")}`,
+      );
+    } else if (verdict === "pending") {
+      p.log.warn(
+        "GitHub didn't settle the merge state in time (transient lag, not necessarily a conflict).",
+      );
+      p.log.info(`Verify the PR on GitHub, then re-run ${pc.green("gh-stack merge")} to finish.`);
+    }
+    console.log();
+    p.log.info(pc.dim("Stack NOT archived — your stack metadata is intact. Re-run to finish."));
+    process.exit(2);
+  }
 
   const enableAutoMerge = async (): Promise<{ ok: boolean; stderr: string }> => {
     const ghArgs = ["pr", "merge", String(basePr), "--squash", "--auto"];
@@ -479,20 +595,29 @@ OPTIONS
     return { ok: exitCode === 0, stderr: stderr.trim() };
   };
 
-  let auto = await enableAutoMerge();
-  if (!auto.ok && isTransientMergeError(auto.stderr)) {
-    // Same stale-head artifact as the cascade — re-sync and try once more.
-    await ensureFreshHead(basePr!, baseBranch, autoSpinner);
-    await waitForMergeable(basePr!, autoSpinner);
-    auto = await enableAutoMerge();
-  }
-
-  if (auto.ok) {
-    autoSpinner.stop(`Auto-merge enabled for PR #${basePr} — will merge into main when CI passes`);
+  // verdict is "merged", "ready", or "blocked" (pending checks). All are safe to
+  // archive: the PR is either already merged or will merge once checks pass.
+  if (verdict === "merged") {
+    autoSpinner.stop(`PR #${basePr} already merged into main`);
   } else {
-    autoSpinner.stop(pc.yellow(`Could not enable auto-merge for PR #${basePr}`));
-    if (auto.stderr) p.log.error(auto.stderr);
-    p.log.info(`Enable manually: ${pc.dim(`gh pr merge ${basePr} --squash --auto`)}`);
+    autoSpinner.message(`Enabling auto-merge for PR #${basePr}...`);
+    let auto = await enableAutoMerge();
+    if (!auto.ok && isTransientMergeError(auto.stderr)) {
+      // Same stale-head artifact as the cascade — re-sync and try once more.
+      await ensureFreshHead(basePr!, baseBranch, autoSpinner);
+      await pollMergeVerdict(basePr!, autoSpinner);
+      auto = await enableAutoMerge();
+    }
+
+    if (auto.ok) {
+      autoSpinner.stop(
+        `Auto-merge enabled for PR #${basePr} — will merge into main when CI passes`,
+      );
+    } else {
+      autoSpinner.stop(pc.yellow(`Could not enable auto-merge for PR #${basePr}`));
+      if (auto.stderr) p.log.error(auto.stderr);
+      p.log.info(`Enable manually: ${pc.dim(`gh pr merge ${basePr} --squash --auto`)}`);
+    }
   }
 
   // Update local main and clean up
@@ -522,3 +647,262 @@ OPTIONS
 
   p.outro(pc.green("Stack merge complete! Stack archived."));
 }
+
+/**
+ * `gh-stack merge --approved` — merge approved PRs from the bottom of the stack
+ * up, each as its own squash commit on main, advancing the rest of the stack
+ * onto main as it goes. Stops at the first PR that isn't approved, leaving the
+ * unreviewed tail as a clean stack re-rooted on main.
+ *
+ * The cascade is interleaved by necessity: each PR must be rebased off the
+ * just-merged commits and pushed before the next one can merge cleanly, so we
+ * merge → advance → merge → advance one branch at a time (see ./lib/advance.ts
+ * for the re-root mechanics and fork-point resolution).
+ */
+async function mergeApproved(deleteFlag: boolean, dryRun: boolean): Promise<void> {
+  // We rebase the surviving branches, so the same pre-flight guards as restack.
+  if (await git.isRebaseInProgress()) {
+    p.cancel(
+      `Git rebase already in progress.\n\n  Finish or abort it first:\n    ${pc.green("git rebase --continue")}\n    ${pc.red("git rebase --abort")}`,
+    );
+    process.exit(1);
+  }
+  if (!dryRun) await ensureCleanWorkingTree();
+
+  const meta = await ensureMetadata();
+  const currentBranch = await git.currentBranch();
+  const stackName = findStackForBranch(meta, currentBranch);
+  if (!stackName) {
+    p.cancel(`Branch ${pc.blue(currentBranch)} not found in any stack`);
+    process.exit(1);
+  }
+
+  const stack = meta.stacks[stackName]!;
+  await ensureValidStack(meta, stackName);
+  const ordered = getOrderedBranches(stack);
+  if (ordered.length === 0) {
+    p.cancel("No branches in this stack");
+    process.exit(1);
+  }
+
+  // Like top-down merge: a split stack rooted off another stack can't drain to
+  // main until it's re-rooted. Require a trunk base.
+  const base = stackBase(stack);
+  if (base !== "main" && base !== "master") {
+    p.cancel(
+      `${pc.yellow(stackName)} is based on ${pc.yellow(base)}, not main — can't merge yet.\n\n` +
+        `  Merge (or finish) the parent stack first, then re-root onto main:\n` +
+        `    ${pc.green("gh-stack restack --onto main")}`,
+    );
+    process.exit(1);
+  }
+  const trunk = base;
+  const targetRef = `origin/${trunk}`;
+
+  p.intro(pc.cyan("Merge Approved (bottom-up, via GitHub)"));
+  p.log.info(`Stack: ${pc.yellow(stackName)}`);
+
+  // Gather each branch's PR review state, bottom-up.
+  const reviewSpinner = p.spinner();
+  reviewSpinner.start("Checking PR review status...");
+  const reviews: BranchReview[] = [];
+  for (const branch of ordered) {
+    const pr = stack.branches[branch]?.pr ?? null;
+    let prState: string | null = null;
+    let reviewDecision: string | null = null;
+    if (pr != null) {
+      const info = await getPrInfo(pr);
+      prState = info?.state ?? null;
+      reviewDecision = info?.reviewDecision ?? null;
+    }
+    reviews.push({ branch, pr, prState, reviewDecision });
+  }
+  reviewSpinner.stop("Review status checked");
+
+  const plan = planMerges(reviews, { approveAndMerge: true });
+
+  // Show the plan.
+  console.log();
+  console.log(`  ${pc.bold("Plan:")}`);
+  for (const step of plan.steps) {
+    const label =
+      step.action === "advance-only"
+        ? pc.dim("already merged — advance past")
+        : `${pc.green("squash-merge")} → ${pc.green(trunk)}`;
+    console.log(`    ${pc.yellow(step.branch)}${step.pr ? ` (#${step.pr})` : ""} → ${label}`);
+  }
+  if (plan.stop) {
+    console.log(
+      `    ${pc.dim("⏹")} stop at ${pc.yellow(plan.stop.branch)} ${pc.dim(`(${plan.stop.reason}) — left as a stack on ${trunk}`)}`,
+    );
+  }
+  console.log();
+
+  const mergeSteps = plan.steps.filter((s) => s.action === "merge");
+  if (mergeSteps.length === 0 && !plan.steps.some((s) => s.action === "advance-only")) {
+    p.outro(
+      plan.stop
+        ? pc.yellow(`Nothing approved to merge — bottom PR is ${plan.stop.reason}.`)
+        : pc.yellow("Nothing to merge."),
+    );
+    return;
+  }
+
+  if (dryRun) {
+    p.outro(pc.yellow("[DRY RUN] No changes made"));
+    return;
+  }
+
+  const confirmed = await confirmAction(
+    `Merge ${mergeSteps.length} approved PR(s) bottom-up into ${trunk} and re-root the rest?`,
+  );
+  if (!confirmed) {
+    p.cancel("Cancelled");
+    process.exit(0);
+  }
+
+  // Snapshot first — this records every branch's pre-merge tip, which both the
+  // fork-point resolver and `gh-stack undo` rely on.
+  await takeSnapshot(meta, stackName, "merge-approved");
+  // Keep a copy of the original topology to archive if the stack fully drains.
+  const originalStack = structuredClone(stack);
+
+  await $`git fetch origin ${trunk}`.quiet();
+
+  for (let i = 0; i < plan.steps.length; i++) {
+    const step = plan.steps[i]!;
+    const mergedBranch = step.branch;
+    const child = ordered[i + 1] ?? null;
+    const childPr = child ? (stack.branches[child]?.pr ?? null) : null;
+
+    console.log();
+    console.log(pc.cyan("━".repeat(40)));
+    console.log(
+      `${pc.blue(step.action === "merge" ? "Merge:" : "Advance:")} ${pc.yellow(mergedBranch)}${step.pr ? ` (#${step.pr})` : ""} → ${pc.green(trunk)}`,
+    );
+    console.log(pc.cyan("━".repeat(40)));
+
+    if (step.action === "merge") {
+      const prNum = step.pr!;
+      // Never stand on the branch we're about to merge (especially with
+      // --delete-branch, which removes the local branch too).
+      if ((await git.currentBranch().catch(() => "")) === mergedBranch) {
+        await git.checkout(trunk).catch(() => {});
+      }
+
+      const s = p.spinner();
+      s.start(`Checking PR #${prNum} is ready to merge...`);
+      await ensureFreshHead(prNum, mergedBranch, s);
+      const ready = await waitForMergeable(prNum, s);
+      if (!ready) {
+        s.stop(pc.red(`PR #${prNum} is not mergeable`));
+        p.log.info("Check the PR on GitHub for merge conflicts or required checks.");
+        p.log.info("Re-run with --approved to continue from where you left off.");
+        process.exit(2);
+      }
+
+      s.message(`Squash-merging PR #${prNum} into ${trunk}...`);
+      const result = await squashMergeWithRetry(prNum, mergedBranch, deleteFlag, s);
+      if (result.ok) {
+        s.stop(`Merged PR #${prNum} into ${pc.green(trunk)}`);
+      } else {
+        s.stop(pc.red(`Failed to merge PR #${prNum}`));
+        p.log.error(result.stderr);
+        p.log.info(
+          result.genuine
+            ? "Real conflict or failing required check — resolve it on GitHub."
+            : "GitHub's mergeability recompute didn't settle (transient lag).",
+        );
+        p.log.info("Re-run with --approved to continue from where you left off.");
+        process.exit(2);
+      }
+    } else {
+      p.log.info(`PR #${step.pr} already merged — advancing the stack past it.`);
+    }
+
+    if (child) {
+      const res = await advanceNewBottom({
+        meta,
+        stackName,
+        mergedBranch,
+        child,
+        childPr,
+        targetRef,
+        recordedBase: trunk,
+      });
+      if (!res.ok) {
+        console.log();
+        if (res.reason === "conflict") {
+          p.log.error(`Rebase conflict re-rooting ${pc.yellow(child)} onto ${trunk}.`);
+          console.log(`  Resolve the conflict, then:`);
+          console.log(`    ${pc.green("git rebase --continue")}`);
+          console.log(
+            `    ${pc.green("gh-stack restack")}   ${pc.dim("(restacks the rest of the tail)")}`,
+          );
+          console.log();
+          console.log(
+            pc.dim(`  The merged PR(s) below ${child} are done; only the re-root needs finishing.`),
+          );
+        } else {
+          p.log.error(
+            `Could not determine a safe rebase base for ${pc.yellow(child)} (${res.reason}).`,
+          );
+          console.log(
+            `  Re-root it manually:\n    ${pc.green(`git rebase --onto ${targetRef} <merged-tip> ${child}`)}`,
+          );
+        }
+        process.exit(2);
+      }
+    } else {
+      // The merged branch was the top — nothing rides above it. Just drop it.
+      await removeBranchFromStack(meta, stackName, mergedBranch);
+    }
+  }
+
+  // Did the whole stack drain, or is there a tail to restack?
+  const survivingStack = meta.stacks[stackName];
+  const remaining = survivingStack ? getOrderedBranches(survivingStack) : [];
+
+  if (remaining.length === 0) {
+    // Fully drained — archive the original topology and land on the trunk.
+    console.log();
+    const pullSpinner = p.spinner();
+    pullSpinner.start("Syncing local trunk...");
+    try {
+      await git.checkout(trunk);
+      await $`git pull origin ${trunk}`.quiet();
+      pullSpinner.stop("Local trunk synced");
+    } catch {
+      pullSpinner.stop(pc.dim(`Could not sync ${trunk} — run git pull manually`));
+    }
+
+    if (!meta.archive) meta.archive = {};
+    meta.archive[stackName] = originalStack;
+    delete meta.stacks[stackName];
+    if (meta.current_stack === stackName) meta.current_stack = null;
+    await writeMetadata(meta);
+
+    p.outro(pc.green("All approved PRs merged — stack drained & archived."));
+    return;
+  }
+
+  // Restack the surviving tail onto the newly re-rooted bottom. The new bottom
+  // is itself already rebased onto main; restack skips it (base branch) and
+  // propagates onto its children using the snapshot taken above.
+  console.log();
+  p.log.info(
+    `Restacking ${remaining.length} remaining branch(es) onto ${pc.yellow(remaining[0]!)}...`,
+  );
+  const newBottom = remaining[0]!;
+  if (await git.localBranchExists(newBottom)) {
+    await git.checkout(newBottom);
+    const { default: restack } = await import("./restack.ts");
+    await restack([]);
+  }
+
+  p.outro(
+    pc.green(
+      `Merged ${mergeSteps.length} approved PR(s); ${remaining.length} branch(es) left as a stack on ${trunk}.`,
+    ),
+  );
+}