gh-stack 0.9.0 → 0.11.0

package/README.md

@@ -154,18 +154,22 @@ merge [--dry-run] [-d|--delete-branch] [--collapse]
     then enables auto-merge for the base PR into main. All merges
     happen on GitHub so PRs show as "Merged", Linear tickets close
     automatically, and GitHub Actions fire normally. Skips already-
-    merged PRs (safe to re-run). Waits for GitHub between merges.
+    merged PRs (safe to re-run). Waits for GitHub between merges, and
+    self-heals its spurious "Head branch is out of date" (a stale PR
+    head pointer after a child squash) by re-syncing and retrying.
     --collapse  Stop after collapsing the stack into the base PR;
                 leaves the base PR open against main so you can
                 review the cumulative diff on GitHub. Re-run
                 `gh-stack merge` (without --collapse) to finish.
 
 split [<branch>] [--name <name>]
-    Cut the current stack into two at <branch>. The cut branch and every
-    branch above it move 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. Interactive
-    selector if no branch is given; you can't split at the stack's root.
+    Cut a stack into two at <branch>. The cut branch and every branch
+    above it move into a NEW stack whose base is the cut branch's parent
+    (which stays in the original stack). The target stack is the one
+    containing <branch>, so this works from anywhere — not only while
+    standing on it. Purely a metadata operation — no git branches are
+    moved or rebased. Interactive selector (current stack) if no branch
+    is given; you can't split at the stack's root.
 
     Use it when 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
@@ -173,10 +177,25 @@ split [<branch>] [--name <name>]
     tip. Once the original stack merges, re-root the new stack with
     `gh-stack restack --onto main`.
 
+rename [<old-name>] <new-name>
+    Rename a tracked branch (runs `git branch -m`) and re-key the stack
+    topology so it stays tracked, re-parenting any children that pointed
+    at the old name. With one argument, renames the current branch. Built
+    for the throwaway-branch → ticketed-PR flow (`feature-wip` →
+    `feature-BEE-1234`) without hand-editing metadata.
+
+    You don't strictly need this command: gh-stack also auto-reconciles
+    after a plain `git branch -m` (the per-branch git config is rename-
+    proof, so the next gh-stack command heals the name-keyed topology).
+    Renaming a branch that already has a PR is local-only — the GitHub PR
+    still tracks the old remote branch.
+
 delete [<branch>] [-k|--keep-branch] [--no-remote]
-    Remove a branch from the stack and re-parent its children, then
+    Remove a branch from its stack and re-parent its children, then
     delete the underlying local git branch (and the remote branch if
-    it was pushed). Interactive selector if no branch specified.
+    it was pushed). The <branch> argument names its own stack, so this
+    works from anywhere. Interactive selector (current stack) if none
+    specified.
     --keep-branch leaves the git branches untouched (metadata only);
     --no-remote deletes the local branch but keeps the remote.
 ```
@@ -188,8 +207,30 @@ log
     Display the current stack as a tree with branch numbers,
     PR info, and descriptions. This is the default command.
 
+    If the current branch isn't tracked yet, log inspects its ancestry
+    and points at the next step: if it sits on top of an existing stack,
+    `gh-stack submit` to add it; if it's stacked on untracked branches,
+    submit to create the stack and open PRs; if it's on trunk, `init`.
+
+update-prs [--force]
+    Refresh the "📚 Stacked on" visualization block in every PR
+    description for the current stack. PRs whose rendered block is
+    unchanged are skipped; --force rewrites all of them. (submit does
+    this automatically — use this to refresh without pushing.)
+
+stacks [--current] [--json]
+    List all stacks and their topology. Read-only and network-free —
+    emits stack membership straight from local metadata, so external
+    tools (status scripts, dashboards) can consume --json as a stable
+    interface instead of parsing the .git/.gh-stack/ store directly.
+    --current  Only the stack containing the current branch
+    --json     Topology as JSON: { current_stack, current_branch,
+               stacks: [{ name, description, base, is_current,
+               branches: [{ branch, parent, pr, description }] }] }
+
 status [--current] [--json]
     PR dashboard showing review state, CI status, and merge readiness.
+    Unlike `stacks`, this hits the network to fetch live PR/CI status.
     --current  Show only the current stack or standalone PR
     --json     Structured JSON output (progress goes to stderr)
 
@@ -267,7 +308,7 @@ per-stack files plus git-native branch config, rather than a single JSON blob:
 
 ```
 .git/.gh-stack/
-  current                      hint: last-active stack name
+  current                      derived stack of the current branch (self-heals on read)
   active/<stack>.json          topology of a live stack (ordered branches, base, description)
   archived/<stack>.json        merged/closed stacks
   deleted/<stack>.json         tombstones (recoverable)
@@ -296,6 +337,7 @@ deleting a branch updates/cleans it automatically:
 branch.<name>.ghstack-stack   <stack>
 branch.<name>.ghstack-parent  <parent-branch>
 branch.<name>.ghstack-pr      <number>
+branch.<name>.ghstack-id      <uuid>   stable identity (survives rename)
 ```
 
 The two representations cross-check each other; `gh-stack doctor` reconciles
@@ -304,9 +346,17 @@ any drift. Why this shape:
 - **A stack can't silently vanish** — lifecycle transitions are file moves
   (`active/ → archived/ → deleted/`), and a stale stack file is tombstoned, never
   just unlinked.
-- **No `current_stack` drift** — the stack you're on is derivable from the
-  branch's own config, so a written pointer can't contradict reality.
+- **No `current_stack` drift** — the stack you're on is derived from the branch
+  you've checked out (its own membership, or the nearest tracked ancestor for a
+  new branch stacked on top), re-resolved and self-healed on every read, so a
+  written pointer can never contradict reality.
 - **No all-or-nothing blast radius** — one bad write can't corrupt other stacks.
+- **Renames heal themselves** — `git branch -m old new` moves the whole
+  `branch.<old>` config section to `branch.<new>` (id and all), but the JSON is
+  keyed by name and goes stale. On the next command, gh-stack matches the moved
+  config to its stale JSON entry by `ghstack-id` (or PR number for older
+  branches), re-keys it, and re-points any children. So `gh-stack rename` — or
+  even a raw `git branch -m` — never needs manual metadata surgery.
 
 #### Migrating from v2
 

package/package.json

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

package/src/commands/delete.ts

@@ -2,7 +2,12 @@
 import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import { removeBranchFromStack, getChildren } from "../lib/metadata.ts";
-import { ensureMetadata, ensureCurrentStack, ensureValidStack } from "../lib/safety.ts";
+import {
+  ensureMetadata,
+  ensureCurrentStack,
+  ensureValidStack,
+  resolveStackForBranchArg,
+} from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { selectBranch, confirmAction } from "../lib/ui.ts";
 import * as git from "../lib/git.ts";
@@ -34,7 +39,12 @@ OPTIONS
   const positional = args.filter((a) => !a.startsWith("-"));
 
   const meta = await ensureMetadata();
-  const stackName = ensureCurrentStack(meta);
+  // The branch to delete names its own stack — resolve from it so
+  // `delete <branch>` works from anywhere. Only fall back to the current stack
+  // (the branch you're on) in interactive mode, when no branch was given.
+  const stackName = positional[0]
+    ? resolveStackForBranchArg(meta, positional[0]!)
+    : ensureCurrentStack(meta);
   await ensureValidStack(meta, stackName);
   const stack = meta.stacks[stackName]!;
   const currentBranch = await git.currentBranch();

package/src/commands/list.ts

@@ -25,24 +25,22 @@ ALIASES
   const meta = await ensureMetadata();
   const currentBranch = await git.currentBranch();
 
-  // Find which stack contains the current branch
-  const branchStackName = findStackForBranch(meta, currentBranch);
-  let stackName = branchStackName;
-  if (!stackName) stackName = meta.current_stack;
+  // The current stack is whichever stack the checked-out branch belongs to —
+  // never the persisted `current_stack` hint. If this branch is in no stack,
+  // there is no current stack; don't resurface a previously-used one.
+  const stackName = findStackForBranch(meta, currentBranch);
 
   if (!stackName || !meta.stacks[stackName]) {
-    console.log("No active stack found.");
+    console.log("Branch is not in any stack.");
     process.exit(1);
   }
 
   const stack = meta.stacks[stackName]!;
   const ordered = getOrderedBranches(stack);
 
-  // Update tracking
+  // We're on a branch in this stack — record it as current + its last_branch.
   meta.current_stack = stackName;
-  if (branchStackName === stackName) {
-    stack.last_branch = currentBranch;
-  }
+  stack.last_branch = currentBranch;
   await writeMetadata(meta);
 
   // Header

package/src/commands/log.ts

@@ -10,6 +10,8 @@ import {
 } from "../lib/metadata.ts";
 import { renderStackTree } from "../lib/ui.ts";
 import { gateLegacyMetadata } from "../lib/safety.ts";
+import { detectBranchChain } from "../lib/chain.ts";
+import type { StackMetadata } from "../types.ts";
 
 export default async function log(_args: string[]): Promise<void> {
   // Check if metadata exists
@@ -30,33 +32,21 @@ export default async function log(_args: string[]): Promise<void> {
 
   const branch = await git.currentBranch();
 
-  // Find which stack contains the current branch
-  const branchStackName = findStackForBranch(meta, branch);
-  let stackName = branchStackName;
-
-  if (!stackName) {
-    // Fall back to current_stack
-    stackName = meta.current_stack;
-  }
+  // The current stack is whichever stack the checked-out branch belongs to —
+  // never the persisted `current_stack` hint. If this branch is in no stack,
+  // there is no current stack; don't resurface a previously-used one.
+  const stackName = findStackForBranch(meta, branch);
 
   if (!stackName || !meta.stacks[stackName]) {
-    p.log.warn(`Branch ${pc.blue(branch)} is not in any stack`);
-    console.log();
-    console.log(`  Add it to a stack with:`);
-    console.log(`    ${pc.green("gh-stack add")}`);
-    console.log();
-    console.log(`  Or create a new stack:`);
-    console.log(`    ${pc.green("gh-stack init")}`);
+    await suggestNextStep(meta, branch);
     process.exit(1);
   }
 
   const stack = meta.stacks[stackName]!;
 
-  // Update current_stack and last_branch
+  // We're on a branch in this stack — record it as current + its last_branch.
   meta.current_stack = stackName;
-  if (branchStackName === stackName) {
-    stack.last_branch = branch;
-  }
+  stack.last_branch = branch;
   await writeMetadata(meta);
 
   // Header
@@ -76,3 +66,93 @@ export default async function log(_args: string[]): Promise<void> {
   console.log(pc.dim(`Tip: Switch stacks with 'gh-stack checkout --stack'`));
   console.log();
 }
+
+/**
+ * The current branch isn't a tracked stack member. Inspect its local ancestry —
+ * the same chain `submit` would self-heal — and point at the lowest-friction
+ * next step:
+ *   - sits on top of an existing stack  → `submit` to ADD it to that stack;
+ *   - stacked on untracked branches only → `submit` to CREATE a new stack;
+ *   - based directly on trunk            → `submit` to push + open a PR;
+ *   - on trunk                           → `init`.
+ */
+async function suggestNextStep(meta: StackMetadata, branch: string): Promise<void> {
+  const trunk = await git.trunkBranch();
+
+  if (branch === trunk || branch === "main" || branch === "master") {
+    p.log.warn(`You're on ${pc.blue(branch)} — not a stack branch`);
+    console.log();
+    console.log(`  Checkout a feature branch, then start a stack with:`);
+    console.log(`    ${pc.green("gh-stack init")}`);
+    console.log();
+    return;
+  }
+
+  // Reconstruct trunk→current the way `submit` does (local branches whose tips
+  // are ancestors of HEAD). [current] alone means it's based right off trunk.
+  let chain: string[] = [branch];
+  try {
+    chain = await detectBranchChain(branch, trunk);
+  } catch {
+    // Fall back to treating it as a single branch off trunk.
+  }
+
+  // Is this chain sitting on top of an existing tracked stack? Find the nearest
+  // ancestor in the chain that's already a stack member.
+  let attachStack: string | null = null;
+  for (let i = chain.length - 2; i >= 0; i--) {
+    const owner = findStackForBranch(meta, chain[i]!);
+    if (owner) {
+      attachStack = owner;
+      break;
+    }
+  }
+
+  p.log.warn(`Branch ${pc.blue(branch)} isn't tracked in a stack yet`);
+  console.log();
+
+  if (attachStack) {
+    // Extends an existing stack — submit ADDS the untracked tail to it.
+    console.log(`  It sits on top of stack ${pc.yellow(attachStack)}:`);
+    console.log();
+    console.log(`  ${pc.dim(trunk)}`);
+    for (let i = 0; i < chain.length; i++) {
+      const b = chain[i]!;
+      const isLast = i === chain.length - 1;
+      const tree = isLast ? "  ┗━" : "  ┣━";
+      const label = b === branch ? pc.yellow(b) + pc.dim(" (current)") : b;
+      const tag = findStackForBranch(meta, b) ? pc.dim(" (in stack)") : pc.green(" +");
+      console.log(`${tree} ${label}${tag}`);
+      if (!isLast) console.log("  ┃");
+    }
+    console.log();
+    console.log(`  Add it to the stack:`);
+    console.log(`    ${pc.green("gh-stack submit")}`);
+    console.log();
+    return;
+  }
+
+  if (chain.length > 1) {
+    // Stacked on untracked branches only — submit CREATES a new stack.
+    console.log(`  It's stacked on ${chain.length - 1} other local branch(es):`);
+    console.log();
+    console.log(`  ${pc.dim(trunk)}`);
+    for (let i = 0; i < chain.length; i++) {
+      const b = chain[i]!;
+      const isLast = i === chain.length - 1;
+      const tree = isLast ? "  ┗━" : "  ┣━";
+      const label = b === branch ? pc.yellow(b) + pc.dim(" (current)") : b;
+      console.log(`${tree} ${label}`);
+      if (!isLast) console.log("  ┃");
+    }
+    console.log();
+    console.log(`  Create the stack and open PRs for the whole chain:`);
+  } else {
+    // A single branch based directly on trunk.
+    console.log(`  It's based directly on ${pc.dim(trunk)}.`);
+    console.log();
+    console.log(`  Push it and open a PR — this also starts the stack:`);
+  }
+  console.log(`    ${pc.green("gh-stack submit")}`);
+  console.log();
+}

package/src/commands/merge.ts

@@ -11,12 +11,140 @@ import {
 } from "../lib/metadata.ts";
 import { ensureMetadata, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
-import { getPrMergeState } from "../lib/github.ts";
+import { getBranchRefSha, getPrMergeState, resyncPrHead } from "../lib/github.ts";
 import { confirmAction } from "../lib/ui.ts";
 
 const MAX_RETRIES = 12;
 const RETRY_DELAY_MS = 5000;
 
+// After GitHub rejects a merge with the "still recomputing" signature, back off
+// (capped) and re-poll before retrying. One entry per retry; length+1 = max
+// attempts. Bounds total transient wait per PR to ~30s.
+const MERGE_RETRY_BACKOFF_MS = [2000, 4000, 8000, 8000, 8000];
+
+/**
+ * GitHub returns these when `mergePullRequest` rejects a merge it considers
+ * out of date. In a top-down cascade this is almost always one of two timing
+ * artifacts (NOT a genuine conflict): a stale PR head pointer (most common —
+ * the child squash moved this branch but GitHub didn't advance the PR's
+ * `headRefOid`), or the brief async mergeability-recompute window.
+ */
+export function isTransientMergeError(stderr: string): boolean {
+  const s = stderr.toLowerCase();
+  return (
+    s.includes("head branch is out of date") ||
+    s.includes("base branch was modified") ||
+    s.includes("review and try the merge again")
+  );
+}
+
+/**
+ * Squash-merge a PR, healing the two timing artifacts a top-down cascade
+ * provokes — neither of which is a real conflict:
+ *
+ *  1. **Stale PR head (the dominant case).** Squash-merging the child moves
+ *     this PR's branch server-side, but GitHub sometimes fails to advance the
+ *     PR's recorded `headRefOid`. Every status read (`mergeable`,
+ *     `mergeStateStatus`, base…head compare) is computed against that stale
+ *     head and reports CLEAN, yet `mergePullRequest` checks the live ref and
+ *     rejects "Head branch is out of date" — indefinitely. We detect it by
+ *     comparing the PR's head to the live branch ref, and fix it by
+ *     close→reopen (`resyncPrHead`), which forces GitHub to re-read the branch.
+ *  2. **Mergeability recompute window.** Heads already match but GitHub is
+ *     still recomputing (`mergeStateStatus: UNKNOWN`); back off and re-poll.
+ *
+ * Only a state that settles genuinely non-mergeable (real conflict / failing
+ * required check) — or exhausted retries — is a hard failure.
+ */
+async function squashMergeWithRetry(
+  prNumber: number,
+  branch: string,
+  deleteFlag: boolean,
+  s: ReturnType<typeof p.spinner>,
+): Promise<{ ok: true } | { ok: false; stderr: string; genuine: boolean }> {
+  const maxAttempts = MERGE_RETRY_BACKOFF_MS.length + 1;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const ghArgs = ["pr", "merge", String(prNumber), "--squash"];
+    if (deleteFlag) ghArgs.push("--delete-branch");
+
+    const proc = Bun.spawn(["gh", ...ghArgs], { stdout: "pipe", stderr: "pipe" });
+    const stderr = await new Response(proc.stderr).text();
+    const exitCode = await proc.exited;
+    if (exitCode === 0) return { ok: true };
+
+    // Raced with another merge / a prior re-run? If it's already merged, done.
+    const state = await getPrMergeState(prNumber);
+    if (state?.state === "MERGED") return { ok: true };
+
+    const transient = isTransientMergeError(stderr);
+    if (!transient || attempt === maxAttempts) {
+      return { ok: false, stderr: stderr.trim(), genuine: !transient };
+    }
+
+    // Is the PR's head stuck behind the live branch tip? If so, the merge will
+    // fail forever until GitHub re-reads the branch — nudge it via close/reopen
+    // rather than burning the backoff budget polling a status that never moves.
+    if (await ensureFreshHead(prNumber, branch, s)) {
+      await waitForMergeable(prNumber, s);
+      continue; // retry the merge with a freshly-synced head
+    }
+
+    // Heads match — genuine recompute window. Back off and re-poll; if it
+    // settles non-mergeable instead, it was a real conflict after all.
+    const delay = MERGE_RETRY_BACKOFF_MS[attempt - 1]!;
+    s.message(
+      `PR #${prNumber}: GitHub still recomputing mergeability — retrying in ${delay / 1000}s (${attempt}/${maxAttempts - 1})...`,
+    );
+    await Bun.sleep(delay);
+    const ready = await waitForMergeable(prNumber, s);
+    if (!ready) return { ok: false, stderr: stderr.trim(), genuine: true };
+  }
+  // Unreachable — the loop returns on the final attempt.
+  return { ok: false, stderr: "merge retries exhausted", genuine: false };
+}
+
+/**
+ * After a `resyncPrHead` nudge, poll until GitHub advances the PR's recorded
+ * head to the live branch SHA (or we give up). Bounded by MAX_RETRIES.
+ */
+async function waitForHeadSync(
+  prNumber: number,
+  liveSha: string,
+  spinner: ReturnType<typeof p.spinner>,
+): Promise<boolean> {
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    const state = await getPrMergeState(prNumber);
+    if (state?.headRefOid === liveSha) return true;
+    if (state?.state === "MERGED") return true;
+    spinner.message(`Waiting for PR #${prNumber} head to sync... (${attempt}/${MAX_RETRIES})`);
+    await Bun.sleep(RETRY_DELAY_MS);
+  }
+  return false;
+}
+
+/**
+ * Heal a stuck PR head pointer. If the PR's recorded head has fallen behind the
+ * live branch ref (GitHub missed the head-sync after a child squash landed on
+ * this branch), force a re-read via close/reopen and wait for the head to catch
+ * up. Returns true if a nudge was performed; false (a no-op) when the heads
+ * already match, the PR is already merged, or the live ref can't be resolved.
+ */
+async function ensureFreshHead(
+  prNumber: number,
+  branch: string,
+  s: ReturnType<typeof p.spinner>,
+): Promise<boolean> {
+  const liveSha = await getBranchRefSha(branch);
+  const state = await getPrMergeState(prNumber);
+  if (!liveSha || !state?.headRefOid || state.state === "MERGED") return false;
+  if (state.headRefOid === liveSha) return false;
+
+  s.message(`PR #${prNumber}: head out of sync with ${pc.yellow(branch)} — nudging GitHub...`);
+  await resyncPrHead(prNumber);
+  await waitForHeadSync(prNumber, liveSha, s);
+  return true;
+}
+
 /**
  * Wait for a PR to become mergeable after a previous merge lands.
  * GitHub needs time to process the new commit on the target branch.
@@ -62,7 +190,10 @@ All merges happen on GitHub, so PRs show as "Merged", Linear tickets
 close automatically, and all GitHub Actions/webhooks fire normally.
 
 Skips PRs that are already merged (safe to re-run after partial failure).
-Waits for GitHub to process between merges if needed.
+Waits for GitHub to process between merges, and self-heals GitHub's
+spurious "Head branch is out of date" (a stale PR head pointer after a
+child squash) by re-syncing the branch and retrying — only a genuine
+conflict or failing required check is reported as a hard failure.
 
 OPTIONS
   -d, --delete-branch  Delete remote branches after merging
@@ -230,21 +361,22 @@ OPTIONS
 
     s.message(`Squash-merging PR #${childPrNum} via GitHub...`);
 
-    const ghArgs = ["pr", "merge", String(childPrNum), "--squash"];
-    if (deleteFlag) ghArgs.push("--delete-branch");
+    const result = await squashMergeWithRetry(childPrNum, childBranch, deleteFlag, s);
 
-    const proc = Bun.spawn(["gh", ...ghArgs], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const stderr = await new Response(proc.stderr).text();
-    const exitCode = await proc.exited;
-
-    if (exitCode === 0) {
+    if (result.ok) {
       s.stop(`Merged PR #${childPrNum} into ${pc.blue(parentBranch)}`);
     } else {
       s.stop(pc.red(`Failed to merge PR #${childPrNum}`));
-      p.log.error(stderr.trim());
+      p.log.error(result.stderr);
+      if (result.genuine) {
+        p.log.info(
+          "This looks like a real conflict or a failing required check — resolve it on GitHub.",
+        );
+      } else {
+        p.log.info(
+          "GitHub's mergeability recompute didn't settle in time (transient lag, not a conflict).",
+        );
+      }
       p.log.info("Re-run merge to continue from where you left off.");
       process.exit(2);
     }
@@ -328,25 +460,38 @@ OPTIONS
 
   const autoSpinner = p.spinner();
 
-  // Wait for base PR to be ready (may need time after last intermediate merge)
+  // Wait for base PR to be ready (may need time after last intermediate merge).
+  // The last intermediate merge moved this branch, so — like the cascade — the
+  // base PR's head can be stuck behind the live ref; heal it before enabling
+  // auto-merge, then once more if GitHub still rejects the first attempt.
   autoSpinner.start(`Waiting for PR #${basePr} to be ready...`);
+  await ensureFreshHead(basePr!, baseBranch, autoSpinner);
   await waitForMergeable(basePr!, autoSpinner);
 
   autoSpinner.message(`Enabling auto-merge for PR #${basePr}...`);
 
-  try {
+  const enableAutoMerge = async (): Promise<{ ok: boolean; stderr: string }> => {
     const ghArgs = ["pr", "merge", String(basePr), "--squash", "--auto"];
     if (deleteFlag) ghArgs.push("--delete-branch");
+    const proc = Bun.spawn(["gh", ...ghArgs], { stdout: "pipe", stderr: "pipe" });
+    const stderr = await new Response(proc.stderr).text();
+    const exitCode = await proc.exited;
+    return { ok: exitCode === 0, stderr: stderr.trim() };
+  };
+
+  let auto = await enableAutoMerge();
+  if (!auto.ok && isTransientMergeError(auto.stderr)) {
+    // Same stale-head artifact as the cascade — re-sync and try once more.
+    await ensureFreshHead(basePr!, baseBranch, autoSpinner);
+    await waitForMergeable(basePr!, autoSpinner);
+    auto = await enableAutoMerge();
+  }
 
-    const proc = Bun.spawn(["gh", ...ghArgs], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    await proc.exited;
-
+  if (auto.ok) {
     autoSpinner.stop(`Auto-merge enabled for PR #${basePr} — will merge into main when CI passes`);
-  } catch {
+  } 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`)}`);
   }
 
@@ -368,8 +513,10 @@ OPTIONS
   meta.archive[stackName] = { ...stack };
   delete meta.stacks[stackName];
   if (meta.current_stack === stackName) {
-    const remaining = Object.keys(meta.stacks);
-    meta.current_stack = remaining.length > 0 ? remaining[0]! : null;
+    // Don't auto-pick a random leftover stack as "current" — that switches you
+    // to a stack you never checked out. The current stack is derived from the
+    // branch you're on; after a merge you're on main, so default to none.
+    meta.current_stack = null;
   }
   await writeMetadata(meta);
 

package/src/commands/rename.ts

@@ -0,0 +1,111 @@
+// gh-stack rename — Rename a tracked branch and keep metadata in sync.
+//
+// The common flow: build on a throwaway branch (`kiliman/feature-wip`), then
+// rename it to a ticketed convention (`kiliman/feature-BEE-1234`) before
+// submitting. `git branch -m` moves the branch's rename-proof config section,
+// and gh-stack reconciles the name-keyed topology files on the next read — this
+// command is just the discoverable front door that does both and persists
+// immediately. (Renaming with raw `git branch -m` still self-heals; see
+// `reconcileRenames` in lib/metadata.ts.)
+import pc from "picocolors";
+import * as p from "../lib/output.ts";
+import * as git from "../lib/git.ts";
+import { findStackForBranch, readMetadata, writeMetadata } from "../lib/metadata.ts";
+import { ensureMetadata } from "../lib/safety.ts";
+import { confirmAction } from "../lib/ui.ts";
+
+const HELP = `
+gh-stack rename — Rename a tracked branch and update metadata
+
+USAGE
+  gh-stack rename <new-name>           Rename the current branch
+  gh-stack rename <old-name> <new-name>
+
+Renames the local git branch (\`git branch -m\`) and re-keys the stack
+topology so the branch stays tracked — re-parenting any children that
+pointed at the old name. Use this for the throwaway-branch → ticketed-PR
+flow without hand-editing metadata.
+
+Renaming a branch that already has a PR only renames it locally; the
+GitHub PR still tracks the old remote branch.
+`;
+
+export default async function rename(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(HELP);
+    return;
+  }
+
+  const positionals = args.filter((a) => !a.startsWith("-"));
+  if (positionals.length === 0 || positionals.length > 2) {
+    p.cancel("Usage: gh-stack rename [<old-name>] <new-name>");
+    process.exit(1);
+  }
+
+  const meta = await ensureMetadata();
+  const current = await git.currentBranch();
+
+  const oldName = positionals.length === 2 ? positionals[0]! : current;
+  const newName = positionals.length === 2 ? positionals[1]! : positionals[0]!;
+
+  // ── Validate ──
+  if (oldName === newName) {
+    p.cancel("Old and new names are identical — nothing to do.");
+    process.exit(1);
+  }
+  if (newName === "main" || newName === "master") {
+    p.cancel(`Refusing to rename a branch to ${pc.red(newName)}.`);
+    process.exit(1);
+  }
+  if (!(await git.localBranchExists(oldName))) {
+    p.cancel(`Branch ${pc.yellow(oldName)} does not exist locally.`);
+    process.exit(1);
+  }
+  if (await git.localBranchExists(newName)) {
+    p.cancel(`A branch named ${pc.yellow(newName)} already exists.`);
+    process.exit(1);
+  }
+
+  const stackName = findStackForBranch(meta, oldName);
+  if (!stackName) {
+    p.cancel(
+      `Branch ${pc.yellow(oldName)} isn't tracked in a stack.\n\n  Rename it with plain git instead:\n    ${pc.green(`git branch -m ${oldName} ${newName}`)}`,
+    );
+    process.exit(1);
+  }
+
+  const hadPr = meta.stacks[stackName]?.branches[oldName]?.pr;
+
+  // ── Confirm ──
+  const ok = await confirmAction(
+    `Rename ${pc.yellow(oldName)} → ${pc.green(newName)} (stack: ${stackName})?`,
+  );
+  if (!ok) {
+    p.cancel("Rename cancelled.");
+    return;
+  }
+
+  // ── Rename + persist ──
+  if (!(await git.renameBranch(oldName, newName))) {
+    p.cancel(`git failed to rename ${pc.yellow(oldName)} → ${pc.yellow(newName)}.`);
+    process.exit(1);
+  }
+
+  // Re-read so reconcileRenames re-keys the topology from the (moved) config,
+  // then write it back to persist the new name + repoint child config.
+  const updated = await readMetadata();
+  if (!updated) {
+    p.cancel("Renamed the branch, but failed to re-read metadata.");
+    process.exit(1);
+  }
+  await writeMetadata(updated);
+
+  p.log.success(`Renamed ${pc.yellow(oldName)} → ${pc.green(newName)}`);
+
+  if (hadPr) {
+    p.log.warn(
+      `PR ${pc.cyan(`#${hadPr}`)} still tracks the old remote branch ${pc.dim(oldName)}.\n` +
+        `  This rename was local only — update the PR's branch on GitHub if needed.`,
+    );
+  }
+}

package/src/commands/split.ts

@@ -12,7 +12,12 @@
 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 {
+  ensureMetadata,
+  ensureCurrentStack,
+  ensureValidStack,
+  resolveStackForBranchArg,
+} from "../lib/safety.ts";
 import { selectBranch, confirmAction } from "../lib/ui.ts";
 import * as git from "../lib/git.ts";
 import type { Stack } from "../types.ts";
@@ -55,7 +60,12 @@ export default async function split(args: string[]): Promise<void> {
   const positional = args.filter((a) => !a.startsWith("-"));
 
   const meta = await ensureMetadata();
-  const stackName = ensureCurrentStack(meta);
+  // The cut branch names its own stack — resolve from it so `split <branch>`
+  // works from anywhere. Only fall back to the current stack (the branch you're
+  // on) in interactive mode, when no branch was given.
+  const stackName = positional[0]
+    ? resolveStackForBranchArg(meta, positional[0]!)
+    : ensureCurrentStack(meta);
   await ensureValidStack(meta, stackName);
   const stack = meta.stacks[stackName]!;
   const currentBranch = await git.currentBranch();

package/src/commands/stacks.ts

@@ -0,0 +1,138 @@
+// gh-stack stacks — List all stacks and their topology (network-free).
+//
+// This is the machine-readable interface to stack metadata: `--json` emits the
+// full topology (stacks, ordered branches, PR numbers, base) so external tools
+// never have to reach into `.git/.gh-stack/` and parse the storage format
+// themselves. It performs NO network calls and does NOT mutate metadata.
+import pc from "picocolors";
+import * as git from "../lib/git.ts";
+import {
+  readMetadata,
+  metadataExists,
+  legacyMetadataExists,
+  getOrderedBranches,
+  stackBase,
+} from "../lib/metadata.ts";
+
+export default async function stacks(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(`
+gh-stack stacks — List all stacks and their topology
+
+USAGE
+  gh-stack stacks [options]
+
+OPTIONS
+  --json       Output topology as JSON (for tools/scripts; no network calls)
+  --current    Only the stack containing the current branch
+
+Read-only and network-free — emits stack membership straight from local
+metadata. Use --json as a stable interface so scripts don't parse the
+.git/.gh-stack/ store directly.
+`);
+    return;
+  }
+
+  const jsonMode = args.includes("--json");
+  const currentOnly = args.includes("--current");
+
+  // Read-only: don't hard-block on unmigrated v2 metadata — just note it to
+  // stderr (keeps stdout/JSON clean) and emit an empty result.
+  if (!(await metadataExists())) {
+    if (await legacyMetadataExists()) {
+      process.stderr.write("Note: stack metadata is unmigrated (v2). Run `gh-stack doctor`.\n");
+    }
+    if (jsonMode) {
+      console.log(
+        JSON.stringify({ current_stack: null, current_branch: null, stacks: [] }, null, 2),
+      );
+    } else {
+      console.log("No stacks found.");
+    }
+    return;
+  }
+
+  const meta = await readMetadata();
+  if (!meta) {
+    if (jsonMode) {
+      console.log(
+        JSON.stringify({ current_stack: null, current_branch: null, stacks: [] }, null, 2),
+      );
+    } else {
+      console.log("No stacks found.");
+    }
+    return;
+  }
+
+  let currentBranch: string | null = null;
+  try {
+    currentBranch = await git.currentBranch();
+  } catch {
+    // Detached HEAD or not on a branch — fine, just no "current" context.
+  }
+
+  // readMetadata already resolved the current stack authoritatively: the
+  // branch's own stack, or — for a new branch built on top of one — the nearest
+  // tracked ancestor's stack, or null. Trust it rather than re-deriving.
+  const currentStackName = meta.current_stack;
+
+  const entries = Object.entries(meta.stacks)
+    .filter(([name]) => !currentOnly || name === currentStackName)
+    .map(([name, stack]) => {
+      const ordered = getOrderedBranches(stack);
+      return {
+        name,
+        description: stack.description || "",
+        base: stackBase(stack),
+        is_current: name === currentStackName,
+        branches: ordered.map((branchName) => {
+          const b = stack.branches[branchName]!;
+          return {
+            branch: branchName,
+            parent: b.parent,
+            pr: b.pr ?? null,
+            description: b.description ?? null,
+          };
+        }),
+      };
+    });
+
+  if (jsonMode) {
+    console.log(
+      JSON.stringify(
+        {
+          current_stack: currentStackName,
+          current_branch: currentBranch,
+          stacks: entries,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  // ── Human-readable ──
+  if (entries.length === 0) {
+    console.log(currentOnly ? "Current branch is not in a stack." : "No stacks found.");
+    return;
+  }
+
+  console.log();
+  for (const stack of entries) {
+    const marker = stack.is_current ? pc.yellow(" (current)") : "";
+    console.log(`${pc.blue("📚")} ${pc.yellow(stack.name)}${marker} ${pc.dim(`→ ${stack.base}`)}`);
+    if (stack.description) {
+      console.log(`   ${pc.dim(stack.description)}`);
+    }
+    for (let i = 0; i < stack.branches.length; i++) {
+      const b = stack.branches[i]!;
+      const isLast = i === stack.branches.length - 1;
+      const tree = isLast ? "┗━" : "┣━";
+      const prNum = b.pr ? pc.dim(`#${b.pr}`) : pc.dim("(no PR)");
+      const cur = currentBranch === b.branch ? pc.yellow(" 👈") : "";
+      console.log(`   ${tree} ${i + 1}. ${b.branch} ${prNum}${cur}`);
+    }
+    console.log();
+  }
+}

package/src/index.ts

@@ -73,6 +73,10 @@ switch (command) {
     await (await import("./commands/split.ts")).default(commandArgs);
     break;
 
+  case "rename":
+    await (await import("./commands/rename.ts")).default(commandArgs);
+    break;
+
   case "checkout":
   case "co":
     await (await import("./commands/checkout.ts")).default(commandArgs);
@@ -115,6 +119,10 @@ switch (command) {
     await (await import("./commands/update-prs.ts")).default(commandArgs);
     break;
 
+  case "stacks":
+    await (await import("./commands/stacks.ts")).default(commandArgs);
+    break;
+
   case "archive":
     await (await import("./commands/archive.ts")).default(commandArgs);
     break;
@@ -172,12 +180,14 @@ ${bold("STACK NAVIGATION")}
   ${green("top")}            Jump to the tip of the stack
   ${green("bottom")}         Jump to the base of the stack
   ${green("ls")}             List branches with numbers
+  ${green("stacks")}         List all stacks (--json for tools)
 
 ${bold("STACK MANAGEMENT")}
   ${green("restack")}        Rebase children onto updated parents
   ${green("sync")}           Sync base with main + restack all
   ${green("merge")}          Local squash-merge top-down
   ${green("split")}          Cut a stack into two at a branch
+  ${green("rename")}         Rename a tracked branch (keeps metadata in sync)
   ${green("delete")}         Remove a branch from the stack
 
 ${bold("INFO & MAINTENANCE")}

package/src/lib/branch-config.ts

@@ -6,6 +6,7 @@
 //   branch.<name>.ghstack-stack   <stack>
 //   branch.<name>.ghstack-parent  <parent-branch>
 //   branch.<name>.ghstack-pr      <number>
+//   branch.<name>.ghstack-id      <uuid>  (stable identity; survives rename)
 //
 // Why config and not JSON: git maintains the `branch.<name>` section for us.
 //   • `git branch -m old new`  → the section moves      → rename tracking free
@@ -23,12 +24,14 @@ export interface BranchMembership {
   stack?: string;
   parent?: string;
   pr?: number;
+  id?: string;
 }
 
 const KEY_PREFIX = "ghstack-";
 const STACK_KEY = "ghstack-stack";
 const PARENT_KEY = "ghstack-parent";
 const PR_KEY = "ghstack-pr";
+const ID_KEY = "ghstack-id";
 
 function configKey(branch: string, key: string): string {
   return `branch.${branch}.${key}`;
@@ -46,6 +49,7 @@ export async function setBranchMembership(
   await setOrUnset(branch, STACK_KEY, membership.stack);
   await setOrUnset(branch, PARENT_KEY, membership.parent);
   await setOrUnset(branch, PR_KEY, membership.pr != null ? String(membership.pr) : undefined);
+  await setOrUnset(branch, ID_KEY, membership.id);
 }
 
 async function setOrUnset(branch: string, key: string, value: string | undefined): Promise<void> {
@@ -78,6 +82,7 @@ export async function clearBranchMembership(branch: string): Promise<void> {
   await unsetKey(branch, STACK_KEY);
   await unsetKey(branch, PARENT_KEY);
   await unsetKey(branch, PR_KEY);
+  await unsetKey(branch, ID_KEY);
 }
 
 /**
@@ -115,6 +120,7 @@ export async function allBranchMemberships(): Promise<Map<string, BranchMembersh
     const m = out.get(branch) ?? {};
     if (field === STACK_KEY) m.stack = value;
     else if (field === PARENT_KEY) m.parent = value;
+    else if (field === ID_KEY) m.id = value;
     else if (field === PR_KEY) {
       const n = Number(value);
       if (Number.isFinite(n)) m.pr = n;

package/src/lib/git.ts

@@ -179,6 +179,16 @@ export async function deleteLocalBranch(branch: string): Promise<boolean> {
   return exitCode === 0;
 }
 
+/**
+ * Rename a local branch (`git branch -m`). Git moves the whole `branch.<old>`
+ * config section to `branch.<new>`, so gh-stack membership rides along for free.
+ * Returns false if the rename failed (e.g. the new name already exists).
+ */
+export async function renameBranch(oldName: string, newName: string): Promise<boolean> {
+  const { exitCode } = await $`git branch -m ${oldName} ${newName}`.nothrow().quiet();
+  return exitCode === 0;
+}
+
 /**
  * Delete a branch on the remote (origin). Returns false on failure.
  */

package/src/lib/github.ts

@@ -150,19 +150,63 @@ export async function getPrBody(prNumber: number): Promise<string | null> {
 
 /**
  * Get the merge state of a PR.
- * Returns { state, mergeable, mergeStateStatus }.
+ * Returns { state, mergeable, mergeStateStatus, headRefName, headRefOid }.
+ *
+ * NOTE: `mergeable`/`mergeStateStatus` are computed against the PR's *recorded*
+ * head (`headRefOid`), which GitHub occasionally fails to advance after a child
+ * squash-merge lands on this branch. Compare `headRefOid` against the live ref
+ * (`getBranchRefSha`) to detect that staleness — see `merge.ts`.
  */
-export async function getPrMergeState(
-  prNumber: number,
-): Promise<{ state: string; mergeable: string; mergeStateStatus: string } | null> {
+export async function getPrMergeState(prNumber: number): Promise<{
+  state: string;
+  mergeable: string;
+  mergeStateStatus: string;
+  headRefName: string;
+  headRefOid: string;
+} | null> {
   try {
-    const result = await $`gh pr view ${prNumber} --json state,mergeable,mergeStateStatus`.text();
+    const result =
+      await $`gh pr view ${prNumber} --json state,mergeable,mergeStateStatus,headRefName,headRefOid`.text();
     return JSON.parse(result.trim());
   } catch {
     return null;
   }
 }
 
+/**
+ * Resolve the live SHA of a branch ref on the remote (`origin`), independent of
+ * any PR's cached head. Returns null if the ref can't be resolved.
+ */
+export async function getBranchRefSha(branch: string): Promise<string | null> {
+  const nwo = await getRepoNwo();
+  if (!nwo) return null;
+  try {
+    const sha = (
+      await $`gh api repos/${nwo}/git/ref/heads/${branch} --jq .object.sha`.text()
+    ).trim();
+    return sha.length > 0 ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Force GitHub to re-read a PR's head branch by closing and immediately
+ * reopening it. Used when the PR's recorded `headRefOid` is stuck behind the
+ * live branch tip (a child squash-merge moved the branch but GitHub missed the
+ * head-sync), which makes `mergePullRequest` reject a "Head branch is out of
+ * date" even though every status read says the PR is clean.
+ */
+export async function resyncPrHead(prNumber: number): Promise<boolean> {
+  try {
+    await $`gh pr close ${prNumber}`.quiet();
+    await $`gh pr reopen ${prNumber}`.quiet();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Close a PR with a comment.
  */

package/src/lib/metadata.ts

@@ -31,6 +31,7 @@ import {
   type BranchMembership,
 } from "./branch-config.ts";
 import { loadSnapshots } from "./snapshot.ts";
+import * as git from "./git.ts";
 
 async function pathExists(p: string): Promise<boolean> {
   try {
@@ -131,9 +132,96 @@ export async function readMetadata(): Promise<StackMetadata | null> {
   if (snapshots.length > 0) meta.snapshots = snapshots;
 
   backfillStackBase(meta);
+  // Catch the name-keyed JSON up to any `git branch -m` since the last write.
+  // In-memory only — the fix persists the next time a command writes metadata
+  // (which also repoints renamed branches' child config). Keeping reads
+  // side-effect-free avoids surprising writes from `status`/`--dry-run`.
+  await reconcileRenames(meta);
+  // The current stack is *derived* from the branch you're on, never trusted
+  // from the stored hint. Every read re-verifies it (and corrects the on-disk
+  // pointer) so no command can act on a stack you've already left.
+  await reconcileCurrentStack(meta);
   return meta;
 }
 
+/**
+ * Resolve and pin `meta.current_stack` to whichever active stack owns the
+ * checked-out branch — the single source of truth for "what stack am I on."
+ *
+ * Resolution, mirroring the on-disk authority order:
+ *   1. The branch's git config (`branch.<name>.ghstack-stack`) — rename-proof
+ *      membership — *if* the named stack is active and still lists the branch.
+ *   2. Otherwise scan the assembled active stacks for the branch by name.
+ *   3. Otherwise walk up the branch's ancestry: a new branch built on top of a
+ *      stack belongs to that stack (until submitted), so the nearest *tracked*
+ *      ancestor's stack is the current one. Only tracked branches are probed,
+ *      so this stays cheap even with many local branches.
+ *   4. Otherwise (ancestry reaches trunk with nothing tracked, or HEAD
+ *      detached) there is no current stack → null.
+ *
+ * The resolved value is also written back to the `current` pointer file when it
+ * drifts, so a stale hint left by a prior session, a merge, or a plain
+ * `git checkout` self-heals on the very next command. Only the pointer file is
+ * touched — stack topology, refs, and snapshots are never written here, so this
+ * stays safe for read-only / `--dry-run` commands.
+ */
+async function reconcileCurrentStack(meta: StackMetadata): Promise<void> {
+  let branch: string | null = null;
+  try {
+    branch = await git.currentBranch();
+  } catch {
+    // Detached HEAD / not on a branch → no current stack.
+  }
+
+  let resolved: string | null = null;
+  if (branch) {
+    // 1. Trust branch config only if the topology still backs it up.
+    const config = await allBranchMemberships();
+    const configStack = config.get(branch)?.stack;
+    if (configStack && meta.stacks[configStack]?.branches[branch]) {
+      resolved = configStack;
+    } else {
+      // 2. Fall back to scanning the active stacks for direct membership.
+      resolved = findStackForBranch(meta, branch);
+    }
+    // 3. Untracked branch — inherit the stack of its nearest tracked ancestor.
+    if (!resolved) {
+      resolved = await nearestTrackedAncestorStack(meta, branch);
+    }
+  }
+
+  if (meta.current_stack !== resolved) {
+    meta.current_stack = resolved;
+    await Bun.write(await currentFile(), (resolved ?? "") + "\n");
+  }
+}
+
+/**
+ * Walk up `branch`'s ancestry and return the stack of the nearest branch that's
+ * already a tracked member of an active stack — i.e. the stack this branch sits
+ * on top of. Probes only tracked branches (small N), picking the closest one by
+ * commit distance, so a chain that spans two stacks resolves to the nearer one.
+ * Returns null when no tracked branch is an ancestor (the branch traces back to
+ * trunk without crossing a stack).
+ */
+export async function nearestTrackedAncestorStack(
+  meta: StackMetadata,
+  branch: string,
+): Promise<string | null> {
+  let best: { stack: string; distance: number } | null = null;
+  for (const [stackName, stack] of Object.entries(meta.stacks)) {
+    for (const member of Object.keys(stack.branches)) {
+      if (member === branch) continue;
+      if (!(await git.isAncestor(member, branch))) continue;
+      const distance = await git.commitCount(member, branch);
+      if (distance > 0 && (!best || distance < best.distance)) {
+        best = { stack: stackName, distance };
+      }
+    }
+  }
+  return best?.stack ?? null;
+}
+
 /**
  * The ref a stack is rooted on. Defaults to "main" for stacks created before
  * the `base` field existed.
@@ -170,6 +258,10 @@ function serializeStack(stack: Stack): string {
 export async function writeMetadata(meta: StackMetadata): Promise<void> {
   await ensureDirs();
 
+  // 0. stamp a stable id on any active branch that lacks one, so a later
+  //    `git branch -m` can be recognized even before the branch has a PR.
+  ensureBranchIds(meta);
+
   // 1. current hint
   await Bun.write(await currentFile(), (meta.current_stack ?? "") + "\n");
 
@@ -237,7 +329,7 @@ async function syncBranchConfig(meta: StackMetadata): Promise<void> {
   const desired = new Map<string, BranchMembership>();
   for (const [stackName, stack] of Object.entries(meta.stacks)) {
     for (const [branchName, b] of Object.entries(stack.branches)) {
-      desired.set(branchName, { stack: stackName, parent: b.parent, pr: b.pr });
+      desired.set(branchName, { stack: stackName, parent: b.parent, pr: b.pr, id: b.id });
     }
   }
 
@@ -245,7 +337,13 @@ async function syncBranchConfig(meta: StackMetadata): Promise<void> {
 
   for (const [branch, m] of desired) {
     const cur = existing.get(branch);
-    if (!cur || cur.stack !== m.stack || cur.parent !== m.parent || cur.pr !== m.pr) {
+    if (
+      !cur ||
+      cur.stack !== m.stack ||
+      cur.parent !== m.parent ||
+      cur.pr !== m.pr ||
+      cur.id !== m.id
+    ) {
       await setBranchMembership(branch, m);
     }
   }
@@ -256,6 +354,100 @@ async function syncBranchConfig(meta: StackMetadata): Promise<void> {
   }
 }
 
+/**
+ * Stamp a stable UUID on every active branch that lacks one. Mutates `meta`;
+ * the ids persist via the normal stack-file write and get mirrored into git
+ * config by `syncBranchConfig`. A branch's id is its rename anchor.
+ */
+function ensureBranchIds(meta: StackMetadata): void {
+  for (const stack of Object.values(meta.stacks)) {
+    for (const b of Object.values(stack.branches)) {
+      if (!b.id) b.id = crypto.randomUUID();
+    }
+  }
+}
+
+/**
+ * Reconcile the name-keyed JSON after a branch was renamed with `git branch -m`.
+ *
+ * Git moves a branch's entire `branch.<name>` config section on rename, so the
+ * membership config is rename-proof and authoritative for identity; only the
+ * JSON (keyed by branch name) drifts. For each branch the config currently knows
+ * by name N, if the JSON has no entry under N but does have one — in the same
+ * stack — matching N's stable id (or, for legacy/pre-id branches, its PR
+ * number), that entry was renamed: re-key it to N and repoint anything that
+ * referenced the old name.
+ *
+ * Mutates `meta` in place; returns true if anything changed. The change persists
+ * on the next `writeMetadata`, which also repoints the renamed branch's child
+ * `ghstack-parent` config (git rewrites section names, not string values).
+ */
+async function reconcileRenames(meta: StackMetadata): Promise<boolean> {
+  const config = await allBranchMemberships();
+  if (config.size === 0) return false;
+
+  let changed = false;
+  for (const [currentName, m] of config) {
+    if (!m.stack) continue;
+    const stack = meta.stacks[m.stack];
+    if (!stack) continue;
+    if (stack.branches[currentName]) continue; // JSON already keyed correctly
+
+    const oldKey = findStaleKey(stack, m);
+    if (!oldKey || oldKey === currentName) continue;
+
+    renameBranchKey(meta, m.stack, oldKey, currentName);
+    changed = true;
+  }
+  return changed;
+}
+
+/** Find a stack's branch entry by stable id (preferred) or PR number (fallback). */
+function findStaleKey(stack: Stack, m: BranchMembership): string | null {
+  if (m.id) {
+    for (const [name, b] of Object.entries(stack.branches)) {
+      if (b.id === m.id) return name;
+    }
+  }
+  if (m.pr != null) {
+    for (const [name, b] of Object.entries(stack.branches)) {
+      if (b.pr === m.pr) return name;
+    }
+  }
+  return null;
+}
+
+/**
+ * Re-key a branch from `oldKey` to `newKey` and repoint every reference to the
+ * old name: the stack's `last_branch`, and any branch's `parent` or stack's
+ * `base` (across active AND archived stacks — a split stack roots on a branch
+ * that belongs to its parent stack).
+ */
+function renameBranchKey(
+  meta: StackMetadata,
+  stackName: string,
+  oldKey: string,
+  newKey: string,
+): void {
+  const stack = meta.stacks[stackName];
+  if (!stack) return;
+  const entry = stack.branches[oldKey];
+  if (!entry) return;
+
+  stack.branches[newKey] = entry;
+  delete stack.branches[oldKey];
+  if (stack.last_branch === oldKey) stack.last_branch = newKey;
+
+  for (const group of [meta.stacks, meta.archive ?? {}]) {
+    for (const s of Object.values(group)) {
+      if (s.base === oldKey) s.base = newKey;
+      for (const b of Object.values(s.branches)) {
+        if (b.parent === oldKey) b.parent = newKey;
+      }
+    }
+  }
+}
+
 /**
  * Initialize an empty v3 store.
  */

package/src/lib/safety.ts

@@ -71,6 +71,23 @@ export function ensureCurrentStack(meta: StackMetadata): string {
   return stack;
 }
 
+/**
+ * Resolve the stack to operate on from a branch argument. The branch names its
+ * own stack unambiguously, so commands that take a branch (split, delete) use
+ * this instead of trusting the current stack — letting `<cmd> <branch>` work
+ * from anywhere, not only while standing on that stack.
+ */
+export function resolveStackForBranchArg(meta: StackMetadata, branch: string): string {
+  const stackName = findStackForBranch(meta, branch);
+  if (!stackName) {
+    p.cancel(
+      `Branch ${pc.yellow(branch)} is not in any stack.\n\n  See your stacks with:\n    ${pc.green("gh-stack stacks")}`,
+    );
+    process.exit(1);
+  }
+  return stackName;
+}
+
 /**
  * Ensure current branch is in a stack. Returns the stack name.
  */

package/src/types.ts

@@ -31,6 +31,13 @@ export interface Branch {
   pr?: number; // GitHub PR number
   description?: string; // Human-readable label
 
+  // Stable per-branch identity (UUID), stamped on first write and mirrored into
+  // git config as `branch.<name>.ghstack-id`. Because `git branch -m` moves the
+  // whole config section but the JSON is keyed by name, this id is what lets us
+  // recognize a renamed branch and re-key its (now-stale) JSON entry — even
+  // before it has a PR number to match on. See metadata.ts `reconcileRenames`.
+  id?: string;
+
   // ── submit caches (v0.9.0, issue #16) ──
   // Let `submit` skip redundant network calls when nothing relevant changed.
   prTitle?: string; // last-known GitHub PR title, for rendering the stack viz without a fetch