gh-stack 0.9.0 → 0.10.0

package/README.md

@@ -154,7 +154,9 @@ 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
@@ -173,6 +175,19 @@ 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
     delete the underlying local git branch (and the remote branch if
@@ -188,8 +203,25 @@ log
     Display the current stack as a tree with branch numbers,
     PR info, and descriptions. This is the default command.
 
+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)
 
@@ -296,6 +328,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
@@ -307,6 +340,12 @@ any drift. Why this shape:
 - **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 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.10.0",
   "description": "Stacked PR manager for squash-merge workflows",
   "author": "Kiliman <kiliman@gmail.com>",
   "license": "MIT",

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`)}`);
   }
 

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/stacks.ts

@@ -0,0 +1,136 @@
+// 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,
+  findStackForBranch,
+  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.
+  }
+
+  const currentStackName = currentBranch ? findStackForBranch(meta, currentBranch) : null;
+
+  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 ?? meta.current_stack ?? null,
+          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

@@ -131,6 +131,11 @@ 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);
   return meta;
 }
 
@@ -170,6 +175,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 +246,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 +254,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 +271,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/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