gh-stack 0.17.0 → 0.17.2

package/README.md

@@ -342,6 +342,8 @@ The critical insight: after a parent branch's history is rewritten (e.g., rebase
 
 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.
 
+If the child sat **behind** the parent when the snapshot was taken (a placeholder branch created before any work landed on it), the recorded tip isn't in the child's history — but it still pins the parent's pre-rewrite history, so the boundary is derived as the child's fork point on it (`merge-base(child, recorded-tip)`). A child with no unique commits is simply moved to the parent's tip, no rebase involved. When no safe boundary can be determined at all, restack refuses with a manual `git rebase --onto` recipe rather than guessing.
+
 Snapshots also power `gh-stack undo`, so the same data structure does double duty.
 
 ### Stack Position in PR Titles

package/package.json

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

package/src/commands/restack.ts

@@ -15,7 +15,7 @@ import {
   writeMetadata,
 } from "../lib/metadata.ts";
 import { ensureMetadata, ensureCleanWorkingTree, ensureValidStack } from "../lib/safety.ts";
-import { takeSnapshot, findPreRewriteSha } from "../lib/snapshot.ts";
+import { takeSnapshot, resolveRestackBoundary, findRecordedBaseTip } from "../lib/snapshot.ts";
 import { confirmAction } from "../lib/ui.ts";
 import type { StackMetadata } from "../types.ts";
 
@@ -345,6 +345,36 @@ async function handleFreshRestack(
  * the new base (the now-merged parent commits are dropped). Children then
  * restack onto the moved root via the normal chain logic.
  */
+// Resolve the boundary commit for re-rooting a stack's root off its old base:
+// the tip of the old base branch that the root was built on. Returns null when
+// it can't be determined safely, so the caller refuses rather than replaying
+// already-merged commits (issue #13).
+async function resolveRerootBoundary(
+  meta: StackMetadata,
+  oldBase: string,
+  root: string,
+): Promise<{ sha: string | null; source: string }> {
+  // 1. The live base branch tip — but only if the root still sits on it. If the
+  //    base was rewritten after the root forked, its current tip isn't the
+  //    boundary; fall through to the recorded tip.
+  if (await git.localBranchExists(oldBase)) {
+    const tip = await git.revParse(oldBase);
+    if (tip && (await git.isAncestor(tip, root))) {
+      return { sha: tip, source: "old-base branch tip" };
+    }
+  }
+
+  // 2. The tip recorded in a snapshot — survives the base branch being deleted
+  //    or rewritten by a squash-merge of the parent stack.
+  const recorded = await findRecordedBaseTip(meta, oldBase, root);
+  if (recorded) {
+    return { sha: recorded, source: "snapshot (old base branch gone/rewritten)" };
+  }
+
+  // 3. Unknown — refuse rather than replay merged commits.
+  return { sha: null, source: "" };
+}
+
 async function handleReroot(
   meta: StackMetadata,
   newBase: string,
@@ -383,20 +413,25 @@ async function handleReroot(
   }
 
   // The rebase base = the tip the root was built on (the old base branch).
-  // Prefer the live branch tip; fall back to merge-base if it's already gone.
-  let oldBaseTip: string | null = null;
-  let oldBaseSource = "old-base branch tip";
-  if (await git.localBranchExists(oldBase)) {
-    oldBaseTip = await git.revParse(oldBase);
-  } else {
-    oldBaseTip = await git.mergeBase(root, newBase);
-    oldBaseSource = "merge-base (old base branch is gone — verify the result)";
-  }
+  // Getting this right matters: rebasing from the wrong boundary replays the
+  // old base's commits onto the new base, and when the old base was a
+  // squash-merged parent stack those commits collide with their own squashed
+  // result on main — a self-inflicted conflict storm (issue #13). So we never
+  // guess with merge-base; we refuse instead.
+  const { sha: oldBaseTip, source: oldBaseSource } = await resolveRerootBoundary(
+    meta,
+    oldBase,
+    root,
+  );
 
   if (!oldBaseTip) {
     p.cancel(
-      `Could not determine the old base for ${pc.yellow(root)}.\n\n  Re-root manually with: ${pc.green(
-        `git rebase --onto ${newBase} <old-base> ${root}`,
+      `Can't safely re-root ${pc.yellow(stackName)}: its old base ${pc.yellow(
+        oldBase,
+      )} is gone (or was rewritten) and no snapshot recorded where ${pc.yellow(
+        root,
+      )} forked off it.\n\n  Rebasing from the merge-base would replay already-merged commits and conflict.\n  Re-root manually once you know the old base tip:\n    ${pc.green(
+        `git rebase --onto ${newBase} <old-base-tip> ${root}`,
       )}`,
     );
     process.exit(1);
@@ -514,49 +549,45 @@ 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 AND is still an
-    //        ancestor of the child. 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).
-    //
-    //   The child-ancestry check (issue #5) prevents stale snapshots from
-    //   older sessions — where the child has already been rebased past the
-    //   recorded point — from being used as a rebase base.
+    // Resolve the rebase boundary — snapshot pre-rewrite tip, a fork point
+    // derived from a rejected snapshot (#30), or merge-base, in that order.
+    // See resolveRestackBoundary for the full strategy.
     //
     //   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, branch);
-    const oldBaseFromMergeBase = await git.mergeBase(branch, parent);
-    const oldBase = oldBaseFromSnapshot ?? oldBaseFromMergeBase;
+    const boundary = await resolveRestackBoundary(freshMeta, parent, branch);
 
     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)"}`,
+        `  ${pc.cyan("Boundary:")} ${boundary ? `${boundary.sha.slice(0, 8)} (${boundary.source})` : "(none)"}`,
       );
-      if (
-        oldBaseFromSnapshot &&
-        oldBaseFromMergeBase &&
-        oldBaseFromSnapshot !== oldBaseFromMergeBase
-      ) {
+      if (boundary && boundary.source !== "merge-base") {
         console.log(
-          `  ${pc.yellow("⚠ Parent was rewritten")} — using snapshot base (would have replayed parent commits otherwise)`,
+          `  ${pc.yellow("⚠ Parent was rewritten")} — merge-base alone would have replayed parent commits`,
         );
       }
       console.log();
     }
 
+    if (!boundary) {
+      // No snapshot evidence and no common history — any base would be a
+      // guess, and a wrong guess replays the parent's history onto itself.
+      // Refuse with the manual command, consistent with the --onto reroot
+      // path. (#30: never silently guess when we can't derive the boundary.)
+      p.log.error(
+        `Cannot determine a safe rebase base for ${pc.yellow(branch)} onto ${pc.yellow(parent)}.`,
+      );
+      console.log();
+      console.log("  Rebase it manually with an explicit boundary:");
+      console.log(`    ${pc.green(`git rebase --onto ${parent} <old-parent-tip> ${branch}`)}`);
+      console.log();
+      console.log(`  Then re-run ${pc.green("gh-stack restack")} to continue the chain.`);
+      process.exit(1);
+    }
+
     // Checkout the branch
     p.log.info(`Checking out ${pc.yellow(branch)}...`);
     await git.checkout(branch);
@@ -569,21 +600,28 @@ async function processChain(
     });
 
     let success: boolean;
-    if (oldBase) {
-      const sourceLabel = oldBaseFromSnapshot ? "snapshot" : "merge-base";
+    const branchTip = await git.revParse(branch);
+    if (boundary.sha === branchTip) {
+      // The child has no commits of its own (a placeholder branch created off
+      // the parent before any work landed). Nothing to replay — move the ref
+      // instead of invoking rebase. (#30)
+      p.log.info(
+        `${pc.yellow(branch)} has no unique commits — moving it to ${pc.yellow(parent)}'s tip`,
+      );
+      success = await git.resetHard(parent);
+    } else {
+      const sourceLabel =
+        boundary.source === "snapshot-derived" ? "snapshot (derived fork-point)" : boundary.source;
       p.log.info(
-        `Rebasing onto ${pc.yellow(parent)} (base: ${oldBase.slice(0, 8)} from ${sourceLabel})`,
+        `Rebasing onto ${pc.yellow(parent)} (base: ${boundary.sha.slice(0, 8)} from ${sourceLabel})`,
       );
 
       if (verbose) {
-        const count = await git.commitCount(oldBase, branch);
+        const count = await git.commitCount(boundary.sha, branch);
         console.log(`  Moving ${count} commit(s)`);
       }
 
-      success = await git.rebaseOnto(parent, oldBase, branch);
-    } else {
-      p.log.warn("Could not determine rebase base — using simple rebase");
-      success = await git.rebase(parent);
+      success = await git.rebaseOnto(parent, boundary.sha, branch);
     }
 
     if (success) {

package/src/commands/sync.ts

@@ -146,7 +146,7 @@ with the base branch included.
 
   // 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.)
+  // need to find when restacking children. (See resolveRestackBoundary.)
   await takeSnapshot(meta, stackName, "sync");
 
   // Step 1: Rebase base branch onto main

package/src/lib/advance.ts

@@ -21,7 +21,7 @@ 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 { resolveRestackBoundary } from "./snapshot.ts";
 import { setPrBase } from "./github.ts";
 
 /** What a single bottom branch needs: an active squash-merge, or just advancing
@@ -109,21 +109,19 @@ function reviewReason(decision: string | null): string {
 
 /**
  * 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).
+ * landed on the trunk. Shares restack's resolver (snapshot pre-rewrite tip →
+ * derived fork point → merge-base; see resolveRestackBoundary) — the snapshot
+ * paths handle a merged branch that was itself rebased earlier in a
+ * multi-merge cascade, including a child that sat behind it (#30).
+ * Returns null if nothing 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);
+  const boundary = await resolveRestackBoundary(meta, mergedBranch, child);
+  return boundary?.sha ?? null;
 }
 
 /** Outcome of advancing a single new bottom onto the trunk. */

package/src/lib/git.ts

@@ -285,6 +285,15 @@ export async function rebaseOnto(
   return exitCode === 0;
 }
 
+/**
+ * Move the current branch's ref to `ref` (working tree included).
+ * Returns true if successful. Caller must have verified the tree is clean.
+ */
+export async function resetHard(ref: string): Promise<boolean> {
+  const { exitCode } = await $`git reset --hard ${ref}`.nothrow().quiet();
+  return exitCode === 0;
+}
+
 /**
  * Simple rebase onto a target.
  * Returns true if successful, false if conflicts occurred.

package/src/lib/snapshot.ts

@@ -7,80 +7,142 @@
 // stack's only record while a busy sibling stack churned (see issue #13).
 import type { StackMetadata, Snapshot } from "../types.ts";
 import * as git from "./git.ts";
-import { getOrderedBranches } from "./metadata.ts";
+import { getOrderedBranches, stackBase } from "./metadata.ts";
 import { snapshotsDir } from "./paths.ts";
 import { mkdir, readdir, unlink } from "node:fs/promises";
 
 const MAX_SNAPSHOTS_PER_STACK = 10;
 
+/** Where a resolved restack boundary came from. */
+export type BoundarySource = "snapshot" | "snapshot-derived" | "merge-base";
+
+export type RestackBoundary = { sha: string; source: BoundarySource };
+
 /**
- * Find the pre-rewrite SHA for a parent branch by walking snapshots newest-first.
+ * Resolve the rebase boundary for restacking `childBranch` onto
+ * `parentBranch`: the commit whose range `boundary..child` contains exactly
+ * the child's own commits, for `git rebase --onto <parent> <boundary> <child>`.
+ *
+ * Resolution order:
  *
- * Returns the SHA from the most recent snapshot whose recorded tip for
- * `parentBranch` is NOT an ancestor of the parent's current tip — meaning
- * that snapshot was taken before the parent's history got rewritten
- * (typically by `sync` rebasing it onto a new main).
+ * 1. `"snapshot"` (issue #2) — the most recent snapshot whose recorded tip for
+ *    the parent is no longer an ancestor of the parent's current tip: that
+ *    snapshot predates a rewrite of the parent (typically `sync` rebasing it
+ *    onto a new main), and its orphaned old tip is exactly where the child's
+ *    own commits start. The recorded tip must also still be an ancestor of the
+ *    child (issue #5) — a stale tip the child was already rebased past would
+ *    replay a wildly wrong range; those candidates are skipped, not used.
  *
- * That pre-rewrite SHA is the correct rebase base when restacking a child
- * onto this parent — `git rebase --onto <new-tip> <pre-rewrite-tip> <child>`
- * replays only the child's unique commits, never the parent's old history.
+ * 2. `"snapshot-derived"` (issue #30) — a snapshot proves the parent was
+ *    rewritten but its recorded tip is not an ancestor of the child, e.g. the
+ *    child sat BEHIND the parent at snapshot time (committed to the parent,
+ *    then synced, before the child got its first commit). The recorded tip
+ *    still pins the parent's pre-rewrite history, and the child forked
+ *    somewhere on it: `merge-base(child, recordedTip)` is that fork point.
+ *    Only used when it is a DESCENDANT of `merge-base(child, parent)` — the
+ *    higher boundary is always the safe one, since everything below it already
+ *    exists in the new base's history. (A stale #5-shaped snapshot derives a
+ *    fork point BELOW the current merge-base; using it would replay the
+ *    parent's commits, so the current merge-base wins there.)
  *
- * **Child validation (issue #5)**: When `childBranch` is provided, any candidate
- * SHA must also still be an ancestor of the child. If the child has already
- * been rebased past this point (e.g., a previous restack already moved it),
- * the recorded SHA is stale for this child and would cause `rebase --onto`
- * to replay a wildly wrong range. We skip those candidates and keep walking.
+ * 3. `"merge-base"` — `merge-base(child, parent)`, correct whenever the parent
+ *    has only had commits appended, never been rewritten.
  *
- * Returns null if no snapshots exist, no recorded tip qualifies, or every
- * snapshot's recorded tip is still an ancestor of the parent's current tip
- * (i.e., the parent has only had commits appended, never been rebased —
- * `merge-base` is still correct).
+ * Returns null when nothing resolves (no snapshot evidence and no common
+ * history) — the caller must refuse rather than guess.
+ *
+ * If the child branch doesn't exist locally, snapshot validation degrades to
+ * parent-only (the newest rewritten tip is accepted without the child check).
  */
-export async function findPreRewriteSha(
+export async function resolveRestackBoundary(
   meta: StackMetadata,
   parentBranch: string,
-  childBranch?: string,
-): Promise<string | null> {
-  if (!meta.snapshots || meta.snapshots.length === 0) return null;
-
-  let currentParentTip: string;
+  childBranch: string,
+): Promise<RestackBoundary | null> {
+  let currentParentTip: string | null = null;
   try {
     currentParentTip = await git.revParse(parentBranch);
   } catch {
-    return null;
+    currentParentTip = null;
   }
 
   let currentChildTip: string | null = null;
-  if (childBranch) {
-    try {
-      currentChildTip = await git.revParse(childBranch);
-    } catch {
-      // Child doesn't exist locally — fall back to parent-only validation
-      currentChildTip = null;
+  try {
+    currentChildTip = await git.revParse(childBranch);
+  } catch {
+    currentChildTip = null;
+  }
+
+  // Walk snapshots newest → oldest for evidence the parent was rewritten.
+  let accepted: string | null = null;
+  let rejected: string | null = null; // newest rewritten tip that failed the child check
+  if (currentParentTip && meta.snapshots) {
+    for (let i = meta.snapshots.length - 1; i >= 0; i--) {
+      const recorded = meta.snapshots[i]!.branches[parentBranch];
+      if (!recorded || recorded === currentParentTip) continue;
+      if (await git.isAncestor(recorded, currentParentTip)) continue; // appended-to, not rewritten
+      if (!currentChildTip || (await git.isAncestor(recorded, currentChildTip))) {
+        accepted = recorded;
+        break;
+      }
+      rejected ??= recorded;
     }
   }
 
-  // Walk newest → oldest
-  for (let i = meta.snapshots.length - 1; i >= 0; i--) {
-    const recorded = meta.snapshots[i]!.branches[parentBranch];
-    if (!recorded) continue;
-    if (recorded === currentParentTip) continue;
-
-    // The recorded SHA must no longer be an ancestor of the parent's current
-    // tip — that's how we detect the parent's history was rewritten.
-    const stillAncestorOfParent = await git.isAncestor(recorded, currentParentTip);
-    if (stillAncestorOfParent) continue;
-
-    // Issue #5 guard: if we know the child, the recorded SHA must still be
-    // an ancestor of the child. Otherwise the child has already been rebased
-    // past this point (or never branched off it) and using it as a base
-    // would replay unrelated history.
-    if (currentChildTip) {
-      const stillAncestorOfChild = await git.isAncestor(recorded, currentChildTip);
-      if (!stillAncestorOfChild) continue;
+  if (accepted) return { sha: accepted, source: "snapshot" };
+
+  const mbCurrent = await git.mergeBase(childBranch, parentBranch);
+
+  if (rejected && currentChildTip) {
+    const derived = await git.mergeBase(childBranch, rejected);
+    if (derived) {
+      if (!mbCurrent) return { sha: derived, source: "snapshot-derived" };
+      if (derived !== mbCurrent && (await git.isAncestor(mbCurrent, derived))) {
+        return { sha: derived, source: "snapshot-derived" };
+      }
     }
+  }
+
+  return mbCurrent ? { sha: mbCurrent, source: "merge-base" } : null;
+}
 
-    return recorded;
+/**
+ * Find the recorded tip of a stack's (non-main) base branch — the boundary a
+ * re-root needs to replay only the dependent stack's own commits.
+ *
+ * Walks snapshots newest-first for one whose recorded `baseBranch` matches and
+ * whose recorded `baseTip` is still an ancestor of `rootBranch` (the dependent
+ * stack's root). That tip is exactly where the root forked off the base, so
+ * `git rebase --onto <new-base> <baseTip> <root>` drops the already-merged
+ * prefix instead of replaying it.
+ *
+ * Unlike `resolveRestackBoundary`, this does NOT require the base branch to still
+ * exist locally — that's the whole point: after a squash-merge deletes the base
+ * branch, its tip survives only in these snapshots. The ancestor-of-root check
+ * rejects stale candidates (an older base tip the root no longer sits on).
+ *
+ * Returns null if no snapshot recorded this base, or none is still an ancestor
+ * of the root (in which case the caller must refuse rather than guess).
+ */
+export async function findRecordedBaseTip(
+  meta: StackMetadata,
+  baseBranch: string,
+  rootBranch: string,
+): Promise<string | null> {
+  if (!meta.snapshots || meta.snapshots.length === 0) return null;
+
+  let rootTip: string;
+  try {
+    rootTip = await git.revParse(rootBranch);
+  } catch {
+    return null;
+  }
+
+  // Walk newest → oldest; first base tip that the root still sits on wins.
+  for (let i = meta.snapshots.length - 1; i >= 0; i--) {
+    const snap = meta.snapshots[i]!;
+    if (snap.baseBranch !== baseBranch || !snap.baseTip) continue;
+    if (await git.isAncestor(snap.baseTip, rootTip)) return snap.baseTip;
   }
 
   return null;
@@ -161,6 +223,20 @@ export async function takeSnapshot(
     stack: stackName,
   };
 
+  // For a non-main base (a stack stacked on top of another stack), record the
+  // base branch's tip too — kept out of `branches` so `undo` won't reset a
+  // branch that belongs to the parent stack. This is the boundary a later
+  // re-root needs if the base branch is deleted by a squash-merge (issue #13).
+  const base = stackBase(stack);
+  if (base !== "main" && base !== "master") {
+    try {
+      snapshot.baseTip = await git.revParse(base);
+      snapshot.baseBranch = base;
+    } catch {
+      // Base branch already gone locally — nothing to record.
+    }
+  }
+
   await writeSnapshotFile(snapshot);
 
   // Keep in-memory array consistent for callers that read it afterward.

package/src/types.ts

@@ -50,6 +50,13 @@ export interface Snapshot {
   operation: string; // "restack" | "merge" | "sync" | "remove"
   branches: Record<string, string>; // branch name -> commit SHA
   stack?: string; // owning stack (v3: drives per-stack retention + file naming)
+  // For a stack with a non-main base: the base branch and its tip at snapshot
+  // time. Recorded separately from `branches` (which `undo` force-resets) so a
+  // dependent stack can re-root onto main after its base branch is deleted by a
+  // squash-merge — without that recorded boundary the reroot would replay the
+  // already-merged commits and conflict (issue #13).
+  baseBranch?: string;
+  baseTip?: string;
 }
 
 // Resume state for restack --resume