gh-stack 0.12.0 → 0.15.0

package/README.md

@@ -83,12 +83,19 @@ create <branch-name> [--description <desc>]
     Create a new git branch off the current branch and add it to
     the stack. The current branch must already be tracked.
 
-submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file <f>] [--dry-run]
+submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file <f>] [--restack] [--dry-run]
     Push all downstack branches to GitHub, create PRs for branches
     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.
 
+    --restack: after submitting, restack the branches above the current
+    one onto it. submit covers DOWNSTACK (trunk → current); restack covers
+    UPSTACK (the children), so together they sync the whole stack from
+    wherever you're standing. The everyday loop: drop downstack, fix an
+    issue, commit, then `submit --restack` to push the fix and propagate
+    it up in one command. Skips cleanly when nothing sits above you.
+
     Self-healing: if the current branch isn't tracked in a stack yet,
     submit auto-detects the chain from trunk → current, registers (or
     reconciles into) a stack, then pushes + creates PRs for the whole
@@ -96,9 +103,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
@@ -149,20 +161,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
@@ -413,9 +446,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.12.0",
+  "version": "0.15.0",
   "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}.`,
+    ),
+  );
+}

package/src/commands/submit.ts

@@ -4,13 +4,14 @@ import pc from "picocolors";
 import { $ } from "bun";
 import * as git from "../lib/git.ts";
 import {
+  buildRebaseChain,
   findStackForBranch,
   getOrderedBranches,
   readMetadata,
   writeMetadata,
 } from "../lib/metadata.ts";
 import { isAutoYes } from "../lib/ui.ts";
-import type { StackMetadata } from "../types.ts";
+import type { Stack, StackMetadata } from "../types.ts";
 import { getPrNumber } from "../lib/github.ts";
 import { resolveOrCreateStack } from "../lib/chain.ts";
 import { reconcilePrTitles, refreshStackViz, branchToTitle } from "./update-prs.ts";
@@ -33,15 +34,29 @@ chain. You never need to run \`gh-stack init\` first.
 OPTIONS
   -d, --draft          Create new PRs as drafts
   -n, --no-edit        Don't prompt for PR titles (auto-generate from branch name)
-  -t, --title <title>  PR title for new PRs (skips prompt)
-  -b, --body <body>    PR body/description for new PRs
+  -t, --title <title>  Set the PR title (current branch) — creates or updates
+  -b, --body <body>    Set the PR body (current branch) — creates or updates
       --body-file <f>  Read PR body from a file
+      --restack        After submitting, restack the branches above the current
+                       one onto it (propagate a downstack fix up to children)
       --dry-run        Show what would happen without doing anything
 
+Updating an existing PR: -t / -b also update the PR for the branch you're on
+if it already exists — 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 so the stack visualization is never clobbered.
+
+Restack after submit (--restack): submit covers DOWNSTACK (trunk → current);
+restack covers UPSTACK (the children above current). Together they sync the
+whole stack from wherever you're standing. The common loop: drop downstack,
+fix an issue, commit, then \`submit --restack\` to push the fix and propagate
+it up — one command instead of two. Skips cleanly if nothing sits above you.
+
 EXAMPLES
   gh-stack submit                              # Push + create PRs interactively
   gh-stack submit -n                           # Push + create PRs with auto-titles
   gh-stack submit -t "My PR" -b "Description"  # Explicit title and body
+  gh-stack submit --restack                    # Submit, then restack children onto it
   gh-stack submit --draft                      # Create new PRs as drafts
   gh-stack submit --dry-run                    # Preview what would happen
 `;
@@ -85,6 +100,7 @@ export default async function submit(args: string[]): Promise<void> {
 
   const draftFlag = args.includes("--draft") || args.includes("-d");
   const dryRun = args.includes("--dry-run");
+  const restackFlag = args.includes("--restack");
 
   // Parse value flags
   let titleFlag: string | undefined;
@@ -350,6 +366,7 @@ export default async function submit(args: string[]): Promise<void> {
         `Dry run complete: would push ${scope.length}, create ${created}, update ${existing} PR(s)`,
       ),
     );
+    if (restackFlag) await maybeRestack(stack, branch, true);
     return;
   }
 
@@ -357,9 +374,17 @@ export default async function submit(args: string[]): Promise<void> {
   // visualization. Titles first so the viz renders the numbered titles. Both
   // render locally and only hit the network for PRs that actually changed
   // (see issue #16), so a no-op re-submit is free. ──
+  // `-t`/`-b` (and `--body-file`) update the PR for the branch you're on, even
+  // if it already exists — title is renumbered, body is replaced with the viz
+  // block re-merged. This makes `submit` the one tool to update a PR without
+  // `gh pr edit` clobbering the `📚 Stacked on` block.
   p.log.info(pc.cyan("Updating PR titles & stack visualization..."));
-  const titles = await reconcilePrTitles(stack, ordered);
-  const viz = await refreshStackViz(meta, stack, ordered);
+  const titles = await reconcilePrTitles(stack, ordered, {
+    titleOverrides: titleFlag ? { [branch]: titleFlag } : undefined,
+  });
+  const viz = await refreshStackViz(meta, stack, ordered, {
+    bodyOverrides: bodyFlag ? { [branch]: bodyFlag } : undefined,
+  });
 
   // One persist for everything we cached this run (discovered PRs, base edits,
   // backfilled/renumbered titles, viz hashes).
@@ -375,4 +400,28 @@ export default async function submit(args: string[]): Promise<void> {
         (viz.unchanged > 0 ? `, ${viz.unchanged} unchanged` : ""),
     ),
   );
+
+  // ── --restack: propagate a downstack fix up to the children ──
+  // submit owns DOWNSTACK (trunk → current); restack owns UPSTACK (the branches
+  // above current). Running both from one branch syncs the whole stack.
+  if (restackFlag) await maybeRestack(stack, branch, false);
+}
+
+/**
+ * Chain into `restack` from the current branch after a submit, so a downstack
+ * fix propagates up to its children in one command. No-op (with a friendly
+ * note) when nothing sits above the current branch — there's nothing to rebase.
+ */
+async function maybeRestack(stack: Stack, branch: string, dryRun: boolean): Promise<void> {
+  // buildRebaseChain returns the current branch + all its descendants; a length
+  // of 1 means it's the top of its line, so there's nothing above to restack.
+  if (buildRebaseChain(stack, branch).length <= 1) {
+    console.log();
+    p.log.info(pc.dim(`--restack: nothing sits above ${pc.yellow(branch)} — nothing to restack.`));
+    return;
+  }
+
+  console.log();
+  const { default: restack } = await import("./restack.ts");
+  await restack(dryRun ? ["--dry-run"] : []);
 }

package/src/commands/sync.ts

@@ -1,16 +1,22 @@
 // gh-stack sync — Fetch main, rebase base branch onto main, then restack all
 import * as p from "../lib/output.ts";
 import pc from "picocolors";
+import { $ } from "bun";
 import * as git from "../lib/git.ts";
 import {
   findStackForBranch,
   getOrderedBranches,
+  removeBranchFromStack,
   saveRestackState,
   stackBase,
+  writeMetadata,
 } from "../lib/metadata.ts";
 import { ensureMetadata, ensureCleanWorkingTree, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { confirmAction } from "../lib/ui.ts";
+import { getPrInfo } from "../lib/github.ts";
+import { planMerges, advanceNewBottom, type BranchReview } from "../lib/advance.ts";
+import type { StackMetadata } from "../types.ts";
 
 export default async function sync(args: string[]): Promise<void> {
   const dryRun = args.includes("--dry-run");
@@ -50,9 +56,9 @@ with the base branch included.
     process.exit(1);
   }
 
-  const stack = meta.stacks[stackName]!;
+  let stack = meta.stacks[stackName]!;
   await ensureValidStack(meta, stackName);
-  const ordered = getOrderedBranches(stack);
+  let ordered = getOrderedBranches(stack);
 
   if (ordered.length === 0) {
     p.cancel("No branches in this stack");
@@ -64,8 +70,6 @@ with the base branch included.
   // Find the root branch (whose parent is the stack's base)
   const base = stackBase(stack);
   const baseIsTrunk = base === "main" || base === "master";
-  const baseBranch = ordered[0]!;
-  const baseParent = stack.branches[baseBranch]?.parent;
 
   // sync only makes sense for trunk-rooted stacks — it fetches main and
   // rebases onto it. A split stack is rooted on a branch in another stack, so
@@ -80,6 +84,31 @@ with the base branch included.
     process.exit(1);
   }
 
+  // Catch up to reality first: if the bottom PR(s) already landed on the trunk
+  // outside gh-stack (e.g. the GitHub web UI), the stack metadata still lists
+  // them. A plain rebase onto main would then replay their now-squashed commits
+  // and conflict — so advance past them (re-rooting the survivor onto main with
+  // `--onto`) before the normal sync runs. (#20)
+  const advance = await advanceMergedBottoms(meta, stackName, base, dryRun);
+  if (advance.drained) {
+    p.outro(pc.green("Bottom PR(s) already merged — stack fully drained & archived."));
+    return;
+  }
+  if (dryRun && advance.detected) {
+    // The advance plan was printed above; the normal rebase plan below would be
+    // misleading (it'd show replaying the merged commits), so stop here.
+    p.outro(pc.green("Sync dry run complete"));
+    return;
+  }
+  if (advance.advanced) {
+    // Topology changed — re-derive the root from the freshly-updated metadata.
+    stack = meta.stacks[stackName]!;
+    ordered = getOrderedBranches(stack);
+  }
+
+  const baseBranch = ordered[0]!;
+  const baseParent = stack.branches[baseBranch]?.parent;
+
   if (baseParent !== base) {
     p.cancel(`Root branch ${pc.yellow(baseBranch)} doesn't have ${base} as parent`);
     process.exit(1);
@@ -191,6 +220,129 @@ with the base branch included.
   }
 }
 
+/** Result of the merged-bottom catch-up pass. */
+interface AdvanceOutcome {
+  /** A merged bottom PR was found (and reported). */
+  detected: boolean;
+  /** The stack metadata + branches were actually advanced (not in dry-run). */
+  advanced: boolean;
+  /** The whole stack drained (every branch was already merged) and was archived. */
+  drained: boolean;
+}
+
+/**
+ * Detect bottom PR(s) that already merged on the trunk outside gh-stack and
+ * advance the stack past them — re-rooting the survivor onto the trunk with
+ * `--onto` so only its own commits replay (never the squashed work). Shares the
+ * planner and re-root mechanics with `merge --approved` (see ./lib/advance.ts).
+ *
+ * Returns what happened so the caller can re-derive the root or short-circuit.
+ * In dry-run it reports and makes no changes.
+ */
+async function advanceMergedBottoms(
+  meta: StackMetadata,
+  stackName: string,
+  trunk: string,
+  dryRun: boolean,
+): Promise<AdvanceOutcome> {
+  const stack = meta.stacks[stackName]!;
+  const ordered = getOrderedBranches(stack);
+
+  // Walk bottom-up gathering PR state; stop at the first branch that isn't a
+  // merged PR (only contiguous merged bottoms can be advanced past).
+  const reviews: BranchReview[] = [];
+  for (const branch of ordered) {
+    const pr = stack.branches[branch]?.pr ?? null;
+    let prState: string | null = null;
+    if (pr != null) {
+      const info = await getPrInfo(pr);
+      prState = info?.state ?? null;
+    }
+    reviews.push({ branch, pr, prState, reviewDecision: null });
+    if (prState !== "MERGED") break;
+  }
+
+  const plan = planMerges(reviews, { approveAndMerge: false });
+  if (plan.steps.length === 0) {
+    return { detected: false, advanced: false, drained: false };
+  }
+
+  p.log.warn(`${plan.steps.length} bottom PR(s) already merged on ${trunk} outside gh-stack:`);
+  for (const step of plan.steps) {
+    console.log(`  ${pc.dim("✓")} ${pc.yellow(step.branch)}${step.pr ? ` (#${step.pr})` : ""}`);
+  }
+  console.log(
+    `  ${pc.dim(`Advancing past them (re-rooting onto ${trunk}) instead of replaying squashed commits.`)}`,
+  );
+  console.log();
+
+  if (dryRun) {
+    p.log.warn("[DRY RUN] Would advance the stack past the merged bottom PR(s)");
+    return { detected: true, advanced: false, drained: false };
+  }
+
+  const targetRef = `origin/${trunk}`;
+  await $`git fetch origin ${trunk}`.quiet();
+  await takeSnapshot(meta, stackName, "sync-advance");
+  const originalStack = structuredClone(stack);
+
+  for (let i = 0; i < plan.steps.length; i++) {
+    const mergedBranch = plan.steps[i]!.branch;
+    const child = ordered[i + 1] ?? null;
+    const childPr = child ? (stack.branches[child]?.pr ?? null) : null;
+
+    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 it, then finish the restack:`);
+          console.log(`    ${pc.green("git rebase --continue")}`);
+          console.log(`    ${pc.green("gh-stack restack")}`);
+        } else {
+          p.log.error(
+            `Could not determine a safe rebase base for ${pc.yellow(child)} (${res.reason}).`,
+          );
+          console.log(
+            `  Re-root manually:\n    ${pc.green(`git rebase --onto ${targetRef} <merged-tip> ${child}`)}`,
+          );
+        }
+        process.exit(2);
+      }
+    } else {
+      await removeBranchFromStack(meta, stackName, mergedBranch);
+    }
+  }
+
+  // Whole stack drained? Archive the original topology and land on the trunk.
+  const surviving = meta.stacks[stackName];
+  if (!surviving || getOrderedBranches(surviving).length === 0) {
+    try {
+      await git.checkout(trunk);
+      await $`git pull origin ${trunk}`.quiet();
+    } catch {
+      // best-effort local sync
+    }
+    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);
+    return { detected: true, advanced: true, drained: true };
+  }
+
+  return { detected: true, advanced: true, drained: false };
+}
+
 async function promptForcePush(branch: string): Promise<void> {
   if (branch === "main" || branch === "master") return;
   if (!(await git.remoteBranchExists(branch))) return;

package/src/commands/update-prs.ts

@@ -24,7 +24,7 @@ import {
   getRepoNwo,
   prUrlFor,
 } from "../lib/github.ts";
-import type { StackMetadata, Stack, Branch } from "../types.ts";
+import type { StackMetadata, Stack } from "../types.ts";
 
 /** The ref a stack is rooted on, for rendering the base node of the viz. */
 export interface BaseRef {
@@ -138,31 +138,58 @@ export interface TitleResult {
   dirty: boolean; // metadata mutated (cached prTitle changed) — caller persists
 }
 
+/**
+ * Decide which PR titles need editing and to what. Pure (no network) so it's
+ * unit-testable. `items` must be the whole stack in order — the index drives
+ * the `(N/M)` position. The base title is an explicit `override` (from
+ * `submit -t`) when given, else the cached `prTitle`; a branch with neither a
+ * PR nor a known base is skipped (never guess from the branch name). An edit is
+ * emitted only when the desired title differs from what's cached/on GitHub.
+ */
+export function planTitleEdits<
+  T extends { pr?: number | null; prTitle?: string; override?: string },
+>(items: T[]): { item: T; desired: string }[] {
+  const total = items.length;
+  const edits: { item: T; desired: string }[] = [];
+  for (let i = 0; i < items.length; i++) {
+    const it = items[i]!;
+    if (it.pr == null) continue;
+    const base = it.override ?? it.prTitle;
+    if (!base) continue;
+    const desired = numberedTitle(base, i + 1, total);
+    if (desired !== it.prTitle) edits.push({ item: it, desired });
+  }
+  return edits;
+}
+
 /**
  * Reconcile every PR title in the stack to carry its `(N/M)` stack position.
  * Backfills any missing cached titles first (so we never clobber a real GitHub
- * title with a branch-name guess), renders the desired title from the cached
- * one, and only calls `gh pr edit --title` when it actually changed — a no-op
- * re-submit makes zero edits, while adding/reordering a branch renumbers the
- * whole stack. Run this BEFORE refreshStackViz so the viz shows numbered titles.
+ * title with a branch-name guess), then edits only the titles that actually
+ * changed — a no-op re-submit makes zero edits, while adding/reordering a
+ * branch renumbers the whole stack. Run BEFORE refreshStackViz so the viz shows
+ * numbered titles.
+ *
+ * `titleOverrides` (branch → new base title) lets `submit -t` set the current
+ * branch's title; the override is renumbered like any other title and the
+ * cache is kept in sync.
  */
-export async function reconcilePrTitles(stack: Stack, ordered: string[]): Promise<TitleResult> {
+export async function reconcilePrTitles(
+  stack: Stack,
+  ordered: string[],
+  opts: { titleOverrides?: Record<string, string> } = {},
+): Promise<TitleResult> {
   const dirtyBackfill = await backfillTitles(stack, ordered);
-  const total = ordered.length;
-
-  const plans: { pr: number; desired: string; bm: Branch }[] = [];
-  for (let i = 0; i < ordered.length; i++) {
-    const bm = stack.branches[ordered[i]!]!;
-    // Need a known base title — never guess from the branch name for an
-    // existing PR (backfill couldn't fetch it → skip rather than clobber).
-    if (bm.pr == null || !bm.prTitle) continue;
-    const desired = numberedTitle(bm.prTitle, i + 1, total);
-    if (desired !== bm.prTitle) plans.push({ pr: bm.pr, desired, bm });
-  }
+  const overrides = opts.titleOverrides ?? {};
+
+  const items = ordered.map((name) => {
+    const bm = stack.branches[name]!;
+    return { pr: bm.pr, prTitle: bm.prTitle, override: overrides[name], bm };
+  });
 
-  const oks = await mapLimit(plans, 8, async (plan) => {
-    const ok = await updatePrTitle(plan.pr, plan.desired);
-    if (ok) plan.bm.prTitle = plan.desired;
+  const oks = await mapLimit(planTitleEdits(items), 8, async ({ item, desired }) => {
+    const ok = await updatePrTitle(item.pr!, desired);
+    if (ok) item.bm.prTitle = desired;
     return ok;
   });
 
@@ -181,14 +208,20 @@ export interface VizResult {
  * Refresh the stack visualization across a stack's PRs. Renders every block
  * locally, then PATCHes only the PRs whose block actually changed (unless
  * `force`), running the surviving PATCHes concurrently.
+ *
+ * `bodyOverrides` (branch → new description) lets `submit -b` replace a PR's
+ * body: the override is used as the base instead of the current GitHub body,
+ * the managed `📚 Stacked on` block is re-merged into it, and the PR is updated
+ * even if the viz block itself didn't change.
  */
 export async function refreshStackViz(
   meta: StackMetadata,
   stack: Stack,
   ordered: string[],
-  opts: { force?: boolean } = {},
+  opts: { force?: boolean; bodyOverrides?: Record<string, string> } = {},
 ): Promise<VizResult> {
   const force = opts.force ?? false;
+  const bodyOverrides = opts.bodyOverrides ?? {};
   const nwo = await getRepoNwo();
 
   let dirty = await backfillTitles(stack, ordered);
@@ -204,7 +237,9 @@ export async function refreshStackViz(
       const viz = buildStackViz(branchInfos, i, baseRef);
       const hash = vizHash(viz);
       const bm = stack.branches[info.branch]!;
-      return { info, viz, hash, bm, needsUpdate: force || bm.vizHash !== hash };
+      // A body override forces the PATCH even when the viz block is unchanged.
+      const overridden = bodyOverrides[info.branch] != null;
+      return { info, viz, hash, bm, needsUpdate: force || overridden || bm.vizHash !== hash };
     });
 
   const toUpdate = plans.filter((plan) => plan.needsUpdate);
@@ -212,7 +247,10 @@ export async function refreshStackViz(
   const skipped = branchInfos.length - plans.length;
 
   const oks = await mapLimit(toUpdate, 8, async (plan) => {
-    const body = await getPrBody(plan.info.prNumber!);
+    // `submit -b` replaces the body; otherwise keep the PR's current body and
+    // just re-merge the viz block into it.
+    const override = bodyOverrides[plan.info.branch];
+    const body = override ?? (await getPrBody(plan.info.prNumber!));
     if (body === null) return false;
     const ok = await updatePrBody(plan.info.prNumber!, mergeViz(body, plan.viz));
     if (ok) plan.bm.vizHash = plan.hash;

package/src/index.ts

@@ -185,7 +185,7 @@ ${bold("STACK NAVIGATION")}
 ${bold("STACK MANAGEMENT")}
   ${green("restack")}        Rebase children onto updated parents
   ${green("sync")}           Sync base with main + restack all
-  ${green("merge")}          Local squash-merge top-down
+  ${green("merge")}          Squash-merge via GitHub (top-down, or --approved bottom-up)
   ${green("split")}          Cut a stack into two at a branch
   ${green("rename")}         Rename a tracked branch (keeps metadata in sync)
   ${green("delete")}         Remove a branch from the stack

package/src/lib/advance.ts

@@ -0,0 +1,185 @@
+// Advancing a stack past merged bottom PRs.
+//
+// When the bottom PR of a stack lands on `main` — whether merged by
+// `gh-stack merge --approved` or squash-merged outside the tool (the GitHub UI)
+// — the rest of the stack must be *advanced*: drop the merged branch from the
+// stack and re-root the new bottom onto `main`, replaying ONLY its own commits.
+//
+// The subtle part is the rebase fork-point. After a squash-merge, `main` carries
+// a brand-new commit that is NOT in the child's history, so `merge-base(child,
+// main)` resolves to the *original* fork — meaning a plain `git rebase main`
+// would replay the already-squashed commits and conflict. The correct base is
+// the merged branch's pre-merge tip; we resolve it exactly like `restack` does
+// (snapshot pre-rewrite tip, falling back to `merge-base(child, mergedBranch)`)
+// and rebase with `git rebase --onto main <merged-tip> <child>`.
+//
+// This module owns the planning (pure, unit-tested) and the per-step git/metadata
+// mechanics. The GitHub squash-merge itself is injected by the caller so this
+// stays free of `merge.ts`'s retry machinery.
+import * as p from "./output.ts";
+import pc from "picocolors";
+import * as git from "./git.ts";
+import type { StackMetadata } from "../types.ts";
+import { removeBranchFromStack } from "./metadata.ts";
+import { findPreRewriteSha } from "./snapshot.ts";
+import { setPrBase } from "./github.ts";
+
+/** What a single bottom branch needs: an active squash-merge, or just advancing
+ *  past one that already merged outside the tool. */
+export type MergeAction = "merge" | "advance-only";
+
+/** The bottom-up review snapshot the planner reasons over. Pure data — no I/O. */
+export interface BranchReview {
+  branch: string;
+  pr: number | null;
+  /** PR state from GitHub: "MERGED" | "OPEN" | "CLOSED" | null (no PR). */
+  prState: string | null;
+  /** "APPROVED" | "CHANGES_REQUESTED" | "REVIEW_REQUIRED" | "PENDING" | null. */
+  reviewDecision: string | null;
+}
+
+export interface PlannedStep {
+  branch: string;
+  pr: number | null;
+  action: MergeAction;
+}
+
+export interface MergePlan {
+  /** Contiguous bottom-up branches to process, in order. */
+  steps: PlannedStep[];
+  /** Where (and why) we stopped — null if the whole stack is included. */
+  stop: { branch: string; reason: string } | null;
+}
+
+/**
+ * Decide which bottom branches to drain, walking bottom-up over the ordered
+ * stack. A branch already `MERGED` is always included as `advance-only` (the
+ * stack is simply out of sync with reality and must catch up).
+ *
+ * When `approveAndMerge` is true (`merge --approved`), an unmerged branch is
+ * included as a `merge` step only if it has a PR that is `APPROVED`; the first
+ * branch that isn't stops the walk. When false (`sync` catching up to reality),
+ * only already-merged branches are drained and the first unmerged branch stops
+ * the walk regardless of its approval.
+ */
+export function planMerges(ordered: BranchReview[], opts: { approveAndMerge: boolean }): MergePlan {
+  const steps: PlannedStep[] = [];
+
+  for (const b of ordered) {
+    if (b.prState === "MERGED") {
+      steps.push({ branch: b.branch, pr: b.pr, action: "advance-only" });
+      continue;
+    }
+
+    if (!opts.approveAndMerge) {
+      // sync mode: we only advance past branches already merged on GitHub.
+      return { steps, stop: { branch: b.branch, reason: "not merged yet" } };
+    }
+
+    if (b.pr == null) {
+      return {
+        steps,
+        stop: { branch: b.branch, reason: "no PR yet — run gh-stack submit" },
+      };
+    }
+
+    if (b.reviewDecision === "APPROVED") {
+      steps.push({ branch: b.branch, pr: b.pr, action: "merge" });
+      continue;
+    }
+
+    return { steps, stop: { branch: b.branch, reason: reviewReason(b.reviewDecision) } };
+  }
+
+  return { steps, stop: null };
+}
+
+function reviewReason(decision: string | null): string {
+  switch (decision) {
+    case "CHANGES_REQUESTED":
+      return "changes requested";
+    case "REVIEW_REQUIRED":
+    case "PENDING":
+    case null:
+      return "not approved yet";
+    default:
+      return `review: ${decision}`;
+  }
+}
+
+/**
+ * Resolve the rebase fork-point for re-rooting `child` after `mergedBranch`
+ * landed on the trunk. Mirrors restack's resolver:
+ *   1. snapshot pre-rewrite tip of `mergedBranch` (handles the case where the
+ *      merged branch was itself rebased earlier in a multi-merge cascade), then
+ *   2. `merge-base(child, mergedBranch)` for the common case where the merged
+ *      branch still sits at the tip the child was stacked on.
+ * Returns null if neither resolves (caller must abort rather than guess).
+ */
+export async function resolveForkPoint(
+  meta: StackMetadata,
+  mergedBranch: string,
+  child: string,
+): Promise<string | null> {
+  const fromSnapshot = await findPreRewriteSha(meta, mergedBranch, child);
+  if (fromSnapshot) return fromSnapshot;
+  return git.mergeBase(child, mergedBranch);
+}
+
+/** Outcome of advancing a single new bottom onto the trunk. */
+export type AdvanceResult =
+  | { ok: true }
+  | { ok: false; reason: "conflict" | "no-fork-point" | "bad-fork-point"; forkPoint?: string };
+
+/**
+ * Re-root `child` (the branch that becomes the new bottom) onto `targetRef`,
+ * dropping `mergedBranch`'s now-squashed commits, then drop `mergedBranch` from
+ * the stack metadata (re-parenting `child` and any siblings onto the trunk),
+ * push the rebased child, and repoint its PR base to `recordedBase`.
+ *
+ * The caller MUST have taken a snapshot first — on a rebase conflict this leaves
+ * the in-progress `git rebase` for the user to resolve and returns `conflict`.
+ */
+export async function advanceNewBottom(opts: {
+  meta: StackMetadata;
+  stackName: string;
+  mergedBranch: string;
+  child: string;
+  childPr: number | null;
+  targetRef: string;
+  recordedBase: string;
+}): Promise<AdvanceResult> {
+  const { meta, stackName, mergedBranch, child, childPr, targetRef, recordedBase } = opts;
+
+  const forkPoint = await resolveForkPoint(meta, mergedBranch, child);
+  if (!forkPoint) return { ok: false, reason: "no-fork-point" };
+
+  // Guard: the fork-point must be an ancestor of the child, else `--onto` would
+  // replay an unrelated range. Bail loudly rather than mangle history.
+  if (!(await git.isAncestor(forkPoint, child))) {
+    return { ok: false, reason: "bad-fork-point", forkPoint };
+  }
+
+  p.log.info(
+    `Re-rooting ${pc.yellow(child)} onto ${pc.green(recordedBase)} ${pc.dim(`(base: ${forkPoint.slice(0, 8)})`)}`,
+  );
+  const ok = await git.rebaseOnto(targetRef, forkPoint, child);
+  if (!ok) return { ok: false, reason: "conflict", forkPoint };
+
+  // Push the rebased head first so the PR diff is clean before its base flips.
+  await git.pushStackedBranch(child);
+  if (childPr != null) {
+    const moved = await setPrBase(childPr, recordedBase);
+    if (moved) {
+      p.log.success(`PR #${childPr} base → ${pc.green(recordedBase)}`);
+    } else {
+      p.log.warn(`Could not retarget PR #${childPr} — set its base to ${recordedBase} manually`);
+    }
+  }
+
+  // Metadata last: re-parents child (and siblings) onto the merged branch's
+  // parent (the trunk) and writes. Done after the git work succeeds so a failure
+  // never leaves metadata describing a state git didn't reach.
+  await removeBranchFromStack(meta, stackName, mergedBranch);
+  return { ok: true };
+}

package/src/lib/github.ts

@@ -149,7 +149,21 @@ export async function updatePrTitle(prNumber: number, title: string): Promise<bo
 }
 
 /**
- * Get PR body text.
+ * Repoint a PR's base branch on GitHub (`gh pr edit --base <base>`). Used when a
+ * stack advances past a merged bottom: the new bottom PR must retarget `main`.
+ * Returns false on failure.
+ */
+export async function setPrBase(prNumber: number, base: string): Promise<boolean> {
+  try {
+    await $`gh pr edit ${prNumber} --base ${base}`.quiet();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get body text for a PR.
  */
 export async function getPrBody(prNumber: number): Promise<string | null> {
   try {