gh-stack 0.19.5 → 0.19.7

package/README.md

@@ -24,12 +24,12 @@ bun install -g gh-stack
 
 ## Terms
 
-| Term | Definition |
-|------|-----------|
-| **trunk** | Base branch of the repository (usually `main`) |
-| **stack** | A chain of dependent branches |
-| **upstack** | Branches that depend on the current branch (children) |
-| **downstack** | Branches the current branch depends on (ancestors) |
+| Term          | Definition                                            |
+| ------------- | ----------------------------------------------------- |
+| **trunk**     | Base branch of the repository (usually `main`)        |
+| **stack**     | A chain of dependent branches                         |
+| **upstack**   | Branches that depend on the current branch (children) |
+| **downstack** | Branches the current branch depends on (ancestors)    |
 
 ## Quick Start
 
@@ -92,6 +92,9 @@ add [branch] [--parent <branch>]
     stack — without pushing or opening a PR. Walks local ancestry: if the
     branch sits on top of an existing stack it's adopted into it (parent
     auto-detected); otherwise a new stack is created from the chain.
+    A PR that gh-stack already recorded for a branch in git config (in
+    another worktree of the repo) is kept, so a stack submitted from a
+    worktree can be tracked in the main checkout and merged from there.
 
     --parent <branch>: stack it directly on <branch> (which it must
     already be based on), tracking <branch> first if needed. Use this
@@ -265,9 +268,11 @@ sync [--dry-run] [--no-push|--push] [--resume | --fresh] [--overwrite-remote]
     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
+    them: it drops every merged branch and re-roots each unmerged branch
+    sitting on them onto main with `--onto`, so only their own commits
+    replay, instead of replaying the now-squashed commits and conflicting.
+    When a merged branch had several children, each child (with the
+    branches above it) becomes its own stack and is synced in turn. It
     warns about a merged PR whose changes never reached main (merged
     into a branch after that branch's own PR had landed).
 
@@ -323,8 +328,9 @@ merge --base [--dry-run] [-d|--delete-branch] [--no-push|--push]
                 full merge.
     --base      Squash-merge ONLY the bottom PR into main as its own
                 commit, then re-root the next branch onto main (replaying
-                just its own commits). One PR per run — run it again to
-                land the next. Approval is enforced by GitHub branch
+                just its own commits). If the bottom PR has several
+                children, each is re-rooted and becomes its own stack.
+                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, along with
                 PRs already collapsed into it. The re-root waits
@@ -430,7 +436,8 @@ delete [<branch>] [-k|--keep-branch] [--no-remote]
     delete the underlying local git branch (and the remote branch if
     it was pushed). The <branch> argument names its own stack, so this
     works from anywhere. Interactive selector (current stack) if none
-    specified.
+    specified. Deleting a stack's root that has several children leaves
+    them side by side on the base, so each becomes its own stack.
     --keep-branch leaves the git branches untouched (metadata only);
     --no-remote deletes the local branch but keeps the remote.
 ```
@@ -487,9 +494,12 @@ config [--json]
     only). Read-only; edit the TOML files directly.
 
 doctor
-    Migrate old (v2) metadata to the v3 layout, reconcile git branch
-    config against the topology files, and flag stacks whose base
-    stack appears already-merged into main. Safe to run repeatedly.
+    Migrate old (v2) metadata to the v3 layout, split any stack left
+    with several root branches into one stack per root, reconcile git
+    branch config against the topology files, flag stacks whose base
+    stack appears already-merged into main, and report stacks that
+    still fail the checks other commands run before loading a stack.
+    Safe to run repeatedly.
 
 learn [--skill] [--harness <name>] [--global] [--force]
     Teach a coding agent how to drive gh-stack. By default prints the
@@ -550,10 +560,10 @@ remember to type them:
 # .gh-stack.toml at the repo root (commit it), or
 # ~/.config/gh-stack/config.toml for personal defaults (honors XDG_CONFIG_HOME)
 [submit]
-draft = true      # new PRs open as drafts; --no-draft overrides for one PR
+draft = true # new PRs open as drafts; --no-draft overrides for one PR
 
 [restack]
-push = false      # restack and sync stay local; --push overrides
+push = false # restack and sync stay local; --push overrides
 ```
 
 Precedence, highest first: **CLI flag > env var > repo config > user config >
@@ -667,7 +677,7 @@ A single `active/<stack>.json` looks like:
 }
 ```
 
-Per-branch membership is *also* recorded in git's own config, so renaming or
+Per-branch membership is _also_ recorded in git's own config, so renaming or
 deleting a branch updates/cleans it automatically:
 
 ```

package/package.json

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

package/src/commands/add.ts

@@ -38,7 +38,8 @@ OPTIONS
                      its stack and has no PR (e.g. a mistaken ${"`"}init${"`"} at trunk).
 
 Network-free — nothing is pushed and no PR is opened. Run ${"`"}gh-stack submit${"`"} when
-you're ready to publish.
+you're ready to publish. A PR already recorded for the branch in git config
+(by gh-stack in another worktree of this repo) is kept.
 
 EXAMPLES
   gh-stack add                    Track the current branch

package/src/commands/delete.ts

@@ -1,7 +1,7 @@
 // gh-stack delete — Delete a branch from the stack (re-link parent chain)
 import * as p from "../lib/output.ts";
 import pc from "picocolors";
-import { removeBranchFromStack, getChildren } from "../lib/metadata.ts";
+import { removeBranchFromStack, getChildren, stackBase } from "../lib/metadata.ts";
 import {
   ensureMetadata,
   ensureCurrentStack,
@@ -24,6 +24,9 @@ Removes the branch from the stack and deletes the underlying git branch,
 re-parenting any children to the removed branch's parent. If the deleted
 branch was pushed, its remote counterpart is deleted too.
 
+Deleting a stack's root that has several children leaves them side by side on
+the base, so each child (with the branches above it) becomes its own stack.
+
 If no branch is specified, shows an interactive selector.
 
 OPTIONS
@@ -84,6 +87,13 @@ OPTIONS
     for (const child of children) {
       console.log(`    ${pc.dim("→")} ${child}`);
     }
+    if (children.length > 1 && branch.parent === stackBase(stack)) {
+      p.log.info(
+        pc.dim(
+          `They'll sit side by side on ${branch.parent}, so each becomes its own stack (${children[0]} keeps ${stackName}).`,
+        ),
+      );
+    }
   }
 
   if (keepBranch) {
@@ -116,8 +126,13 @@ OPTIONS
     p.log.info(`Switched to ${pc.blue(fallback)} (was on the deleted branch)`);
   }
 
-  // Remove from metadata (re-parents children, fixes last_branch)
-  await removeBranchFromStack(meta, stackName, branchName);
+  // Remove from metadata (re-parents children, fixes last_branch, splits siblings)
+  const split = await removeBranchFromStack(meta, stackName, branchName);
+  if (split.length > 0) {
+    p.log.success(
+      `Split off ${split.map((s) => pc.yellow(s)).join(", ")} beside ${pc.blue(stackName)}`,
+    );
+  }
 
   // Delete the actual git branch(es)
   if (hasRemote) {

package/src/commands/doctor.ts

@@ -11,7 +11,10 @@ import {
   v3Exists,
   legacyMetadataExists,
   stackBase,
+  stackRoots,
+  splitMultiRootStack,
 } from "../lib/metadata.ts";
+import { validateStack } from "../lib/safety.ts";
 import { legacyMetadataPath, legacyRestackStatePath, restackStateFile } from "../lib/paths.ts";
 import { writeSnapshotFile } from "../lib/snapshot.ts";
 import { allBranchMemberships } from "../lib/branch-config.ts";
@@ -23,9 +26,11 @@ USAGE
   gh-stack doctor
 
 Migrates old (v2) metadata to the v3 layout (per-stack files under
-.git/.gh-stack/ + git branch config), then reconciles branch config
-against the topology files and flags stacks whose base stack looks
-already-merged into main.
+.git/.gh-stack/ + git branch config), splits any stack left with several
+root branches into one stack per root, reconciles branch config against
+the topology files, flags stacks whose base stack looks already-merged
+into main, and reports stacks that still fail the checks other commands
+run before they load a stack.
 
 Safe to run repeatedly — it's idempotent.
 `;
@@ -54,19 +59,59 @@ export default async function doctor(args: string[]): Promise<void> {
     process.exit(1);
   }
 
-  // ── 2. Reconcile branch config ↔ topology ──
+  // ── 2. Split stacks left with several roots (#60) ──
+  splitMultiRootStacks(meta);
+
+  // ── 3. Reconcile branch config ↔ topology (also writes the split) ──
   await reconcile(meta);
 
-  // ── 3. Flag base-stack-merged situations (issue #13) ──
+  // ── 4. Flag base-stack-merged situations (issue #13) ──
   await flagMergedBaseStacks(meta);
 
-  if (migrated) {
+  // ── 5. Run the checks every command runs before it loads a stack ──
+  const invalid = await reportInvalidStacks(meta);
+
+  if (invalid > 0) {
+    p.outro(pc.yellow(`${invalid} stack(s) still need repair (see above).`));
+  } else if (migrated) {
     p.outro(pc.green("Migration complete — metadata is now v3."));
   } else {
     p.outro(pc.green("Metadata looks healthy."));
   }
 }
 
+// ── Multi-root repair (#60) ──
+
+/**
+ * A stack whose root left with several children has several roots, which every
+ * command refuses. Siblings on the same base are independent stacks, so give
+ * each its own: lossless, and only metadata changes. The caller writes.
+ */
+function splitMultiRootStacks(meta: StackMetadata): void {
+  for (const name of Object.keys(meta.stacks)) {
+    const roots = stackRoots(meta.stacks[name]!);
+    const split = splitMultiRootStack(meta, name);
+    if (split.length === 0) continue;
+    p.log.success(
+      `Split ${pc.yellow(name)}, which had ${roots.length} root branches: ${pc.yellow(roots[0]!)} stays, ${split.map((s) => pc.yellow(s)).join(", ")} split off`,
+    );
+  }
+}
+
+/** Report the stacks that still fail validation; returns how many. */
+async function reportInvalidStacks(meta: StackMetadata): Promise<number> {
+  let invalid = 0;
+  for (const name of Object.keys(meta.stacks)) {
+    const errors = await validateStack(meta, name);
+    if (errors.length === 0) continue;
+    invalid++;
+    console.log();
+    p.log.warn(`Stack ${pc.yellow(name)} is invalid:`);
+    for (const error of errors) console.log(`  ${pc.red("•")} ${error}`);
+  }
+  return invalid;
+}
+
 // ── Migration ──
 
 async function migrateIfNeeded(): Promise<boolean> {

package/src/commands/merge.ts

@@ -6,7 +6,6 @@ import * as git from "../lib/git.ts";
 import {
   findStackForBranch,
   getOrderedBranches,
-  removeBranchFromStack,
   stackBase,
   writeMetadata,
 } from "../lib/metadata.ts";
@@ -28,7 +27,8 @@ import { guardRemoteContent } from "../lib/remote-guard.ts";
 import { ensureNoPendingRun } from "./restack.ts";
 import {
   planMerges,
-  advanceNewBottom,
+  advancePastMerged,
+  survivorsOf,
   type BranchReview,
   type MergeAction,
 } from "../lib/advance.ts";
@@ -1032,7 +1032,8 @@ function resolveMergePush(args: string[]): Resolved {
 /**
  * `gh-stack merge --base` — squash-merge ONLY the bottom PR into main, then
  * re-root the next branch onto main (replaying just its own commits, via
- * advance.ts's fork-point resolution). One PR per run — run it again to land the
+ * advance.ts's fork-point resolution); every child, each its own stack, when
+ * the bottom PR has several (#60). One PR per run — run it again to land the
  * next. Approval is NOT checked here; GitHub branch protection enforces it.
  * A base PR already merged outside gh-stack is detected and advanced past.
  */
@@ -1107,7 +1108,9 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
   // 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;
+  const mergedRun = [baseBranch, ...mergedAbove];
+  // Every unmerged branch on the run is re-rooted: one per child (#60).
+  const survivors = survivorsOf(stack, mergedRun);
 
   console.log();
   console.log(`  ${pc.bold("Plan:")}`);
@@ -1123,10 +1126,16 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
       `    ${pc.dim(`drop ${mergedAbove.join(", ")} (already merged into the branch below)`)}`,
     );
   }
-  if (nextChild) {
+  if (survivors.length === 1) {
     console.log(
-      `    ${pc.dim(`then re-root ${nextChild} onto ${trunk} — the rest stays a stack`)}`,
+      `    ${pc.dim(`then re-root ${survivors[0]} onto ${trunk} — the rest stays a stack`)}`,
     );
+  } else if (survivors.length > 1) {
+    console.log(
+      `    ${pc.dim(`then re-root ${survivors.join(", ")} onto ${trunk} — each becomes its own stack`)}`,
+    );
+  }
+  if (survivors.length > 0) {
     if (!push) {
       console.log(
         `    ${pc.dim(`(--no-push: re-rooted branches stay local; ${pc.green("gh-stack submit")} publishes them)`)}`,
@@ -1141,8 +1150,8 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
   }
 
   const confirmed = await confirmAction(
-    nextChild
-      ? `Merge base PR #${basePr} into ${trunk} and re-root ${nextChild}?`
+    survivors.length > 0
+      ? `Merge base PR #${basePr} into ${trunk} and re-root ${survivors.join(", ")}?`
       : `Merge base PR #${basePr} into ${trunk}?`,
   );
   if (!confirmed) {
@@ -1201,12 +1210,11 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
   await takeSnapshot(meta, stackName, "merge-base");
   // Keep a copy of the original topology to archive if the stack fully drains.
   const originalStack = structuredClone(stack);
+  let split: string[] = [];
 
   for (let i = 0; i < plan.steps.length; i++) {
     const step = plan.steps[i]!;
     const mergedBranch = step.branch;
-    const child = nextChild;
-    const childPr = child ? (stack.branches[child]?.pr ?? null) : null;
 
     console.log();
     console.log(pc.cyan("━".repeat(40)));
@@ -1253,7 +1261,7 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
       p.log.info(`PR #${step.pr} already merged — advancing the stack past it.`);
     }
 
-    if (child) {
+    if (survivors.length > 0) {
       // Re-root onto the trunk as it is now, with the merge in it (#51).
       const trunkState = await fetchTrunkWithMerge(trunk, step.pr!);
       if (!trunkState.ok) {
@@ -1266,56 +1274,53 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
           } yet.`,
         );
         console.log(
-          `  Stopped before re-rooting ${pc.yellow(child)}: a ${trunk} without the merge would drop its changes from the stack.`,
+          `  Stopped before re-rooting ${pc.yellow(survivors.join(", "))}: a ${trunk} without the merge would drop its changes from the stack.`,
         );
         console.log(`  Once ${trunk} has it, finish with:`);
         console.log(`    ${pc.green("gh-stack merge --base")}`);
         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: mergedParent,
-        alsoMerged: [mergedBranch, ...mergedAbove].filter((b) => b !== mergedParent),
-        child,
-        childPr,
-        targetRef,
-        recordedBase: trunk,
-        push,
-        expect: verified.get(child),
-      });
-      if (!res.ok) {
+    const res = await advancePastMerged({
+      meta,
+      stackName,
+      merged: mergedRun,
+      survivors: survivors.map((branch) => ({
+        branch,
+        pr: stack.branches[branch]?.pr ?? null,
+        expect: verified.get(branch),
+      })),
+      targetRef,
+      recordedBase: trunk,
+      push,
+    });
+    if (!res.ok) {
+      console.log();
+      if (res.reason === "conflict") {
+        p.log.error(`Rebase conflict re-rooting ${pc.yellow(res.child)} onto ${trunk}.`);
+        console.log(`  Resolve the conflict, then finish with:`);
+        console.log(`    ${pc.green("git rebase --continue")}`);
+        console.log(
+          `    ${pc.green("gh-stack merge --base")}   ${pc.dim(`(pushes ${res.child}, retargets its PR, restacks the rest)`)}`,
+        );
         console.log();
-        if (res.reason === "conflict") {
-          p.log.error(`Rebase conflict re-rooting ${pc.yellow(child)} onto ${trunk}.`);
-          console.log(`  Resolve the conflict, then finish with:`);
-          console.log(`    ${pc.green("git rebase --continue")}`);
-          console.log(
-            `    ${pc.green("gh-stack merge --base")}   ${pc.dim(`(pushes ${child}, retargets its PR, restacks the rest)`)}`,
-          );
-          console.log();
-          console.log(
-            pc.dim(`  The merged PR(s) below ${child} are done; only the re-root needs finishing.`),
-          );
-        } else {
-          p.log.error(
-            `Could not determine a safe rebase base for ${pc.yellow(child)} (${res.reason}).`,
-          );
-          console.log(
-            `  Re-root it manually:\n    ${pc.green(`git rebase --onto ${targetRef} <merged-tip> ${child}`)}`,
-          );
-        }
-        process.exit(2);
-      }
-    } else {
-      // Nothing unmerged rides above it. Just drop the merged run.
-      for (const branch of [mergedBranch, ...mergedAbove]) {
-        await removeBranchFromStack(meta, stackName, branch);
+        console.log(
+          pc.dim(
+            `  The merged PR(s) below ${res.child} are done; only the re-root needs finishing.`,
+          ),
+        );
+      } else {
+        p.log.error(
+          `Could not determine a safe rebase base for ${pc.yellow(res.child)} (${res.reason}).`,
+        );
+        console.log(
+          `  Re-root it manually:\n    ${pc.green(`git rebase --onto ${targetRef} <merged-tip> ${res.child}`)}`,
+        );
       }
+      process.exit(2);
     }
+    split = res.split;
   }
 
   // Did the whole stack drain, or is there a tail to restack?
@@ -1345,17 +1350,20 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
     return;
   }
 
-  // Restack the surviving tail onto the newly re-rooted bottom. The new bottom
-  // is itself already rebased onto main; restack skips it (base branch) and
-  // propagates onto its children using the snapshot taken above.
-  console.log();
-  p.log.info(
-    `Restacking ${remaining.length} remaining branch(es) onto ${pc.yellow(remaining[0]!)}...`,
-  );
-  const newBottom = remaining[0]!;
-  if (await git.localBranchExists(newBottom)) {
+  // Restack the surviving tail onto the newly re-rooted bottom, then each stack
+  // split off beside it (#60). Each new bottom is already rebased onto main;
+  // restack skips it (base branch) and propagates onto its children using the
+  // snapshot taken above.
+  const { default: restack } = await import("./restack.ts");
+  for (const name of [stackName, ...split]) {
+    const tail = meta.stacks[name] ? getOrderedBranches(meta.stacks[name]) : [];
+    const newBottom = tail[0];
+    if (!newBottom || !(await git.localBranchExists(newBottom))) continue;
+    console.log();
+    p.log.info(
+      `Restacking ${pc.yellow(name)} (${tail.length} branch(es)) onto ${pc.yellow(newBottom)}...`,
+    );
     await git.checkout(newBottom);
-    const { default: restack } = await import("./restack.ts");
     // Push unless this run is local-only (--no-push / GH_STACK_NO_PUSH): the
     // tail must match the re-root above. An explicit flag also means the
     // `[restack] push` config isn't read mid-merge.
@@ -1364,7 +1372,9 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
 
   p.outro(
     pc.green(
-      `Merged base PR #${basePr} into ${trunk}; ${remaining.length} branch(es) left as a stack.`,
+      split.length > 0
+        ? `Merged base PR #${basePr} into ${trunk}; the rest is now ${split.length + 1} stacks: ${[stackName, ...split].join(", ")}.`
+        : `Merged base PR #${basePr} into ${trunk}; ${remaining.length} branch(es) left as a stack.`,
     ),
   );
 }

package/src/commands/submit.ts

@@ -393,13 +393,13 @@ async function runSubmit(args: string[], run: RunState, jsonMode: boolean): Prom
   const outcomes = run.outcomes;
 
   // The branch's PR: recorded in metadata, else looked up on GitHub. A PR
-  // found that way (opened outside gh-stack) is recorded for next time.
+  // found that way (opened outside gh-stack) is recorded for next time, except
+  // in a dry run, which still looks so its plan doesn't offer to create it.
   const findPr = async (name: string): Promise<number | null> => {
     const bm = stack.branches[name]!;
     if (bm.pr) return bm.pr;
-    if (dryRun) return null;
     const found = await getPrNumber(name);
-    if (found) {
+    if (found && !dryRun) {
       bm.pr = found;
       metadataChanged = true;
     }

package/src/commands/sync.ts

@@ -6,7 +6,6 @@ import * as git from "../lib/git.ts";
 import {
   findStackForBranch,
   getOrderedBranches,
-  removeBranchFromStack,
   stackBase,
   writeMetadata,
 } from "../lib/metadata.ts";
@@ -17,8 +16,9 @@ import { guardRemoteContent } from "../lib/remote-guard.ts";
 import { getPrMergeState } from "../lib/github.ts";
 import {
   planMerges,
-  advanceNewBottom,
+  advancePastMerged,
   strandedMerges,
+  survivorsOf,
   type BranchReview,
   type MergePlan,
   type MergedRunEntry,
@@ -198,9 +198,29 @@ adds on GitHub). Pull or cherry-pick them first; see \`gh-stack restack --help\`
   // need to find when restacking children. (See resolveRestackBoundary.)
   await takeSnapshot(meta, stackName, "sync");
 
+  if (advance.split.length > 0) {
+    p.log.info(
+      `Split off ${advance.split.map((s) => pc.yellow(s)).join(", ")} — each is synced after ${pc.yellow(stackName)}. ` +
+        pc.dim(`If a run stops, finish it, then run gh-stack sync on the stacks it didn't reach.`),
+    );
+  }
+
   // Rebase the root onto main, push it, then restack every branch above it —
   // one run, saved after every step, so `restack --resume` can finish it.
   await syncChain(meta, stackName, ordered, { trunkRef: "origin/main", push, verified });
+
+  // Stacks split off by the advance are already re-rooted onto the trunk, but
+  // the branches above their roots still sit on the old roots (#60).
+  for (const name of advance.split) {
+    const splitStack = meta.stacks[name];
+    if (!splitStack) continue;
+    await takeSnapshot(meta, name, "sync");
+    await syncChain(meta, name, getOrderedBranches(splitStack), {
+      trunkRef: "origin/main",
+      push,
+      verified,
+    });
+  }
 }
 
 /**
@@ -257,6 +277,8 @@ interface AdvanceOutcome {
   advanced: boolean;
   /** The whole stack drained (every branch was already merged) and was archived. */
   drained: boolean;
+  /** Stacks split off because several branches sat on the merged run (#60). */
+  split: string[];
 }
 
 /** The contiguous merged bottom branches, and how each one's PR merged. */
@@ -312,16 +334,15 @@ async function advanceMergedBottoms(
   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 };
+    return { detected: false, advanced: false, drained: false, split: [] };
   }
 
   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;
+  // Every unmerged branch sitting on the run: one per child of a merged branch.
+  const survivors = survivorsOf(stack, mergedBranches);
 
   p.log.warn(`${plan.steps.length} bottom PR(s) already merged:`);
   for (const step of plan.steps) {
@@ -329,17 +350,22 @@ async function advanceMergedBottoms(
   }
   console.log(
     `  ${pc.dim(
-      survivor
-        ? `Dropping them and re-rooting ${survivor} onto ${trunk}, so only its own commits replay.`
-        : `Dropping them: nothing is left above them.`,
+      survivors.length === 0
+        ? `Dropping them: nothing is left above them.`
+        : `Dropping them and re-rooting ${survivors.join(", ")} onto ${trunk}, so only their own commits replay.`,
     )}`,
   );
+  if (survivors.length > 1) {
+    console.log(
+      `  ${pc.dim(`Each of ${survivors.join(", ")} becomes its own stack: siblings on ${trunk} don't depend on each other.`)}`,
+    );
+  }
   console.log();
   warnStranded(strandedMerges(run, trunk), trunk);
 
   if (dryRun) {
     p.log.warn("[DRY RUN] Would advance the stack past the merged bottom PR(s)");
-    return { detected: true, advanced: false, drained: false };
+    return { detected: true, advanced: false, drained: false, split: [] };
   }
 
   const targetRef = `origin/${trunk}`;
@@ -347,41 +373,37 @@ async function advanceMergedBottoms(
   await takeSnapshot(meta, stackName, "sync-advance");
   const originalStack = structuredClone(stack);
 
-  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}`)}`,
-        );
-      }
-      process.exit(2);
+  const res = await advancePastMerged({
+    meta,
+    stackName,
+    merged: mergedBranches,
+    survivors: survivors.map((branch) => ({
+      branch,
+      pr: stack.branches[branch]?.pr ?? null,
+      expect: verified.get(branch),
+    })),
+    targetRef,
+    recordedBase: trunk,
+    push: !noPush,
+  });
+  if (!res.ok) {
+    console.log();
+    if (res.reason === "conflict") {
+      p.log.error(`Rebase conflict re-rooting ${pc.yellow(res.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 ${res.child}; not restack, which would put it back on ${res.mergedBranch})`)}`,
+      );
+    } else {
+      p.log.error(
+        `Could not determine a safe rebase base for ${pc.yellow(res.child)} (${res.reason}).`,
+      );
+      console.log(
+        `  Re-root manually:\n    ${pc.green(`git rebase --onto ${targetRef} <${res.mergedBranch}'s pre-merge tip> ${res.child}`)}`,
+      );
     }
-  } else {
-    for (const branch of mergedBranches) await removeBranchFromStack(meta, stackName, branch);
+    process.exit(2);
   }
 
   // Whole stack drained? Archive the original topology and land on the trunk.
@@ -398,10 +420,10 @@ async function advanceMergedBottoms(
     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: true, split: [] };
   }
 
-  return { detected: true, advanced: true, drained: false };
+  return { detected: true, advanced: true, drained: false, split: res.split };
 }
 
 /**

package/src/lib/advance.ts

@@ -4,6 +4,8 @@
 // `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.
+// A merged branch with several children leaves several new bottoms: each is
+// re-rooted and becomes its own stack (#60).
 //
 // 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,
@@ -19,8 +21,8 @@
 import * as p from "./output.ts";
 import pc from "picocolors";
 import * as git from "./git.ts";
-import type { StackMetadata } from "../types.ts";
-import { removeBranchFromStack, writeMetadata } from "./metadata.ts";
+import type { Stack, StackMetadata } from "../types.ts";
+import { getOrderedBranches, removeBranchFromStack, writeMetadata } from "./metadata.ts";
 import { resolveRestackBoundary } from "./snapshot.ts";
 import { setPrBase } from "./github.ts";
 
@@ -182,119 +184,153 @@ export async function resolveForkPoint(
   return boundary?.sha ?? null;
 }
 
-/** Outcome of advancing a single new bottom onto the trunk. */
+/** An unmerged branch sitting on a merged run: it gets re-rooted onto the trunk. */
+export interface Survivor {
+  branch: string;
+  pr: number | null;
+  /**
+   * Its origin tip as the remote guard checked and cleared it: the push
+   * leases on exactly that sha (see git.forcePushWithLease).
+   */
+  expect?: string;
+}
+
+/**
+ * The unmerged branches whose parent is in the merged run, parents first.
+ * Usually one, but a merged branch with several children leaves one per child,
+ * and each needs its own re-root (#60).
+ */
+export function survivorsOf(stack: Stack, merged: string[]): string[] {
+  const run = new Set(merged);
+  return getOrderedBranches(stack).filter((b) => !run.has(b) && run.has(stack.branches[b]!.parent));
+}
+
+/** Outcome of advancing a stack past a merged run. */
 export type AdvanceResult =
-  | { ok: true }
-  | { ok: false; reason: "conflict" | "no-fork-point" | "bad-fork-point"; forkPoint?: string };
+  | {
+      ok: true;
+      /** Stacks split off because the run left several branches on the trunk (#60). */
+      split: string[];
+    }
+  | {
+      ok: false;
+      /** The survivor that couldn't be re-rooted, and the merged branch it sat on. */
+      child: string;
+      mergedBranch: string;
+      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` (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`.
+ * Re-root each survivor onto `targetRef`, dropping its merged parent's
+ * now-squashed commits, push it, and repoint its PR base to `recordedBase`.
+ * Then drop the whole merged run from the stack metadata. Survivors left side
+ * by side on the trunk become one stack each (see splitMultiRootStack).
  *
  * 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`.
- * Metadata still names the merged branch as the child's parent then, so the
- * fix is to re-run the caller: this skips the finished rebase and does the rest.
- * (`restack` would rebase the child back onto the merged branch.)
+ * Metadata still names the merged branches then, so the fix is to re-run the
+ * caller: survivors already on the target skip their rebase and finish the
+ * rest. (`restack` would rebase them back onto the merged branch.)
  */
-export async function advanceNewBottom(opts: {
+export async function advancePastMerged(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.
+   * The merged run, every branch of it. Their commits are in the trunk, so
+   * they're dropped without being re-rooted themselves (#54).
    */
-  alsoMerged?: string[];
-  child: string;
-  childPr: number | null;
+  merged: string[];
+  survivors: Survivor[];
   targetRef: string;
   recordedBase: string;
   /** false = `--no-push`: rebase + metadata only, leave origin and the PR alone (#36). */
   push?: boolean;
-  /**
-   * The child's origin tip as the remote guard checked and cleared it: the
-   * push leases on exactly that sha (see git.forcePushWithLease).
-   */
-  expect?: string;
 }): Promise<AdvanceResult> {
-  const { meta, stackName, mergedBranch, child, childPr, targetRef, recordedBase } = opts;
+  const { meta, stackName, targetRef, recordedBase } = opts;
   const push = opts.push ?? true;
-  let retargeted = false;
+  const prBases = new Map<string, string>();
 
-  // Already on the target: an earlier run stopped on a conflict the user then
-  // resolved, or the branch was re-rooted by hand (#51). Its fork point is
-  // behind it now, so skip the rebase and finish the rest (push, PR base,
-  // metadata). Before a re-root the child can't contain the target, which
-  // holds the merged PR's new squash commit.
-  if (await git.isAncestor(targetRef, child)) {
-    p.log.info(
-      `${pc.yellow(child)} is already on ${pc.green(recordedBase)} — finishing its re-root`,
-    );
-  } else {
-    const forkPoint = await resolveForkPoint(meta, mergedBranch, child);
-    if (!forkPoint) return { ok: false, reason: "no-fork-point" };
+  for (const survivor of opts.survivors) {
+    const child = survivor.branch;
+    const childPr = survivor.pr;
+    const mergedBranch = meta.stacks[stackName]!.branches[child]!.parent;
+    let retargeted = false;
 
-    // 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 };
-    }
+    // Already on the target: an earlier run stopped on a conflict the user then
+    // resolved, or the branch was re-rooted by hand (#51). Its fork point is
+    // behind it now, so skip the rebase and finish the rest (push, PR base,
+    // metadata). Before a re-root the child can't contain the target, which
+    // holds the merged PR's new squash commit.
+    if (await git.isAncestor(targetRef, child)) {
+      p.log.info(
+        `${pc.yellow(child)} is already on ${pc.green(recordedBase)} — finishing its re-root`,
+      );
+    } else {
+      const forkPoint = await resolveForkPoint(meta, mergedBranch, child);
+      if (!forkPoint) return { ok: false, child, mergedBranch, reason: "no-fork-point" };
 
-    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 };
-  }
+      // 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, child, mergedBranch, reason: "bad-fork-point", forkPoint };
+      }
 
-  if (push) {
-    // Push the rebased head first so the PR diff is clean before its base flips.
-    // If it didn't land, leave the base alone: retargeting onto the trunk with
-    // the old head on origin would show the merged commits in the PR (#29).
-    const pushed = await git.forcePushWithLease(child, { expect: opts.expect });
-    if (!pushed.ok) {
-      p.log.error(
-        `Push of ${pc.yellow(child)} failed — PR${childPr != null ? ` #${childPr}` : ""} left on ${mergedBranch} for now. The next push of ${child} that lands (gh-stack restack --resume, sync) retargets it.`,
+      p.log.info(
+        `Re-rooting ${pc.yellow(child)} onto ${pc.green(recordedBase)} ${pc.dim(`(base: ${forkPoint.slice(0, 8)})`)}`,
       );
-      for (const line of git.pushFailureHint(child, pushed)) console.log(`  ${line}`);
-    } else if (childPr != null) {
-      const moved = await setPrBase(childPr, recordedBase);
-      if (moved) {
-        retargeted = true;
-        p.log.success(`PR #${childPr} base → ${pc.green(recordedBase)}`);
-      } else {
-        p.log.warn(
-          `Could not retarget PR #${childPr} — the next push of ${child} retries, or set its base to ${recordedBase} manually`,
+      const ok = await git.rebaseOnto(targetRef, forkPoint, child);
+      if (!ok) return { ok: false, child, mergedBranch, reason: "conflict", forkPoint };
+    }
+
+    if (push) {
+      // Push the rebased head first so the PR diff is clean before its base flips.
+      // If it didn't land, leave the base alone: retargeting onto the trunk with
+      // the old head on origin would show the merged commits in the PR (#29).
+      const pushed = await git.forcePushWithLease(child, { expect: survivor.expect });
+      if (!pushed.ok) {
+        p.log.error(
+          `Push of ${pc.yellow(child)} failed — PR${childPr != null ? ` #${childPr}` : ""} left on ${mergedBranch} for now. The next push of ${child} that lands (gh-stack restack --resume, sync) retargets it.`,
         );
+        for (const line of git.pushFailureHint(child, pushed)) console.log(`  ${line}`);
+      } else if (childPr != null) {
+        const moved = await setPrBase(childPr, recordedBase);
+        if (moved) {
+          retargeted = true;
+          p.log.success(`PR #${childPr} base → ${pc.green(recordedBase)}`);
+        } else {
+          p.log.warn(
+            `Could not retarget PR #${childPr} — the next push of ${child} retries, or set its base to ${recordedBase} manually`,
+          );
+        }
       }
+    } else if (childPr != null) {
+      // Retargeting the base without pushing the rebased head would show the
+      // merged commits in the PR diff, so leave both for `submit` to reconcile.
+      p.log.info(
+        `Not pushing ${pc.yellow(child)} or retargeting PR #${childPr} (--no-push) — ${pc.green("gh-stack submit")} publishes both`,
+      );
     }
-  } else if (childPr != null) {
-    // Retargeting the base without pushing the rebased head would show the
-    // merged commits in the PR diff, so leave both for `submit` to reconcile.
-    p.log.info(
-      `Not pushing ${pc.yellow(child)} or retargeting PR #${childPr} (--no-push) — ${pc.green("gh-stack submit")} publishes both`,
-    );
-  }
 
-  // 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.
-  for (const merged of [...(opts.alsoMerged ?? []), mergedBranch]) {
-    await removeBranchFromStack(meta, stackName, merged);
+    // 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
+    // retargets it (restack's pushStep), so it's never left there.
+    if (childPr != null) prBases.set(child, retargeted ? recordedBase : mergedBranch);
   }
 
-  // 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
-  // retargets it (restack's pushStep), so it's never left there.
-  const entry = meta.stacks[stackName]?.branches[child];
-  if (entry && childPr != null) {
-    entry.prBase = retargeted ? recordedBase : mergedBranch;
+  // Metadata last: drop the merged run in one go (survivors move onto the
+  // trunk) and write. Done after the git work succeeds so a failure never
+  // leaves metadata describing a state git didn't reach.
+  const split = await removeBranchFromStack(meta, stackName, opts.merged);
+
+  if (prBases.size > 0) {
+    for (const stack of [stackName, ...split].map((name) => meta.stacks[name])) {
+      for (const [branch, prBase] of prBases) {
+        const entry = stack?.branches[branch];
+        if (entry) entry.prBase = prBase;
+      }
+    }
     await writeMetadata(meta);
   }
-  return { ok: true };
+  return { ok: true, split };
 }

package/src/lib/chain.ts

@@ -4,9 +4,25 @@
 // auto-create/register a stack from a bare set of local branches so the
 // end state is always stack registered + branches pushed + PRs created).
 import * as git from "./git.ts";
+import { allBranchMemberships, type BranchMembership } from "./branch-config.ts";
 import { findStackForBranch, getOrderedBranches, stackBase } from "./metadata.ts";
 import type { StackMetadata, Branch } from "../types.ts";
 
+/**
+ * A new stack entry for a branch, keeping the PR number and id already
+ * recorded for it in git config. Git config is shared by every worktree of a
+ * repo, but stack files are not: a branch submitted in one worktree and then
+ * tracked in another (the dependency sweep's handoff) would otherwise lose its
+ * PR, and `sync` and `merge --base` would not see it merge.
+ */
+function newBranchEntry(parent: string, recorded: BranchMembership | undefined): Branch {
+  return {
+    parent,
+    ...(recorded?.pr != null && { pr: recorded.pr }),
+    ...(recorded?.id && { id: recorded.id }),
+  };
+}
+
 /**
  * Detect a chain of branches from trunk to the current branch.
  *
@@ -107,6 +123,7 @@ export async function resolveOrCreateStack(
   trunk: string,
 ): Promise<StackResolution> {
   const fullChain = await detectBranchChain(branch, trunk); // trunk→current
+  const recorded = await allBranchMemberships();
 
   // Walk from just below `branch` downward; the first tracked ancestor is the
   // attachment point. Everything above it (up to `branch`) is the untracked
@@ -143,7 +160,7 @@ export async function resolveOrCreateStack(
       }
 
       if (stack.branches[name]) continue; // already tracked — leave as-is
-      stack.branches[name] = { parent };
+      stack.branches[name] = newBranchEntry(parent, recorded.get(name));
       stack.last_branch = name;
       addedBranches.push(name);
     }
@@ -177,8 +194,7 @@ export async function resolveOrCreateStack(
     const name = fullChain[i]!;
     if (stack.branches[name]) continue;
     const parent = i === 0 ? trunk : fullChain[i - 1]!;
-    const branchData: Branch = { parent };
-    stack.branches[name] = branchData;
+    stack.branches[name] = newBranchEntry(parent, recorded.get(name));
     stack.last_branch = name;
     addedBranches.push(name);
   }

package/src/lib/metadata.ts

@@ -535,48 +535,92 @@ export async function addBranchToStack(
 }
 
 /**
- * Remove a branch from a stack, re-parenting children to the removed branch's parent.
+ * Remove branches from a stack, re-parenting each one's children to its
+ * parent. If that leaves several branches on the stack's base (a removed root
+ * had more than one child), they're split into one stack each; see
+ * splitMultiRootStack. Returns the names of the stacks split off.
+ *
+ * Pass every branch that leaves at once (e.g. a whole merged run): splitting
+ * after each removal could move a branch still to be removed into another stack.
  */
 export async function removeBranchFromStack(
   meta: StackMetadata,
   stackName: string,
-  branchName: string,
-): Promise<StackMetadata> {
+  branchNames: string | string[],
+): Promise<string[]> {
   const stack = meta.stacks[stackName];
   if (!stack) {
     throw new Error(`Stack "${stackName}" not found`);
   }
 
-  const branch = stack.branches[branchName];
-  if (!branch) {
-    throw new Error(`Branch "${branchName}" not found in stack "${stackName}"`);
-  }
+  for (const branchName of typeof branchNames === "string" ? [branchNames] : branchNames) {
+    const branch = stack.branches[branchName];
+    if (!branch) {
+      throw new Error(`Branch "${branchName}" not found in stack "${stackName}"`);
+    }
 
-  const removedParent = branch.parent;
+    for (const b of Object.values(stack.branches)) {
+      if (b.parent === branchName) b.parent = branch.parent;
+    }
+    delete stack.branches[branchName];
 
-  // Re-parent children
-  for (const [, b] of Object.entries(stack.branches)) {
-    if (b.parent === branchName) {
-      b.parent = removedParent;
+    // The removed branch may still exist in git but is no longer a member —
+    // drop its membership config explicitly (syncBranchConfig also would, but
+    // be direct since the branch is gone from `meta`).
+    await clearBranchMembership(branchName);
+
+    if (stack.last_branch === branchName) {
+      const remaining = Object.keys(stack.branches);
+      stack.last_branch = remaining.length > 0 ? remaining[remaining.length - 1]! : null;
     }
   }
 
-  // Remove the branch
-  delete stack.branches[branchName];
+  const split = splitMultiRootStack(meta, stackName);
+  await writeMetadata(meta);
+  return split;
+}
 
-  // The removed branch may still exist in git but is no longer a member —
-  // drop its membership config explicitly (syncBranchConfig also would, but
-  // be direct since the branch is gone from `meta`).
-  await clearBranchMembership(branchName);
+/** The branches sitting directly on the stack's base, in insertion order. */
+export function stackRoots(stack: Stack): string[] {
+  const base = stackBase(stack);
+  return Object.keys(stack.branches).filter((b) => stack.branches[b]!.parent === base);
+}
 
-  // Update last_branch if it was the removed one
-  if (stack.last_branch === branchName) {
-    const remaining = Object.keys(stack.branches);
-    stack.last_branch = remaining.length > 0 ? remaining[remaining.length - 1]! : null;
+/**
+ * Give each root of a stack with several roots its own stack (#60). A stack has
+ * exactly one root, so this happens when a removed root had several children:
+ * siblings on the same base are independent stacks. The first root keeps the
+ * stack; each other root's subtree moves to a new stack named after that root
+ * (suffixed `-2`, `-3`… on a clash), on the same base. Metadata only: no git
+ * branch moves. The caller writes. Returns the new stacks' names.
+ */
+export function splitMultiRootStack(meta: StackMetadata, stackName: string): string[] {
+  const stack = meta.stacks[stackName];
+  if (!stack) return [];
+  const [, ...others] = stackRoots(stack);
+  const created: string[] = [];
+
+  for (const root of others) {
+    let name = root;
+    for (let n = 2; meta.stacks[name]; n++) name = `${root}-${n}`;
+
+    const moved: Stack = {
+      description: stack.description ? `Split from ${stackName}` : "",
+      last_branch: null,
+      branches: {},
+      base: stackBase(stack),
+    };
+    for (const b of buildRebaseChain(stack, root)) {
+      moved.branches[b] = stack.branches[b]!;
+      delete stack.branches[b];
+    }
+    moved.last_branch = getOrderedBranches(moved).at(-1) ?? null;
+    meta.stacks[name] = moved;
+    created.push(name);
   }
 
-  await writeMetadata(meta);
-  return meta;
+  if (created.length > 0) stack.last_branch = getOrderedBranches(stack).at(-1) ?? null;
+  return created;
 }
 
 /**

package/src/lib/safety.ts

@@ -6,6 +6,7 @@ import {
   readMetadata,
   findStackForBranch,
   stackBase,
+  stackRoots,
 } from "./metadata.ts";
 import type { StackMetadata, Stack } from "../types.ts";
 import * as p from "./output.ts";
@@ -219,9 +220,15 @@ export async function ensureValidStack(
     console.log(`  ${pc.red("•")} ${error}`);
   }
   console.log();
-  console.log(
-    pc.dim(`Repair the local branches, or run ${pc.green("gh-stack doctor")}, before retrying.`),
-  );
+  if (stackRoots(meta.stacks[stackName]!).length > 1) {
+    console.log(
+      pc.dim(`Run ${pc.green("gh-stack doctor")} to split it into one stack per root, then retry.`),
+    );
+  } else {
+    console.log(
+      pc.dim(`Repair the local branches, or run ${pc.green("gh-stack doctor")}, before retrying.`),
+    );
+  }
   process.exit(1);
 }
 

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

@@ -129,6 +129,11 @@ This resolves the catch-22 where `sync`/`restack` said "not in any stack" for a
 tip you hadn't submitted yet. (`submit` still auto-tracks too — `add` is just the
 no-publish path.)
 
+**Handing a stack over from another worktree.** Stack files are per worktree,
+but the PR numbers gh-stack records in git config are shared. So after
+submitting from a worktree, `gh-stack add <top-branch>` in the main checkout
+tracks the whole chain _with_ its PRs, and `sync`/`merge --base` work there.
+
 **Splice an existing branch/PR into a stack — `gh-stack join`.** For a branch
 that should have been stacked but was cut from main on its own (often with its
 own PR already open):
@@ -310,8 +315,10 @@ deletes them from the PR.
 
 **`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
+detects it, drops every merged branch, and re-roots each unmerged branch sitting
+on them onto trunk instead of replaying squashed commits and conflicting. A
+merged branch with several children (the dependency sweep's batch PR with one
+breaking PR per upgrade) leaves one stack per child, and sync syncs each. It rebases
 onto `origin/main` (fetched itself), so a stale local `main` doesn't matter.
 
 ### 5. Status
@@ -343,7 +350,8 @@ Merge is **top-down everywhere** (collapse PRn → PRn-1 → … → base PR, th
   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
+  the next branch onto trunk (every child, each as its own stack, when the
+  bottom PR has several) — 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
   outside gh-stack. If the re-root stops (a conflict, or "origin/main doesn't
   show its merge commit"), fix it (`git rebase --continue`) and **re-run
@@ -372,13 +380,13 @@ cherry-pick them, don't force past it.
 ### 7. Maintenance
 
 ```bash
-gh-stack delete        # remove a branch from the stack (re-parents children)
+gh-stack delete        # remove a branch from the stack (re-parents children; a root's several children become one stack each)
 gh-stack split         # cut a stack into two at a branch
 gh-stack join <b>      # splice an existing branch/PR into the stack (--above <b>, --dry-run)
 gh-stack rename        # rename a tracked branch (keeps metadata in sync)
 gh-stack undo          # restore from the last snapshot
 gh-stack archive       # manage archived stacks
-gh-stack doctor        # migrate & repair stack metadata
+gh-stack doctor        # migrate & repair stack metadata (splits a stack with several roots)
 gh-stack update-prs    # repair stack viz in PR descriptions + adopt PRs opened with gh pr create
 ```