gh-stack 0.11.0 → 0.14.1

package/src/commands/submit.ts

@@ -13,7 +13,7 @@ import { isAutoYes } from "../lib/ui.ts";
 import type { StackMetadata } from "../types.ts";
 import { getPrNumber } from "../lib/github.ts";
 import { resolveOrCreateStack } from "../lib/chain.ts";
-import { refreshStackViz, branchToTitle } from "./update-prs.ts";
+import { reconcilePrTitles, refreshStackViz, branchToTitle } from "./update-prs.ts";
 
 const HELP = `
 gh-stack submit — Push branches and create/update PRs
@@ -33,11 +33,16 @@ 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
       --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.
+
 EXAMPLES
   gh-stack submit                              # Push + create PRs interactively
   gh-stack submit -n                           # Push + create PRs with auto-titles
@@ -353,14 +358,25 @@ export default async function submit(args: string[]): Promise<void> {
     return;
   }
 
-  // ── Phase 2: Refresh the stack visualization (renders locally, PATCHes only
-  // the PRs whose block actually changed; see issue #16). ──
-  p.log.info(pc.cyan("Updating stack visualization..."));
-  const viz = await refreshStackViz(meta, stack, ordered);
+  // ── Phase 2: Reconcile PR titles (stack position) then refresh the stack
+  // 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, {
+    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 titles, viz hashes).
-  if (metadataChanged || viz.dirty) {
+  // backfilled/renumbered titles, viz hashes).
+  if (metadataChanged || titles.dirty || viz.dirty) {
     await writeMetadata(meta);
   }
 
@@ -368,7 +384,7 @@ export default async function submit(args: string[]): Promise<void> {
   console.log();
   p.outro(
     pc.green(
-      `Done! Pushed ${pushed} branch(es), created ${created} PR(s), updated ${viz.updated} description(s)` +
+      `Done! Pushed ${pushed} branch(es), created ${created} PR(s), updated ${viz.updated} description(s), ${titles.updated} title(s)` +
         (viz.unchanged > 0 ? `, ${viz.unchanged} unchanged` : ""),
     ),
   );

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

@@ -16,7 +16,14 @@ import {
   writeMetadata,
 } from "../lib/metadata.ts";
 import { ensureMetadata } from "../lib/safety.ts";
-import { getPrInfo, getPrBody, updatePrBody, getRepoNwo, prUrlFor } from "../lib/github.ts";
+import {
+  getPrInfo,
+  getPrBody,
+  updatePrBody,
+  updatePrTitle,
+  getRepoNwo,
+  prUrlFor,
+} from "../lib/github.ts";
 import type { StackMetadata, Stack } from "../types.ts";
 
 /** The ref a stack is rooted on, for rendering the base node of the viz. */
@@ -103,6 +110,93 @@ function mergeViz(body: string, viz: string): string {
   return base ? `${base}\n\n${viz}` : viz;
 }
 
+// ── PR-title stack numbering ──
+//
+// The stack position lives in the PR title as a ` (N/M)` suffix so reviewers
+// can see order from a bare "needs review" list (parens, not brackets, to avoid
+// colliding with `[BEE-1234]` ticket tags). The cached `prTitle` tracks exactly
+// what's on GitHub; we recover the base title by stripping the suffix and
+// re-applying the current position, so reordering/adding a branch renumbers the
+// whole stack and a no-op re-submit touches nothing.
+
+/** Matches a trailing ` (N/M)` stack-position suffix, e.g. " (2/4)". */
+const SEQ_SUFFIX = /\s*\(\d+\/\d+\)\s*$/;
+
+/** Strip a trailing ` (N/M)` suffix to recover the base PR title. */
+export function stripSeqSuffix(title: string): string {
+  return title.replace(SEQ_SUFFIX, "").trimEnd();
+}
+
+/** The title a branch at `position` of `total` should have. Idempotent. */
+export function numberedTitle(title: string, position: number, total: number): string {
+  const base = stripSeqSuffix(title);
+  return total >= 2 ? `${base} (${position}/${total})` : base;
+}
+
+export interface TitleResult {
+  updated: number; // PR titles we edited on GitHub
+  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), 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[],
+  opts: { titleOverrides?: Record<string, string> } = {},
+): Promise<TitleResult> {
+  const dirtyBackfill = await backfillTitles(stack, ordered);
+  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(planTitleEdits(items), 8, async ({ item, desired }) => {
+    const ok = await updatePrTitle(item.pr!, desired);
+    if (ok) item.bm.prTitle = desired;
+    return ok;
+  });
+
+  const updated = oks.filter(Boolean).length;
+  return { updated, dirty: dirtyBackfill || updated > 0 };
+}
+
 export interface VizResult {
   updated: number; // PRs whose description we PATCHed
   unchanged: number; // PRs skipped because their rendered block was identical
@@ -114,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);
@@ -137,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);
@@ -145,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;
@@ -192,16 +297,17 @@ PRs whose rendered block is unchanged are skipped; --force rewrites all.
   console.log();
 
   const s = p.spinner();
-  s.start("Updating PR descriptions...");
+  s.start("Updating PR titles & descriptions...");
+  const titles = await reconcilePrTitles(stack, ordered);
   const result = await refreshStackViz(meta, stack, ordered, { force });
   s.stop("Done");
 
-  if (result.dirty) await writeMetadata(meta);
+  if (titles.dirty || result.dirty) await writeMetadata(meta);
 
   console.log();
   p.outro(
     pc.green(
-      `Updated ${result.updated} PR(s)` +
+      `Updated ${result.updated} description(s), ${titles.updated} title(s)` +
         (result.unchanged > 0 ? `, ${result.unchanged} unchanged` : "") +
         (result.skipped > 0 ? `, ${result.skipped} without PRs` : ""),
     ),
@@ -249,9 +355,9 @@ export function buildStackViz(
     // Tree character
     const tree = isLast ? "┗━" : "┣━";
 
-    // Leading `N.` is the branch's 1-based position in the stack — makes it
-    // easy to tell which PR is #6 in a 12-PR stack at a glance.
-    lines.push(`${tree} ${i + 1}. ${prLink} ${info.prTitle}${marker}`);
+    // No leading `N.` — the stack position now lives in the PR title itself as
+    // a `(N/M)` suffix (see reconcilePrTitles), so the tree just shows titles.
+    lines.push(`${tree} ${prLink} ${info.prTitle}${marker}`);
 
     if (!isLast) {
       lines.push("┃");

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 };
+}