gh-stack 0.7.0 → 0.9.0

package/src/commands/merge.ts

@@ -3,7 +3,12 @@ import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import { $ } from "bun";
 import * as git from "../lib/git.ts";
-import { findStackForBranch, getOrderedBranches, writeMetadata } from "../lib/metadata.ts";
+import {
+  findStackForBranch,
+  getOrderedBranches,
+  stackBase,
+  writeMetadata,
+} from "../lib/metadata.ts";
 import { ensureMetadata, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { getPrMergeState } from "../lib/github.ts";
@@ -84,6 +89,19 @@ OPTIONS
   await ensureValidStack(meta, stackName);
   const ordered = getOrderedBranches(stack);
 
+  // A split stack is rooted on a branch in another stack, so its base PR
+  // doesn't target main — merging it now would land it against the wrong base.
+  // Re-root onto main first (after the parent stack merges).
+  const base = stackBase(stack);
+  if (base !== "main" && base !== "master") {
+    p.cancel(
+      `${pc.yellow(stackName)} is based on ${pc.yellow(base)}, not main — can't merge yet.\n\n` +
+        `  Merge (or finish) the parent stack first, then re-root onto main:\n` +
+        `    ${pc.green("gh-stack restack --onto main")}`,
+    );
+    process.exit(1);
+  }
+
   if (ordered.length <= 1) {
     // Single branch — just enable auto-merge
     const basePr = stack.branches[ordered[0]!]?.pr;

package/src/commands/restack.ts

@@ -5,18 +5,16 @@ import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import {
   findStackForBranch,
+  stackBase,
   buildRebaseChain,
+  getOrderedBranches,
   saveRestackState,
   loadRestackState,
   clearRestackState,
   readMetadata,
+  writeMetadata,
 } from "../lib/metadata.ts";
-import {
-  ensureMetadata,
-  ensureCleanWorkingTree,
-  ensureNotMain,
-  ensureValidStack,
-} from "../lib/safety.ts";
+import { ensureMetadata, ensureCleanWorkingTree, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot, findPreRewriteSha } from "../lib/snapshot.ts";
 import { confirmAction } from "../lib/ui.ts";
 import type { StackMetadata } from "../types.ts";
@@ -26,14 +24,23 @@ export default async function restack(args: string[]): Promise<void> {
   const resume = args.includes("--resume");
   const verbose = args.includes("--verbose") || args.includes("-v");
 
+  // --onto <branch>: re-root the current stack onto a new base (e.g. move a
+  // split stack from its parent branch onto main once the parent has merged).
+  let ontoFlag: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--onto" && args[i + 1]) ontoFlag = args[++i];
+  }
+
   if (args.includes("--help")) {
     console.log(`
 gh-stack restack — Rebase children onto updated parents
 
 USAGE
   gh-stack restack [options]
+  gh-stack restack --onto <branch>    Re-root the current stack onto <branch>
 
 OPTIONS
+  --onto <ref> Re-root the stack onto a new base ref (changes stack base)
   --yes, -y   Skip confirmations (auto-accept all rebases and pushes)
   --resume    Resume after resolving rebase conflicts
   --dry-run   Show what would happen without executing
@@ -43,6 +50,8 @@ EXAMPLES
   gh-stack restack              Interactive (prompts before each rebase)
   gh-stack restack --yes        Non-interactive (for agents/CI)
   gh-stack restack --resume     Continue after resolving conflicts
+  gh-stack restack --onto main  Re-root a split stack onto main after its
+                                parent stack has merged
 
 ALIASES
   gh-stack rebase
@@ -67,6 +76,9 @@ ALIASES
 
   const meta = await ensureMetadata();
   const rebasedBranches: string[] = [];
+  // Every branch restack is responsible for this run (rebased OR already
+  // up to date) — we push each one and verify its ref landed at the end.
+  const touched: string[] = [];
 
   p.intro(pc.cyan("Git Stack Restack"));
 
@@ -74,10 +86,12 @@ ALIASES
   // (pre-snapshot). Keeps users upgrading from <0.4 from seeing stale tags.
   await git.deleteTagsMatching(git.STACK_SYNC_TAG_GLOB);
 
-  if (resume) {
-    await handleResume(meta, rebasedBranches, verbose);
+  if (ontoFlag) {
+    await handleReroot(meta, ontoFlag, rebasedBranches, touched, dryRun, verbose);
+  } else if (resume) {
+    await handleResume(meta, rebasedBranches, touched, verbose);
   } else {
-    await handleFreshRestack(meta, rebasedBranches, dryRun, verbose);
+    await handleFreshRestack(meta, rebasedBranches, touched, dryRun, verbose);
   }
 
   // Summary
@@ -91,12 +105,60 @@ ALIASES
     }
   }
 
+  // Verification pass: assert every touched branch's ref actually landed on
+  // origin. Fail loudly (listing the stale ones) rather than reporting success
+  // when a push didn't take. (#12)
+  if (!dryRun) {
+    const stale = await findStaleRefs(touched);
+    if (stale.length > 0) {
+      console.log();
+      p.log.error("Some branch refs are NOT in sync with origin:");
+      for (const { branch, local, remote } of stale) {
+        console.log(`  ${pc.red("✗")} ${branch}  local ${local.slice(0, 8)}  origin ${remote}`);
+      }
+      console.log();
+      console.log(
+        `  Reconcile with: ${pc.green("gh-stack restack")} (re-runs the push for stale refs)`,
+      );
+      p.outro(pc.red("Restack finished with un-pushed refs"));
+      process.exit(1);
+    }
+  }
+
   p.outro(pc.green("Stack Restack Complete!"));
 }
 
+/**
+ * For each branch, compare its local tip against origin. Returns the ones that
+ * differ (or whose remote ref is missing), so restack can report exactly which
+ * refs didn't land instead of falsely claiming success. (#12)
+ */
+async function findStaleRefs(
+  branches: string[],
+): Promise<{ branch: string; local: string; remote: string }[]> {
+  const stale: { branch: string; local: string; remote: string }[] = [];
+  const seen = new Set<string>();
+  for (const branch of branches) {
+    if (seen.has(branch) || branch === "main" || branch === "master") continue;
+    seen.add(branch);
+    if (!(await git.localBranchExists(branch))) continue;
+    const local = await git.revParse(branch);
+    if (!(await git.remoteBranchExists(branch))) {
+      stale.push({ branch, local, remote: "(missing)" });
+      continue;
+    }
+    const remote = await git.revParse(`origin/${branch}`).catch(() => "");
+    if (remote !== local) {
+      stale.push({ branch, local, remote: remote ? remote.slice(0, 8) : "(unknown)" });
+    }
+  }
+  return stale;
+}
+
 async function handleResume(
   meta: StackMetadata,
   rebasedBranches: string[],
+  touched: string[],
   verbose: boolean,
 ): Promise<void> {
   p.log.warn("Resuming from saved state...");
@@ -135,10 +197,11 @@ async function handleResume(
   // Rebase completed successfully
   p.log.success("Rebase completed successfully");
   rebasedBranches.push(expectedBranch);
+  touched.push(expectedBranch);
   await clearRestackState();
 
   // Prompt to push the resumed branch
-  await promptPush(expectedBranch);
+  await pushBranchRef(expectedBranch);
 
   // Continue with remaining branches in chain
   const stackName = state.stack_name;
@@ -149,13 +212,23 @@ async function handleResume(
   const currentIndex = state.current_index + 1;
 
   if (currentIndex < chain.length) {
-    await processChain(meta, stackName, chain, currentIndex, rebasedBranches, false, verbose);
+    await processChain(
+      meta,
+      stackName,
+      chain,
+      currentIndex,
+      rebasedBranches,
+      touched,
+      false,
+      verbose,
+    );
   }
 }
 
 async function handleFreshRestack(
   meta: StackMetadata,
   rebasedBranches: string[],
+  touched: string[],
   dryRun: boolean,
   verbose: boolean,
 ): Promise<void> {
@@ -189,26 +262,40 @@ async function handleFreshRestack(
   }
   console.log();
 
-  // Skip base branches (parent = main) unless this is a sync
-  const baseBranches = chain.filter((b) => stack.branches[b]?.parent === "main");
+  // Skip the stack's root branch (parent = base) when the base is the trunk —
+  // rebasing onto trunk is `sync`'s job, not restack's. For a split stack
+  // whose base is a sibling branch, the root SHOULD be rebased onto that base
+  // so changes propagate, so we don't skip it.
+  const base = stackBase(stack);
+  const baseIsTrunk = base === "main" || base === "master";
+  const baseBranches = baseIsTrunk ? chain.filter((b) => stack.branches[b]?.parent === base) : [];
   if (baseBranches.length > 0) {
-    p.log.warn("Skipping base branch(es) (parent: main):");
-    for (const base of baseBranches) {
-      console.log(`  ${pc.cyan("Skip:")} ${base} ${pc.blue("(parent: main)")}`);
+    p.log.warn(`Skipping base branch(es) (parent: ${base}):`);
+    for (const baseBranch of baseBranches) {
+      console.log(`  ${pc.cyan("Skip:")} ${baseBranch} ${pc.blue(`(parent: ${base})`)}`);
     }
     console.log();
     console.log(`  ${pc.dim("This is a restack — propagating changes from parent to children.")}`);
-    console.log(`  ${pc.dim(`To include rebasing onto main, use: ${pc.green("gh-stack sync")}`)}`);
+    console.log(
+      `  ${pc.dim(`To include rebasing onto ${base}, use: ${pc.green("gh-stack sync")}`)}`,
+    );
     console.log();
 
-    chain = chain.filter((b) => stack.branches[b]?.parent !== "main");
+    chain = chain.filter((b) => stack.branches[b]?.parent !== base);
+
+    // We don't rebase the base branch, but if you committed on it its ref is
+    // now stale on origin — push it so the PR reflects the new commit. (#12)
+    if (!dryRun) {
+      for (const baseBranch of baseBranches) {
+        if (await git.localBranchExists(baseBranch)) {
+          touched.push(baseBranch);
+          await pushBranchRef(baseBranch);
+        }
+      }
+    }
 
     if (chain.length === 0) {
-      p.log.warn("No branches to process after skipping base branches");
-      console.log();
-      console.log("  Either:");
-      console.log("    1. Run from a child branch (e.g., PR2)");
-      console.log(`    2. Use ${pc.green("gh-stack sync")} to include rebasing base onto main`);
+      p.log.info("No child branches to rebase — base branch ref reconciled above.");
       return;
     }
 
@@ -228,7 +315,130 @@ async function handleFreshRestack(
   }
 
   // Process the chain
-  await processChain(meta, stackName, chain, 0, rebasedBranches, dryRun, verbose);
+  await processChain(meta, stackName, chain, 0, rebasedBranches, touched, dryRun, verbose);
+}
+
+/**
+ * Re-root the current stack onto a new base (`restack --onto <newBase>`).
+ *
+ * Used to move a split stack off its parent-stack branch and onto the trunk
+ * once that parent stack has merged. The root branch is rebased with
+ * `git rebase --onto <newBase> <oldBaseTip> <root>`, where oldBaseTip is the
+ * tip of the current base branch — so only the root's own commits replay onto
+ * the new base (the now-merged parent commits are dropped). Children then
+ * restack onto the moved root via the normal chain logic.
+ */
+async function handleReroot(
+  meta: StackMetadata,
+  newBase: string,
+  rebasedBranches: string[],
+  touched: string[],
+  dryRun: boolean,
+  verbose: boolean,
+): Promise<void> {
+  const currentBranch = await git.currentBranch();
+  const stackName = findStackForBranch(meta, currentBranch);
+
+  if (!stackName) {
+    p.cancel(`Branch ${pc.blue(currentBranch)} is not in any stack.`);
+    process.exit(1);
+  }
+
+  const stack = meta.stacks[stackName]!;
+  await ensureValidStack(meta, stackName);
+
+  const oldBase = stackBase(stack);
+  if (oldBase === newBase) {
+    p.log.warn(
+      `${pc.yellow(stackName)} is already based on ${pc.yellow(newBase)} — nothing to do.`,
+    );
+    return;
+  }
+
+  // The root is the branch whose parent is the current base.
+  const ordered = getOrderedBranches(stack);
+  const root = ordered[0];
+  if (!root) {
+    p.cancel("Stack has no branches");
+    process.exit(1);
+  }
+
+  // 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)";
+  }
+
+  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}`,
+      )}`,
+    );
+    process.exit(1);
+  }
+
+  p.log.info(`Re-rooting ${pc.yellow(stackName)}: ${pc.dim(oldBase)} → ${pc.green(newBase)}`);
+  p.log.info(`Root branch: ${pc.yellow(root)}`);
+  if (verbose) {
+    p.log.info(`Rebase base: ${oldBaseTip.slice(0, 8)} (${oldBaseSource})`);
+  }
+  console.log();
+
+  if (dryRun) {
+    p.log.warn(`[DRY RUN] Would rebase ${root} onto ${newBase} (from ${oldBaseTip.slice(0, 8)})`);
+    const children = ordered.slice(1);
+    if (children.length > 0) {
+      p.log.info(`[DRY RUN] Would restack ${children.length} child branch(es) onto the moved root`);
+    }
+    return;
+  }
+
+  const confirmed = await confirmAction(
+    `Re-root ${pc.yellow(stackName)} onto ${pc.yellow(newBase)}?`,
+  );
+  if (!confirmed) {
+    p.cancel("Cancelled");
+    process.exit(0);
+  }
+
+  // Snapshot before rewriting, then commit the new base into metadata.
+  await takeSnapshot(meta, stackName, "reroot");
+  stack.base = newBase;
+  stack.branches[root]!.parent = newBase;
+  await writeMetadata(meta);
+
+  // Rebase the root onto the new base, dropping the old base's commits.
+  p.log.info(`Checking out ${pc.yellow(root)}...`);
+  await git.checkout(root);
+  p.log.info(`Rebasing ${pc.yellow(root)} onto ${pc.yellow(newBase)}...`);
+  const ok = await git.rebaseOnto(newBase, oldBaseTip, root);
+
+  if (!ok) {
+    console.log();
+    p.log.error("Rebase conflict — resolve and run:");
+    console.log(`  ${pc.green("git rebase --continue")}`);
+    console.log(
+      `  ${pc.green("gh-stack restack")}   ${pc.dim("(from the first child, to restack the rest)")}`,
+    );
+    process.exit(2);
+  }
+
+  rebasedBranches.push(root);
+  touched.push(root);
+  await pushBranchRef(root);
+
+  // Restack the children onto the moved root.
+  const children = ordered.slice(1);
+  if (children.length > 0) {
+    const chain = buildRebaseChain(stack, children[0]!);
+    await processChain(meta, stackName, chain, 0, rebasedBranches, touched, false, verbose);
+  }
 }
 
 async function processChain(
@@ -237,6 +447,7 @@ async function processChain(
   chain: string[],
   startIndex: number,
   rebasedBranches: string[],
+  touched: string[],
   dryRun: boolean,
   verbose: boolean,
 ): Promise<void> {
@@ -258,9 +469,16 @@ async function processChain(
     console.log(pc.cyan("━".repeat(40)));
     console.log();
 
-    // Check if already up to date
+    // Check if already up to date. The branch doesn't need rebasing, but its
+    // remote ref may still be stale — e.g. this is the branch you just
+    // committed on, which triggered the restack. Push it so origin (and its
+    // PR) reflects the new commit. (#12)
     if (await git.isAncestor(parent, branch)) {
       p.log.success("Already up to date with parent");
+      if (!dryRun) {
+        touched.push(branch);
+        await pushBranchRef(branch);
+      }
       continue;
     }
 
@@ -352,10 +570,12 @@ async function processChain(
     if (success) {
       p.log.success("Rebase successful");
       rebasedBranches.push(branch);
+      touched.push(branch);
       await clearRestackState();
 
-      // Prompt to push immediately (don't batch)
-      await promptPush(branch);
+      // Push immediately (don't batch) so an interrupt can't leave later
+      // branches un-pushed.
+      await pushBranchRef(branch);
     } else {
       // Conflict!
       console.log();
@@ -376,36 +596,42 @@ async function processChain(
   }
 }
 
-async function promptPush(branch: string): Promise<void> {
-  ensureNotMain(branch);
-
-  if (!(await git.remoteBranchExists(branch))) return;
+/**
+ * Reconcile a single branch's ref with origin. Pushes when the local tip
+ * differs from origin OR the remote branch doesn't exist yet (so a branch
+ * that was never pushed still lands). No-op when already in sync. (#12)
+ */
+async function pushBranchRef(branch: string): Promise<void> {
+  if (branch === "main" || branch === "master") return;
 
   const localSha = await git.revParse(branch);
-  let remoteSha: string;
-  try {
-    remoteSha = await git.revParse(`origin/${branch}`);
-  } catch {
-    return;
-  }
+  const hasRemote = await git.remoteBranchExists(branch);
+  const remoteSha = hasRemote ? await git.revParse(`origin/${branch}`).catch(() => null) : null;
 
-  if (localSha === remoteSha) return;
+  if (hasRemote && remoteSha === localSha) return; // already in sync — nothing to do
 
   console.log();
   console.log(pc.cyan("━".repeat(40)));
-  console.log(pc.blue("  Push Rebased Branch?"));
+  console.log(pc.blue(hasRemote ? "  Push Rebased Branch?" : "  Push New Branch?"));
   console.log(pc.cyan("━".repeat(40)));
   console.log();
   console.log(`${pc.blue("Branch:")} ${branch}`);
-  console.log(pc.yellow("⚠ Branch is out of sync with remote"));
-  console.log(`  Local:  ${localSha.slice(0, 8)}`);
-  console.log(`  Remote: ${remoteSha.slice(0, 8)}`);
+  if (hasRemote) {
+    console.log(pc.yellow("⚠ Branch is out of sync with remote"));
+    console.log(`  Local:  ${localSha.slice(0, 8)}`);
+    console.log(`  Remote: ${remoteSha ? remoteSha.slice(0, 8) : "(unknown)"}`);
+  } else {
+    console.log(pc.yellow("⚠ Branch has no remote ref yet"));
+    console.log(`  Local:  ${localSha.slice(0, 8)}`);
+  }
   console.log();
 
-  const confirmed = await confirmAction("Push with --force-with-lease?");
+  const confirmed = await confirmAction(
+    hasRemote ? "Push with --force-with-lease?" : `Push ${branch} to origin?`,
+  );
   if (confirmed) {
     p.log.info(`Pushing ${branch}...`);
-    const ok = await git.forcePushWithLease(branch);
+    const ok = await git.pushStackedBranch(branch);
     if (ok) {
       p.log.success("Pushed successfully");
     } else {

package/src/commands/split.ts

@@ -0,0 +1,159 @@
+// gh-stack split — Cut a stack into two at a given branch.
+//
+// The branch you cut at (and everything above it) moves into a NEW stack whose
+// base is the cut branch's parent — a branch that stays in the original stack.
+// This is a pure metadata operation: no branches are moved or rebased in git,
+// since stack membership is just bookkeeping on top of the real branch graph.
+//
+// Typical use: a long chain is in review and can't merge yet, but new work is
+// piling on top. Split at the first "new work" branch so the original stack
+// stays the review unit and the new stack rides on its tip. Once the original
+// stack merges, re-root the new stack onto main with `gh-stack restack --onto main`.
+import * as p from "../lib/output.ts";
+import pc from "picocolors";
+import { buildRebaseChain, getOrderedBranches, stackBase, writeMetadata } from "../lib/metadata.ts";
+import { ensureMetadata, ensureCurrentStack, ensureValidStack } from "../lib/safety.ts";
+import { selectBranch, confirmAction } from "../lib/ui.ts";
+import * as git from "../lib/git.ts";
+import type { Stack } from "../types.ts";
+
+const HELP = `
+gh-stack split — Cut a stack into two at a branch
+
+USAGE
+  gh-stack split [<branch>] [options]
+
+The branch you cut at — and every branch above it — moves into a new stack
+whose base is the cut branch's parent (which stays in the original stack).
+Purely a metadata operation: no git branches are moved or rebased.
+
+If no branch is given, shows an interactive selector. You cannot split at the
+stack's root branch (that would just rename the whole stack).
+
+OPTIONS
+  --name <name>   Name for the new stack (default: the cut branch name)
+
+EXAMPLES
+  gh-stack split feat-12                 # feat-12.. become a new stack based on feat-11
+  gh-stack split feat-12 --name phase-2  # ...named "phase-2"
+
+AFTER THE ORIGINAL STACK MERGES
+  gh-stack restack --onto main           # re-root the split stack onto main
+`;
+
+export default async function split(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(HELP);
+    return;
+  }
+
+  // Parse flags
+  let nameFlag: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--name" && args[i + 1]) nameFlag = args[++i];
+  }
+  const positional = args.filter((a) => !a.startsWith("-"));
+
+  const meta = await ensureMetadata();
+  const stackName = ensureCurrentStack(meta);
+  await ensureValidStack(meta, stackName);
+  const stack = meta.stacks[stackName]!;
+  const currentBranch = await git.currentBranch();
+  const base = stackBase(stack);
+
+  p.intro(pc.cyan("Split Stack"));
+
+  // Determine the cut branch
+  let cutBranch = positional[0];
+  if (!cutBranch) {
+    cutBranch =
+      (await selectBranch(
+        stack,
+        "Select the branch to cut at (it becomes the new stack's root)",
+        currentBranch,
+      )) ?? undefined;
+    if (!cutBranch) {
+      p.cancel("Cancelled");
+      process.exit(0);
+    }
+  }
+
+  // Validate
+  const cut = stack.branches[cutBranch];
+  if (!cut) {
+    p.cancel(`Branch ${pc.yellow(cutBranch)} not found in stack ${pc.blue(stackName)}`);
+    process.exit(1);
+  }
+
+  if (cut.parent === base) {
+    p.cancel(
+      `${pc.yellow(cutBranch)} is the root of ${pc.blue(stackName)} — there's nothing below it to split off.\n\n  Pick a branch higher up the stack.`,
+    );
+    process.exit(1);
+  }
+
+  // The new stack is the subtree rooted at the cut branch.
+  const moving = buildRebaseChain(stack, cutBranch);
+  const newBase = cut.parent; // stays in the original stack
+
+  // Pick a name for the new stack (default = cut branch, auto-suffix on clash)
+  let newName = nameFlag || cutBranch;
+  if (!nameFlag) {
+    let n = 2;
+    while (meta.stacks[newName]) newName = `${cutBranch}-${n++}`;
+  }
+  if (meta.stacks[newName]) {
+    p.cancel(`Stack "${newName}" already exists`);
+    process.exit(1);
+  }
+
+  // Report the plan
+  p.log.info(`Stack: ${pc.yellow(stackName)} (base: ${pc.dim(base)})`);
+  p.log.info(`Cut at: ${pc.yellow(cutBranch)} (parent: ${pc.dim(newBase)})`);
+  p.log.info(
+    `Moving ${moving.length} branch${moving.length > 1 ? "es" : ""} into new stack ${pc.yellow(newName)} (base: ${pc.dim(newBase)})`,
+  );
+  for (const b of moving) {
+    console.log(`    ${pc.dim("→")} ${b}`);
+  }
+  console.log();
+
+  const confirmed = await confirmAction(
+    `Split ${moving.length} branch(es) into ${pc.yellow(newName)} based on ${pc.yellow(newBase)}?`,
+  );
+  if (!confirmed) {
+    p.cancel("Cancelled");
+    process.exit(0);
+  }
+
+  // ── Pure metadata move ──
+  const newStack: Stack = {
+    description: stack.description ? `Split from ${stackName}` : "",
+    last_branch: null,
+    branches: {},
+    base: newBase,
+  };
+
+  for (const b of moving) {
+    newStack.branches[b] = stack.branches[b]!; // parent links stay valid within the subtree
+    delete stack.branches[b];
+  }
+
+  meta.stacks[newName] = newStack;
+
+  // Recompute last_branch for both stacks from their now-final graphs
+  newStack.last_branch = getOrderedBranches(newStack).at(-1) ?? null;
+  stack.last_branch = getOrderedBranches(stack).at(-1) ?? null;
+
+  // Follow the user: if they're standing on a moved branch, make the new stack
+  // current; otherwise leave the original stack current.
+  meta.current_stack = moving.includes(currentBranch) ? newName : stackName;
+
+  await writeMetadata(meta);
+
+  p.outro(
+    pc.green(
+      `Split ${pc.yellow(stackName)} → ${pc.yellow(newName)} (${moving.length} branch(es), based on ${pc.yellow(newBase)})`,
+    ),
+  );
+}

package/src/commands/status.ts

@@ -5,6 +5,7 @@ import * as git from "../lib/git.ts";
 import {
   readMetadata,
   metadataExists,
+  legacyMetadataExists,
   getOrderedBranches,
   findStackForBranch,
 } from "../lib/metadata.ts";
@@ -32,6 +33,12 @@ Progress/spinner output goes to stderr so stdout stays clean for piping.
   const jsonMode = args.includes("--json");
   const currentOnly = args.includes("--current");
 
+  // Read-only command, so don't hard-block — but if v2 metadata hasn't been
+  // migrated, stacks won't be grouped. Nudge to stderr (keeps stdout/JSON clean).
+  if (!(await metadataExists()) && (await legacyMetadataExists())) {
+    process.stderr.write("Note: stack metadata is unmigrated (v2). Run `gh-stack doctor`.\n");
+  }
+
   // Progress goes to stderr so stdout is clean for agents
   process.stderr.write("Fetching open PRs...\n");