gh-stack 0.19.1 → 0.19.3

package/README.md

@@ -262,11 +262,14 @@ sync [--dry-run] [--no-push|--push] [--resume | --fresh] [--overwrite-remote]
     Fetch main, rebase the base branch onto main, push it, then restack
     all children (every branch above it, in one resumable run). 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.
+    If the bottom PR(s) already merged outside gh-stack (e.g. the GitHub
+    web UI, or the base of a `merge --approved` landing with the PRs
+    collapsed into it), sync detects this and advances the stack past
+    them: it drops every merged branch and re-roots only the first
+    unmerged one onto main with `--onto`, so only its own commits replay,
+    instead of replaying the now-squashed commits and conflicting. It
+    warns about a merged PR whose changes never reached main (merged
+    into a branch after that branch's own PR had landed).
 
     --no-push / --push (and their defaults): as for restack. Also skips
     retargeting a PR's base after advancing past a merged bottom;
@@ -323,7 +326,8 @@ merge --base [--dry-run] [-d|--delete-branch] [--no-push|--push]
                 just its own commits). One PR per run — run it again to
                 land the next. Approval is enforced by GitHub branch
                 protection, not gh-stack. A base PR already merged outside
-                gh-stack is detected and advanced past. The re-root waits
+                gh-stack is detected and advanced past, along with
+                PRs already collapsed into it. The re-root waits
                 until origin's main shows the merge commit, and stops (exit
                 2) if it never does. When a re-root stops (a conflict, or
                 main not showing the merge yet), finish it by re-running

package/package.json

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

package/src/commands/merge.ts

@@ -423,11 +423,11 @@ OPTIONS
           : "Single branch stack — enabling auto-merge on GitHub.",
       );
       if (!dryRun) {
-        try {
-          await $`gh pr merge ${basePr} --squash --auto`.quiet();
+        const auto = await $`gh pr merge ${basePr} --squash --auto`.nothrow().quiet();
+        if (auto.exitCode === 0) {
           p.log.success(`Auto-merge enabled for PR #${basePr}`);
-        } catch {
-          p.log.info(`Enable manually: ${pc.dim(`gh pr merge ${basePr} --squash --auto`)}`);
+        } else {
+          autoMergeFallback(basePr, auto.stderr.toString());
         }
       }
     } else {
@@ -721,6 +721,7 @@ OPTIONS
 
   // 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.
+  let autoMerging = true;
   if (verdict === "merged") {
     autoSpinner.stop(`PR #${basePr} already merged into main`);
   } else {
@@ -740,7 +741,8 @@ OPTIONS
     } 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`)}`);
+      autoMergeFallback(basePr!, auto.stderr);
+      autoMerging = false;
     }
   }
 
@@ -764,7 +766,7 @@ OPTIONS
   if (tail.length > 0) {
     p.outro(
       pc.green(
-        `Approved run collapsed into PR #${basePr} → auto-merging to main. ` +
+        `Approved run collapsed into PR #${basePr}${autoMerging ? " → auto-merging to main" : ""}. ` +
           `After it lands, run \`gh-stack sync\` to re-root the ${tail.length} remaining branch(es).`,
       ),
     );
@@ -960,6 +962,36 @@ async function collapsedChildren(
   return { collapsed, unknown: null };
 }
 
+/**
+ * What to do when `gh pr merge --auto` failed. A repo that doesn't allow
+ * auto-merge fails the same way every time, so don't suggest retrying it (#54).
+ */
+function autoMergeFallback(prNumber: number, stderr: string): void {
+  if (/auto.?merge is not allowed/i.test(stderr)) {
+    p.log.info(
+      `This repo doesn't allow auto-merge. Merge PR #${prNumber} once its checks pass: ${pc.dim(`gh pr merge ${prNumber} --squash`)}`,
+    );
+  } else {
+    p.log.info(`Enable manually: ${pc.dim(`gh pr merge ${prNumber} --squash --auto`)}`);
+  }
+}
+
+/**
+ * The branches right above the base (`ordered[0]`) whose PRs already merged,
+ * bottom-up, stopping at the first that hasn't: PRs collapsed into the base,
+ * or landed on their own. A PR that can't be read stops the run, so it's
+ * re-rooted rather than dropped on a guess.
+ */
+async function mergedRunAbove(stack: Stack, ordered: string[]): Promise<string[]> {
+  const run: string[] = [];
+  for (const branch of ordered.slice(1)) {
+    const pr = stack.branches[branch]?.pr;
+    if (pr == null || (await getPrMergeState(pr))?.state !== "MERGED") break;
+    run.push(branch);
+  }
+  return run;
+}
+
 /**
  * Fetch the trunk and confirm it holds PR `prNumber`'s merge commit (#51).
  * The re-root rebases onto `origin/<trunk>`; a trunk fetched before the squash
@@ -1071,7 +1103,11 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
   const baseState = await getPrMergeState(basePr);
   const baseAction: MergeAction = baseState?.state === "MERGED" ? "advance-only" : "merge";
   const plan = { steps: [{ branch: baseBranch, pr: basePr, action: baseAction }] };
-  const nextChild = ordered[1] ?? null;
+  // PRs already merged above the base (collapsed into it, or landed on their
+  // own) go with it: dropped, never re-rooted, since replaying their commits
+  // onto a trunk that holds them squashed conflicts (#54).
+  const mergedAbove = await mergedRunAbove(stack, ordered);
+  const nextChild = ordered[1 + mergedAbove.length] ?? null;
 
   console.log();
   console.log(`  ${pc.bold("Plan:")}`);
@@ -1082,6 +1118,11 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
         : `${pc.green("squash-merge")} → ${pc.green(trunk)}`
     }`,
   );
+  if (mergedAbove.length > 0) {
+    console.log(
+      `    ${pc.dim(`drop ${mergedAbove.join(", ")} (already merged into the branch below)`)}`,
+    );
+  }
   if (nextChild) {
     console.log(
       `    ${pc.dim(`then re-root ${nextChild} onto ${trunk} — the rest stays a stack`)}`,
@@ -1151,7 +1192,7 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
   const overwrite = args.includes("--overwrite-remote");
   const verified = await guardRemoteContent(
     meta,
-    ordered.slice(1).filter((b) => !collapsed.includes(b)),
+    ordered.slice(1).filter((b) => !collapsed.includes(b) && !mergedAbove.includes(b)),
     { command: "merge --base", overwrite, dryRun: false },
   );
 
@@ -1164,7 +1205,7 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
   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 child = nextChild;
     const childPr = child ? (stack.branches[child]?.pr ?? null) : null;
 
     console.log();
@@ -1232,10 +1273,13 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
         process.exit(2);
       }
 
+      // The child sits on the last branch of the merged run.
+      const mergedParent = stack.branches[child]!.parent;
       const res = await advanceNewBottom({
         meta,
         stackName,
-        mergedBranch,
+        mergedBranch: mergedParent,
+        alsoMerged: [mergedBranch, ...mergedAbove].filter((b) => b !== mergedParent),
         child,
         childPr,
         targetRef,
@@ -1267,8 +1311,10 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
         process.exit(2);
       }
     } else {
-      // The merged branch was the top — nothing rides above it. Just drop it.
-      await removeBranchFromStack(meta, stackName, mergedBranch);
+      // Nothing unmerged rides above it. Just drop the merged run.
+      for (const branch of [mergedBranch, ...mergedAbove]) {
+        await removeBranchFromStack(meta, stackName, branch);
+      }
     }
   }
 

package/src/commands/sync.ts

@@ -14,8 +14,16 @@ import { ensureMetadata, ensureCleanWorkingTree, ensureValidStack } from "../lib
 import { resolveFlag } from "../lib/config.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { guardRemoteContent } from "../lib/remote-guard.ts";
-import { getPrInfo } from "../lib/github.ts";
-import { planMerges, advanceNewBottom, type BranchReview, type MergePlan } from "../lib/advance.ts";
+import { getPrMergeState } from "../lib/github.ts";
+import {
+  planMerges,
+  advanceNewBottom,
+  strandedMerges,
+  type BranchReview,
+  type MergePlan,
+  type MergedRunEntry,
+  type StrandedMerge,
+} from "../lib/advance.ts";
 import type { StackMetadata } from "../types.ts";
 import restack, {
   notePendingRun,
@@ -117,7 +125,7 @@ adds on GitHub). Pull or cherry-pick them first; see \`gh-stack restack --help\`
   // Bottoms whose PRs already merged are skipped: the advance drops them
   // rather than rewriting them, and after `merge --approved` they're exactly
   // where the collapse's squash commits live.
-  const mergedBranches = new Set(merged.steps.map((step) => step.branch));
+  const mergedBranches = new Set(merged.plan.steps.map((step) => step.branch));
   const verified = await guardRemoteContent(
     meta,
     ordered.filter((b) => !mergedBranches.has(b)),
@@ -251,60 +259,83 @@ interface AdvanceOutcome {
   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.
- */
+/** The contiguous merged bottom branches, and how each one's PR merged. */
+interface MergedBottoms {
+  plan: MergePlan;
+  run: MergedRunEntry[];
+}
+
 /**
  * The contiguous bottom branches whose PRs already merged (outside gh-stack,
- * or the base of a `merge --approved`), walking bottom-up and stopping at the
- * first that isn't.
+ * or the base of a `merge --approved` and the PRs collapsed into it), walking
+ * bottom-up and stopping at the first that isn't.
  */
-async function findMergedBottoms(meta: StackMetadata, stackName: string): Promise<MergePlan> {
+async function findMergedBottoms(meta: StackMetadata, stackName: string): Promise<MergedBottoms> {
   const stack = meta.stacks[stackName]!;
   const reviews: BranchReview[] = [];
+  const run: MergedRunEntry[] = [];
   for (const branch of getOrderedBranches(stack)) {
     const pr = stack.branches[branch]?.pr ?? null;
-    let prState: string | null = null;
-    if (pr != null) {
-      const info = await getPrInfo(pr);
-      prState = info?.state ?? null;
-    }
+    const state = pr != null ? await getPrMergeState(pr) : null;
+    const prState = state?.state ?? null;
     reviews.push({ branch, pr, prState, reviewDecision: null });
     if (prState !== "MERGED") break;
+    run.push({
+      branch,
+      parent: stack.branches[branch]!.parent,
+      pr,
+      baseRefName: state?.baseRefName ?? null,
+      mergedAt: state?.mergedAt ?? null,
+    });
   }
-  return planMerges(reviews, { approveAndMerge: false });
+  return { plan: planMerges(reviews, { approveAndMerge: false }), run };
 }
 
+/**
+ * Advance the stack past bottom PR(s) that already merged: drop them all and
+ * re-root the first unmerged branch onto the trunk with `--onto`, from its
+ * merged parent's pre-merge tip, so only its own commits replay. The merged
+ * branches themselves are never re-rooted: their commits are already on the
+ * trunk, squashed, and replaying them conflicts (#54). Shares the re-root
+ * mechanics with `merge` (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,
   noPush: boolean,
-  plan: MergePlan,
+  merged: MergedBottoms,
   verified: Map<string, string>,
 ): Promise<AdvanceOutcome> {
   const stack = meta.stacks[stackName]!;
   const ordered = getOrderedBranches(stack);
+  const { plan, run } = merged;
 
   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:`);
+  const mergedBranches = plan.steps.map((step) => step.branch);
+  // The first unmerged branch. Ordered parents-first, so its parent is in the run.
+  const survivor = ordered[mergedBranches.length] ?? null;
+
+  p.log.warn(`${plan.steps.length} bottom PR(s) already merged:`);
   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.`)}`,
+    `  ${pc.dim(
+      survivor
+        ? `Dropping them and re-rooting ${survivor} onto ${trunk}, so only its own commits replay.`
+        : `Dropping them: nothing is left above them.`,
+    )}`,
   );
   console.log();
+  warnStranded(strandedMerges(run, trunk), trunk);
 
   if (dryRun) {
     p.log.warn("[DRY RUN] Would advance the stack past the merged bottom PR(s)");
@@ -316,45 +347,41 @@ async function advanceMergedBottoms(
   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,
-        push: !noPush,
-        expect: verified.get(child),
-      });
-      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 sync:`);
-          console.log(`    ${pc.green("git rebase --continue")}`);
-          console.log(
-            `    ${pc.green("gh-stack sync")}   ${pc.dim(`(picks up the re-rooted ${child}; not restack, which would put it back on ${mergedBranch})`)}`,
-          );
-        } 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);
+  if (survivor) {
+    const mergedParent = stack.branches[survivor]!.parent;
+    const res = await advanceNewBottom({
+      meta,
+      stackName,
+      mergedBranch: mergedParent,
+      alsoMerged: mergedBranches.filter((b) => b !== mergedParent),
+      child: survivor,
+      childPr: stack.branches[survivor]?.pr ?? null,
+      targetRef,
+      recordedBase: trunk,
+      push: !noPush,
+      expect: verified.get(survivor),
+    });
+    if (!res.ok) {
+      console.log();
+      if (res.reason === "conflict") {
+        p.log.error(`Rebase conflict re-rooting ${pc.yellow(survivor)} onto ${trunk}.`);
+        console.log(`  Resolve it, then finish the sync:`);
+        console.log(`    ${pc.green("git rebase --continue")}`);
+        console.log(
+          `    ${pc.green("gh-stack sync")}   ${pc.dim(`(picks up the re-rooted ${survivor}; not restack, which would put it back on ${mergedParent})`)}`,
+        );
+      } else {
+        p.log.error(
+          `Could not determine a safe rebase base for ${pc.yellow(survivor)} (${res.reason}).`,
+        );
+        console.log(
+          `  Re-root manually:\n    ${pc.green(`git rebase --onto ${targetRef} <${mergedParent}'s pre-merge tip> ${survivor}`)}`,
+        );
       }
-    } else {
-      await removeBranchFromStack(meta, stackName, mergedBranch);
+      process.exit(2);
     }
+  } else {
+    for (const branch of mergedBranches) await removeBranchFromStack(meta, stackName, branch);
   }
 
   // Whole stack drained? Archive the original topology and land on the trunk.
@@ -376,3 +403,25 @@ async function advanceMergedBottoms(
 
   return { detected: true, advanced: true, drained: false };
 }
+
+/**
+ * Say which merged PRs' changes never reached the trunk. The advance drops
+ * their branches either way (re-rooting one would replay its commits onto a
+ * trunk they were never squashed into, under the wrong PR), so the user has
+ * to land those changes again themselves.
+ */
+function warnStranded(stranded: StrandedMerge[], trunk: string): void {
+  if (stranded.length === 0) return;
+  for (const s of stranded) {
+    const pr = s.pr != null ? `PR #${s.pr}` : pc.yellow(s.branch);
+    p.log.warn(
+      s.landedPr != null
+        ? `${pr} merged into ${s.into} after PR #${s.landedPr} had landed, so its changes never reached ${trunk}.`
+        : `${pr} merged into ${s.into}, which isn't ${trunk} or a branch below it, so its changes may not be on ${trunk}.`,
+    );
+  }
+  console.log(
+    `  ${pc.dim(`Sync drops them from the stack anyway. To ship those changes, open a new PR for them against ${trunk}.`)}`,
+  );
+  console.log();
+}

package/src/lib/advance.ts

@@ -94,6 +94,53 @@ export function planMerges(ordered: BranchReview[], opts: { approveAndMerge: boo
   return { steps, stop: null };
 }
 
+/** One branch of a contiguous merged run, with how its PR merged. */
+export interface MergedRunEntry {
+  branch: string;
+  /** Its stack parent. */
+  parent: string;
+  pr: number | null;
+  /** The branch its PR merged into. */
+  baseRefName: string | null;
+  mergedAt: string | null;
+}
+
+/** A merged PR whose changes never reached the trunk. */
+export interface StrandedMerge {
+  branch: string;
+  pr: number | null;
+  into: string;
+  /** The PR of the branch it merged into, which had already landed; null when that branch isn't in the run. */
+  landedPr: number | null;
+}
+
+/**
+ * The merged PRs in `run` (bottom-up) whose changes never reached `trunk`.
+ * Advancing past a merged run drops its branches without replaying them, which
+ * is only right if each one's changes are on the trunk: merged into the trunk,
+ * or into a branch of the run before that branch's own PR merged (a collapse).
+ * One merged into its parent after the parent landed, or into a branch outside
+ * the run, is stranded. Missing facts never claim stranded.
+ */
+export function strandedMerges(run: MergedRunEntry[], trunk: string): StrandedMerge[] {
+  const byBranch = new Map(run.map((entry) => [entry.branch, entry]));
+  const stranded: StrandedMerge[] = [];
+  for (const entry of run) {
+    const into = entry.baseRefName;
+    if (!into || into === trunk) continue;
+    const container = byBranch.get(into);
+    if (!container) {
+      stranded.push({ branch: entry.branch, pr: entry.pr, into, landedPr: null });
+      continue;
+    }
+    if (!entry.mergedAt || !container.mergedAt) continue;
+    if (Date.parse(entry.mergedAt) > Date.parse(container.mergedAt)) {
+      stranded.push({ branch: entry.branch, pr: entry.pr, into, landedPr: container.pr });
+    }
+  }
+  return stranded;
+}
+
 function reviewReason(decision: string | null): string {
   switch (decision) {
     case "CHANGES_REQUESTED":
@@ -142,9 +189,10 @@ export type AdvanceResult =
 
 /**
  * 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`.
+ * dropping `mergedBranch`'s now-squashed commits, then drop `mergedBranch` (and
+ * `alsoMerged`) 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`.
@@ -155,7 +203,13 @@ export type AdvanceResult =
 export async function advanceNewBottom(opts: {
   meta: StackMetadata;
   stackName: string;
+  /** The merged branch `child` sits on: its pre-merge tip is the fork point. */
   mergedBranch: string;
+  /**
+   * The rest of a merged run below `mergedBranch` (#54). Their commits are in
+   * the trunk too, so they're dropped without being re-rooted themselves.
+   */
+  alsoMerged?: string[];
   child: string;
   childPr: number | null;
   targetRef: string;
@@ -227,10 +281,12 @@ export async function advanceNewBottom(opts: {
     );
   }
 
-  // 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
+  // Metadata last: drop the merged run, which re-parents child (and siblings)
+  // onto the trunk, and write. Done after the git work succeeds so a failure
   // never leaves metadata describing a state git didn't reach.
-  await removeBranchFromStack(meta, stackName, mergedBranch);
+  for (const merged of [...(opts.alsoMerged ?? []), mergedBranch]) {
+    await removeBranchFromStack(meta, stackName, merged);
+  }
 
   // Record where the child's PR really points. Until it's retargeted it still
   // targets the merged branch, and the next successful push of the child

package/src/lib/github.ts

@@ -215,16 +215,18 @@ export interface PrMergeResult {
   baseRefName: string;
   /** The commit merging it created on its base (for a squash merge, the squash commit). */
   mergeCommit: string | null;
+  /** When it merged (ISO 8601); null if it hasn't. */
+  mergedAt: string | null;
 }
 
 export async function getPrMergeState(prNumber: number): Promise<PrMergeResult | null> {
   try {
     const data = JSON.parse(
       (
-        await $`gh pr view ${prNumber} --json state,mergeable,mergeStateStatus,headRefName,headRefOid,baseRefName,mergeCommit`.text()
+        await $`gh pr view ${prNumber} --json state,mergeable,mergeStateStatus,headRefName,headRefOid,baseRefName,mergeCommit,mergedAt`.text()
       ).trim(),
     );
-    return { ...data, mergeCommit: data.mergeCommit?.oid ?? null };
+    return { ...data, mergeCommit: data.mergeCommit?.oid ?? null, mergedAt: data.mergedAt || null };
   } catch {
     return null;
   }

package/src/lib/using-gh-stack.md

@@ -303,9 +303,11 @@ often the squash commit a `merge --collapse` added on GitHub. Run the
 pass `--overwrite-remote` unless you were asked to drop those commits: it
 deletes them from the PR.
 
-**`sync` is self-correcting:** if you merged the bottom PR in the GitHub UI,
-`sync` detects it and advances the stack past the merged branch (re-rooting onto
-trunk) instead of replaying squashed commits and conflicting.
+**`sync` is self-correcting:** if you merged the bottom PR in the GitHub UI, or
+the base of a `merge --approved` landed with the PRs collapsed into it, `sync`
+detects it, drops every merged branch, and re-roots only the first unmerged one
+onto trunk instead of replaying squashed commits and conflicting. It rebases
+onto `origin/main` (fetched itself), so a stale local `main` doesn't matter.
 
 ### 5. Status
 
@@ -332,7 +334,9 @@ Merge is **top-down everywhere** (collapse PRn → PRn-1 → … → base PR, th
   one commit on trunk. Approval is read from the base up — the first un-approved
   PR caps the run (unapproved PR4 stops at PR3 even if PR5 is approved). The
   unapproved tail is left in place; after the base lands, run `gh-stack sync` to
-  re-root the tail onto trunk (it does not block on CI).
+  re-root the tail onto trunk (it does not block on CI). If the repo doesn't
+  allow auto-merge, merge the base PR yourself once its checks pass
+  (`gh pr merge <N> --squash`), then `gh-stack sync`.
 - **`merge --base`**: squash-merge **only the bottom PR** into trunk and re-root
   the next branch onto trunk — one PR per run, re-run for the next. Use this to
   land reviewed PRs one at a time. Auto-advances past a bottom PR already merged