gh-stack 0.3.0 → 0.4.0

package/README.md

@@ -117,7 +117,8 @@ ls
 ```
 restack [--resume] [--dry-run] [--verbose]
     Rebase the current branch and all descendants onto their parents.
-    Uses tag-based references for stable rebasing across the chain.
+    Uses metadata snapshots to recover the correct rebase base even
+    after a parent's history has been rewritten.
 
     On conflict:
         git rebase --continue
@@ -127,13 +128,15 @@ restack [--resume] [--dry-run] [--verbose]
 
 sync [--dry-run]
     Fetch main, rebase the base branch onto main, then restack all
-    children. Creates tags for ALL branches before any rebasing starts.
+    children. Snapshots every branch's pre-sync tip so children can be
+    correctly rebased even though their parent's history was rewritten.
 
 merge [--dry-run] [-d|--delete-branch]
     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.
+    automatically, and GitHub Actions fire normally. Skips already-
+    merged PRs (safe to re-run). Waits for GitHub between merges.
 
 delete [<branch>]
     Remove a branch from the stack and re-parent its children.
@@ -180,9 +183,13 @@ GH_STACK_NO_COLOR=1    Disable colored output
 
 `gh-stack init` auto-detects branch chains by walking git ancestry. From the top branch, it finds all local branches whose tips are strict ancestors (but not already merged into trunk) and reconstructs the chain with correct parent relationships.
 
-### Tag-Based Rebasing
+### Snapshot-Based Rebasing
 
-The critical insight: after rebasing a parent branch, `git merge-base` returns wrong results for its children. gh-stack solves this by creating temporary `stack-sync-*` tags marking each branch's divergence point **before** any rebasing starts, then using those stable references for `git rebase --onto`.
+The critical insight: after a parent branch's history is rewritten (e.g., rebased onto a new main), `git merge-base(child, parent)` falls all the way back to the original main — and using that as a rebase base would replay the parent's old commits onto the child, producing ghost-conflicts on the parent's own work.
+
+gh-stack solves this by snapshotting every branch's tip **before** any destructive operation. When restacking a child whose parent has been rewritten, gh-stack walks the snapshots newest-first and finds the most recent recorded tip that's no longer an ancestor of the parent's current tip. That orphaned SHA is the correct rebase base — `git rebase --onto <new-parent-tip> <orphaned-old-tip> <child>` replays only the child's unique commits.
+
+Snapshots also power `gh-stack undo`, so the same data structure does double duty.
 
 ### Stack Visualization
 

package/package.json

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

package/src/commands/merge.ts

@@ -6,8 +6,38 @@ import * as git from "../lib/git.ts";
 import { findStackForBranch, getOrderedBranches, writeMetadata } from "../lib/metadata.ts";
 import { ensureMetadata, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
+import { getPrMergeState } from "../lib/github.ts";
 import { confirmAction } from "../lib/ui.ts";
 
+const MAX_RETRIES = 12;
+const RETRY_DELAY_MS = 5000;
+
+/**
+ * Wait for a PR to become mergeable after a previous merge lands.
+ * GitHub needs time to process the new commit on the target branch.
+ */
+async function waitForMergeable(
+  prNumber: number,
+  spinner: ReturnType<typeof p.spinner>,
+): Promise<boolean> {
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    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;
+    }
+
+    spinner.message(`Waiting for PR #${prNumber} to be ready... (${attempt}/${MAX_RETRIES})`);
+    await Bun.sleep(RETRY_DELAY_MS);
+  }
+  return false;
+}
+
 export default async function merge(args: string[]): Promise<void> {
   const dryRun = args.includes("--dry-run");
   const deleteFlag = args.includes("--delete-branch") || args.includes("-d");
@@ -25,6 +55,9 @@ Squash-merges the stack from top to bottom via GitHub:
 All merges happen on GitHub, so PRs show as "Merged", Linear tickets
 close automatically, and all GitHub Actions/webhooks fire normally.
 
+Skips PRs that are already merged (safe to re-run after partial failure).
+Waits for GitHub to process between merges if needed.
+
 OPTIONS
   -d, --delete-branch  Delete remote branches after merging
       --dry-run        Show what would happen without doing anything
@@ -65,23 +98,29 @@ OPTIONS
   }
 
   p.intro(pc.cyan("Stack Merge (via GitHub)"));
-
   p.log.info(`Stack: ${pc.yellow(stackName)}`);
   console.log();
 
-  // Show the merge plan: from top to bottom
+  // Check PR states and build the merge plan
   const reversed = ordered.toReversed();
+  const baseBranch = ordered[0]!;
+  const basePr = stack.branches[baseBranch]?.pr;
+
   console.log(`  ${pc.bold("Merge plan:")}`);
   for (let i = 0; i < reversed.length - 1; i++) {
     const child = reversed[i]!;
     const parent = stack.branches[child]?.parent || "???";
     const childPr = stack.branches[child]?.pr;
+
+    // Check if already merged
+    const prState = childPr ? await getPrMergeState(childPr) : null;
+    const isMerged = prState?.state === "MERGED";
+    const mergedLabel = isMerged ? pc.dim(" (already merged)") : "";
+
     console.log(
-      `    ${pc.yellow(child)}${childPr ? ` (#${childPr})` : ""} → squash into ${pc.blue(parent)}`,
+      `    ${pc.yellow(child)}${childPr ? ` (#${childPr})` : ""} → squash into ${pc.blue(parent)}${mergedLabel}`,
     );
   }
-  const baseBranch = ordered[0]!;
-  const basePr = stack.branches[baseBranch]?.pr;
   console.log(
     `    ${pc.blue(baseBranch)}${basePr ? ` (#${basePr})` : ""} → ${pc.green("main")} (auto-merge)`,
   );
@@ -118,6 +157,13 @@ OPTIONS
 
     if (parentBranch === "main" || parentBranch === "master") continue;
 
+    // Check if already merged (skip)
+    const prState = await getPrMergeState(childPrNum);
+    if (prState?.state === "MERGED") {
+      p.log.info(`${pc.dim("✓")} PR #${childPrNum} already merged — skipping`);
+      continue;
+    }
+
     console.log();
     console.log(pc.cyan("━".repeat(40)));
     console.log(
@@ -125,8 +171,19 @@ OPTIONS
     );
     console.log(pc.cyan("━".repeat(40)));
 
+    // Wait for PR to be mergeable (GitHub may need time after previous merge)
     const s = p.spinner();
-    s.start(`Squash-merging PR #${childPrNum} via GitHub...`);
+    s.start(`Checking PR #${childPrNum} is ready to merge...`);
+    const ready = await waitForMergeable(childPrNum, s);
+
+    if (!ready) {
+      s.stop(pc.red(`PR #${childPrNum} is not mergeable`));
+      p.log.info("Check the PR on GitHub for merge conflicts or required checks.");
+      p.log.info("Re-run merge to continue from where you left off.");
+      process.exit(2);
+    }
+
+    s.message(`Squash-merging PR #${childPrNum} via GitHub...`);
 
     const ghArgs = ["pr", "merge", String(childPrNum), "--squash"];
     if (deleteFlag) ghArgs.push("--delete-branch");
@@ -143,7 +200,7 @@ OPTIONS
     } else {
       s.stop(pc.red(`Failed to merge PR #${childPrNum}`));
       p.log.error(stderr.trim());
-      p.log.info("Resolve the issue on GitHub, then re-run merge to continue.");
+      p.log.info("Re-run merge to continue from where you left off.");
       process.exit(2);
     }
   }
@@ -157,12 +214,23 @@ OPTIONS
   console.log(pc.cyan("━".repeat(40)));
 
   const autoSpinner = p.spinner();
-  autoSpinner.start(`Enabling auto-merge for PR #${basePr}...`);
+
+  // Wait for base PR to be ready (may need time after last intermediate merge)
+  autoSpinner.start(`Waiting for PR #${basePr} to be ready...`);
+  await waitForMergeable(basePr!, autoSpinner);
+
+  autoSpinner.message(`Enabling auto-merge for PR #${basePr}...`);
 
   try {
     const ghArgs = ["pr", "merge", String(basePr), "--squash", "--auto"];
     if (deleteFlag) ghArgs.push("--delete-branch");
-    await $`gh pr merge ${basePr} --squash --auto ${deleteFlag ? "--delete-branch" : ""}`.quiet();
+
+    const proc = Bun.spawn(["gh", ...ghArgs], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    await proc.exited;
+
     autoSpinner.stop(`Auto-merge enabled for PR #${basePr} — will merge into main when CI passes`);
   } catch {
     autoSpinner.stop(pc.yellow(`Could not enable auto-merge for PR #${basePr}`));
@@ -175,7 +243,6 @@ OPTIONS
   pullSpinner.start("Syncing local branches...");
   try {
     await $`git fetch origin`.quiet();
-    // Checkout main and pull so local is up to date
     await git.checkout("main");
     await $`git pull origin main`.quiet();
     pullSpinner.stop("Local branches synced");

package/src/commands/restack.ts

@@ -9,6 +9,7 @@ import {
   saveRestackState,
   loadRestackState,
   clearRestackState,
+  readMetadata,
 } from "../lib/metadata.ts";
 import {
   ensureMetadata,
@@ -16,7 +17,7 @@ import {
   ensureNotMain,
   ensureValidStack,
 } from "../lib/safety.ts";
-import { takeSnapshot } from "../lib/snapshot.ts";
+import { takeSnapshot, findPreRewriteSha } from "../lib/snapshot.ts";
 import { confirmAction } from "../lib/ui.ts";
 import type { StackMetadata } from "../types.ts";
 
@@ -36,7 +37,7 @@ OPTIONS
   --yes, -y   Skip confirmations (auto-accept all rebases and pushes)
   --resume    Resume after resolving rebase conflicts
   --dry-run   Show what would happen without executing
-  --verbose   Show diagnostic info (tag vs merge-base)
+  --verbose   Show diagnostic info (snapshot vs merge-base)
 
 EXAMPLES
   gh-stack restack              Interactive (prompts before each rebase)
@@ -49,6 +50,16 @@ ALIASES
     return;
   }
 
+  // Reject if a git rebase is already in progress (unless we're resuming).
+  // Letting commands run on top of a half-finished rebase produces deeply
+  // confusing state — better to make the user finish or abort first.
+  if (!resume && (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")}\n\n  Then re-run ${pc.green("gh-stack restack")} (or ${pc.green("gh-stack restack --resume")} to continue).`,
+    );
+    process.exit(1);
+  }
+
   // Ensure clean working tree (unless resuming)
   if (!resume) {
     await ensureCleanWorkingTree();
@@ -59,6 +70,10 @@ ALIASES
 
   p.intro(pc.cyan("Git Stack Restack"));
 
+  // Silently drop any leftover temp tags from older versions of gh-stack
+  // (pre-snapshot). Keeps users upgrading from <0.4 from seeing stale tags.
+  await git.deleteTagsMatching(git.STACK_SYNC_TAG_GLOB);
+
   if (resume) {
     await handleResume(meta, rebasedBranches, verbose);
   } else {
@@ -76,9 +91,6 @@ ALIASES
     }
   }
 
-  // Cleanup tags
-  await git.deleteTagsMatching(git.STACK_SYNC_TAG_GLOB);
-
   p.outro(pc.green("Stack Restack Complete!"));
 }
 
@@ -137,38 +149,8 @@ async function handleResume(
   const currentIndex = state.current_index + 1;
 
   if (currentIndex < chain.length) {
-    // Ensure temporary tags exist for remaining branches.
-    // If sync created them upfront (correct!), they'll already be here.
-    // If not (e.g., old state file), we create them as a fallback —
-    // but NOTE: tags created after parent was rebased may be inaccurate.
-    p.log.info("Checking base tags for remaining branches...");
-    for (let i = currentIndex; i < chain.length; i++) {
-      const branch = chain[i]!;
-      const parent = stack.branches[branch]?.parent;
-      if (!parent) continue;
-
-      const tagName = git.tempBaseTagName(branch);
-      if (await git.tagExists(tagName)) {
-        const tagSha = await git.revParse(tagName);
-        console.log(
-          `  ${pc.green("✓")} Pre-existing tag for ${branch}: ${pc.cyan(tagName)} (${tagSha.slice(0, 8)})`,
-        );
-      } else {
-        // Fallback: create tag now (may be inaccurate if parent already rebased)
-        p.log.warn(`No pre-existing tag for ${branch} — creating from current merge-base`);
-        const mb = await git.mergeBase(branch, parent);
-        if (mb) {
-          await git.createTag(tagName, mb);
-          console.log(
-            `  ${pc.yellow("⚠")} Tagged base for ${branch}: ${pc.cyan(tagName)} (${mb.slice(0, 8)})`,
-          );
-        }
-      }
-    }
-    console.log();
+    await processChain(meta, stackName, chain, currentIndex, rebasedBranches, false, verbose);
   }
-
-  await processChain(meta, stackName, chain, currentIndex, rebasedBranches, false, verbose);
 }
 
 async function handleFreshRestack(
@@ -190,9 +172,6 @@ async function handleFreshRestack(
   const stack = meta.stacks[stackName]!;
   await ensureValidStack(meta, stackName);
 
-  // Check for stale tags from previous runs
-  await handleStaleTags();
-
   // Build the rebase chain from current branch
   p.log.info("Building rebase chain...");
   let chain = buildRebaseChain(stack, currentBranch);
@@ -242,25 +221,10 @@ async function handleFreshRestack(
   }
 
   if (!dryRun) {
-    // Take snapshot before destructive operation
+    // Take snapshot before destructive operation. This preserves the current
+    // tip of every branch so subsequent restacks (after a parent is rewritten)
+    // can find the correct rebase base.
     await takeSnapshot(meta, stackName, "restack");
-
-    // Create temporary tags for stable base references
-    p.log.info("Creating temporary base tags...");
-    for (const branch of chain) {
-      const parent = stack.branches[branch]?.parent;
-      if (!parent) continue;
-
-      const mb = await git.mergeBase(branch, parent);
-      if (mb) {
-        const tagName = git.tempBaseTagName(branch);
-        await git.createTag(tagName, mb);
-        console.log(
-          `  ${pc.green("✓")} Tagged base for ${branch}: ${pc.cyan(tagName)} (${mb.slice(0, 8)})`,
-        );
-      }
-    }
-    console.log();
   }
 
   // Process the chain
@@ -313,6 +277,44 @@ async function processChain(
       continue;
     }
 
+    // Resolve the rebase base.
+    //
+    //   Strategy:
+    //     1. Look for a recent snapshot where the parent's recorded tip is no
+    //        longer an ancestor of the parent's current tip. That recorded SHA
+    //        is the orphaned old-parent tip — exactly the rebase base we need.
+    //     2. Fall back to `merge-base(branch, parent)` if no snapshot tells us
+    //        the parent was rewritten (typical case: parent only had commits
+    //        appended, not rebased).
+    //
+    //   Re-read metadata fresh because previous iterations of this loop may
+    //   have updated snapshots.
+    const freshMeta = (await readMetadata()) ?? meta;
+    const oldBaseFromSnapshot = await findPreRewriteSha(freshMeta, parent);
+    const oldBaseFromMergeBase = await git.mergeBase(branch, parent);
+    const oldBase = oldBaseFromSnapshot ?? oldBaseFromMergeBase;
+
+    if (verbose) {
+      console.log();
+      console.log(pc.yellow("  Diagnostic: base resolution"));
+      console.log(
+        `  ${pc.cyan("Snapshot pre-rewrite tip:")} ${oldBaseFromSnapshot?.slice(0, 8) ?? "(none)"}`,
+      );
+      console.log(
+        `  ${pc.cyan("Current merge-base:")}      ${oldBaseFromMergeBase?.slice(0, 8) ?? "(none)"}`,
+      );
+      if (
+        oldBaseFromSnapshot &&
+        oldBaseFromMergeBase &&
+        oldBaseFromSnapshot !== oldBaseFromMergeBase
+      ) {
+        console.log(
+          `  ${pc.yellow("⚠ Parent was rewritten")} — using snapshot base (would have replayed parent commits otherwise)`,
+        );
+      }
+      console.log();
+    }
+
     // Checkout the branch
     p.log.info(`Checking out ${pc.yellow(branch)}...`);
     await git.checkout(branch);
@@ -324,49 +326,22 @@ async function processChain(
       chain,
     });
 
-    // Use temporary tag as stable base reference
-    const tagName = git.tempBaseTagName(branch);
     let success: boolean;
-
-    if (await git.tagExists(tagName)) {
-      const taggedBase = await git.revParse(tagName);
-      p.log.info(`Using tagged base: ${pc.cyan(tagName)} (${taggedBase.slice(0, 8)})`);
+    if (oldBase) {
+      const sourceLabel = oldBaseFromSnapshot ? "snapshot" : "merge-base";
+      p.log.info(
+        `Rebasing onto ${pc.yellow(parent)} (base: ${oldBase.slice(0, 8)} from ${sourceLabel})`,
+      );
 
       if (verbose) {
-        const currentMb = await git.mergeBase(branch, parent);
-        console.log();
-        console.log(pc.yellow("  Diagnostic: Tag vs Merge-Base"));
-        console.log(`  ${pc.cyan("Tagged base:")}      ${taggedBase.slice(0, 8)}`);
-        if (currentMb) {
-          console.log(`  ${pc.cyan("Current merge-base:")} ${currentMb.slice(0, 8)}`);
-          if (taggedBase === currentMb) {
-            console.log(`  ${pc.green("✓ Same")} — Parent hasn't been updated`);
-          } else {
-            console.log(`  ${pc.yellow("⚠ Different")} — Parent was rebased (tag protects us!)`);
-          }
-        }
-        console.log();
-      }
-
-      p.log.info(`Rebasing onto ${pc.yellow(parent)}...`);
-      const count = await git.commitCount(taggedBase, branch);
-      if (verbose) {
+        const count = await git.commitCount(oldBase, branch);
         console.log(`  Moving ${count} commit(s)`);
       }
 
-      success = await git.rebaseOnto(parent, tagName, branch);
+      success = await git.rebaseOnto(parent, oldBase, branch);
     } else {
-      // Fallback to merge-base
-      p.log.warn("Tag not found, calculating merge-base...");
-      const oldBase = await git.mergeBase(branch, parent);
-
-      if (!oldBase) {
-        p.log.warn("Could not find merge-base, using simple rebase");
-        success = await git.rebase(parent);
-      } else {
-        p.log.info(`Found merge-base: ${oldBase.slice(0, 8)}`);
-        success = await git.rebaseOnto(parent, oldBase, branch);
-      }
+      p.log.warn("Could not determine rebase base — using simple rebase");
+      success = await git.rebase(parent);
     }
 
     if (success) {
@@ -435,50 +410,3 @@ async function promptPush(branch: string): Promise<void> {
     p.log.warn("Skipping push (you'll need to push manually)");
   }
 }
-
-async function handleStaleTags(): Promise<void> {
-  try {
-    const { $ } = await import("bun");
-    const result = await $`git tag -l ${git.STACK_SYNC_TAG_GLOB}`.text();
-    const tags = result.trim();
-    if (!tags) return;
-
-    p.log.warn(`Found stale ${git.STACK_SYNC_TAG_GLOB} tags from a previous run`);
-    console.log();
-
-    const action = await p.select({
-      message: "What would you like to do?",
-      options: [
-        {
-          value: "clean",
-          label: "Clean up tags and start fresh",
-        },
-        {
-          value: "resume",
-          label: "Resume from previous sync (--resume)",
-        },
-        { value: "abort", label: "Abort (keep tags, exit)" },
-      ],
-    });
-
-    if (p.isCancel(action) || action === "abort") {
-      p.cancel("Aborted");
-      process.exit(0);
-    }
-
-    if (action === "clean") {
-      p.log.info("Cleaning up stale tags...");
-      await git.deleteTagsMatching(git.STACK_SYNC_TAG_GLOB);
-      p.log.success("Tags cleaned");
-    }
-
-    if (action === "resume") {
-      // Re-run with --resume flag
-      const { default: restack } = await import("./restack.ts");
-      await restack(["--resume"]);
-      process.exit(0);
-    }
-  } catch {
-    // No stale tags — carry on
-  }
-}

package/src/commands/sync.ts

@@ -24,6 +24,16 @@ with the base branch included.
     return;
   }
 
+  // Reject if a git rebase is already in progress. Letting sync run on top
+  // of a half-finished rebase produces deeply confusing state — make the
+  // user finish or abort it first.
+  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")}\n\n  Then re-run ${pc.green("gh-stack sync")}.`,
+    );
+    process.exit(1);
+  }
+
   await ensureCleanWorkingTree();
 
   const meta = await ensureMetadata();
@@ -83,31 +93,11 @@ with the base branch included.
   await git.fetchMain();
   fetchSpinner.stop("Fetched latest main");
 
-  // Take snapshot
+  // Take snapshot BEFORE rebasing. This records every branch's pre-rebase
+  // tip — including the orphaned base-branch tip that restack will later
+  // need to find when restacking children. (See findPreRewriteSha.)
   await takeSnapshot(meta, stackName, "sync");
 
-  // Create temporary tags for ALL branches BEFORE any rebasing starts.
-  // This is critical: after rebasing PR1, `git merge-base PR2 PR1` returns
-  // wrong results. Tags capture the true divergence points while history
-  // is still intact.
-  p.log.info("Creating temporary base tags for all branches...");
-  for (const branch of ordered) {
-    const parent = stack.branches[branch]?.parent;
-    if (!parent) continue;
-
-    // For the base branch, the "parent" is main — tag its merge-base with main
-    const parentRef = parent === "main" ? "origin/main" : parent;
-    const mb = await git.mergeBase(branch, parentRef);
-    if (mb) {
-      const tagName = git.tempBaseTagName(branch);
-      await git.createTag(tagName, mb);
-      console.log(
-        `  ${pc.green("✓")} Tagged base for ${branch}: ${pc.cyan(tagName)} (${mb.slice(0, 8)})`,
-      );
-    }
-  }
-  console.log();
-
   // Step 1: Rebase base branch onto main
   console.log();
   console.log(pc.cyan("━".repeat(40)));

package/src/lib/github.ts

@@ -124,6 +124,21 @@ export async function getPrBody(prNumber: number): Promise<string | null> {
   }
 }
 
+/**
+ * Get the merge state of a PR.
+ * Returns { state, mergeable, mergeStateStatus }.
+ */
+export async function getPrMergeState(
+  prNumber: number,
+): Promise<{ state: string; mergeable: string; mergeStateStatus: string } | null> {
+  try {
+    const result = await $`gh pr view ${prNumber} --json state,mergeable,mergeStateStatus`.text();
+    return JSON.parse(result.trim());
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Close a PR with a comment.
  */

package/src/lib/snapshot.ts

@@ -1,8 +1,55 @@
-// Snapshot system for undo support
+// Snapshot system for undo support and pre-rewrite base recovery
 import type { StackMetadata, Snapshot } from "../types.ts";
 import * as git from "./git.ts";
 import { writeMetadata, getOrderedBranches } from "./metadata.ts";
 
+/**
+ * Find the pre-rewrite SHA for a branch by walking snapshots newest-first.
+ *
+ * Returns the SHA from the most recent snapshot whose recorded tip for
+ * `branchName` is NOT an ancestor of the branch's current tip — meaning
+ * that snapshot was taken before the branch's history got rewritten
+ * (typically by `sync` rebasing it onto a new main).
+ *
+ * That pre-rewrite SHA is the correct rebase base when restacking a child
+ * onto this branch — `git rebase --onto <new-tip> <pre-rewrite-tip> <child>`
+ * replays only the child's unique commits, never the parent's old history.
+ *
+ * Returns null if no snapshots exist or every snapshot's recorded tip is
+ * still an ancestor of the current tip (i.e., the branch has only had
+ * commits appended, never been rebased — `merge-base` is still correct).
+ */
+export async function findPreRewriteSha(
+  meta: StackMetadata,
+  branchName: string,
+): Promise<string | null> {
+  if (!meta.snapshots || meta.snapshots.length === 0) return null;
+
+  let currentTip: string;
+  try {
+    currentTip = await git.revParse(branchName);
+  } catch {
+    return null;
+  }
+
+  // Walk newest → oldest
+  for (let i = meta.snapshots.length - 1; i >= 0; i--) {
+    const recorded = meta.snapshots[i]!.branches[branchName];
+    if (!recorded) continue;
+    if (recorded === currentTip) continue;
+
+    // If the recorded SHA is no longer an ancestor of the current tip,
+    // the branch's history was rewritten between then and now.
+    // That recorded SHA is the orphaned tip we need.
+    const stillAncestor = await git.isAncestor(recorded, currentTip);
+    if (!stillAncestor) {
+      return recorded;
+    }
+  }
+
+  return null;
+}
+
 const MAX_SNAPSHOTS = 10;
 
 /**