gh-stack 0.10.0 → 0.12.0

package/README.md

@@ -85,8 +85,9 @@ create <branch-name> [--description <desc>]
 
 submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file <f>] [--dry-run]
     Push all downstack branches to GitHub, create PRs for branches
-    that don't have them, and update all PR descriptions with stack
-    visualization. Idempotent — safe to run repeatedly.
+    that don't have them, number each PR title with its stack position
+    `(N/M)`, and update all PR descriptions with stack visualization.
+    Idempotent — safe to run repeatedly.
 
     Self-healing: if the current branch isn't tracked in a stack yet,
     submit auto-detects the chain from trunk → current, registers (or
@@ -163,11 +164,13 @@ merge [--dry-run] [-d|--delete-branch] [--collapse]
                 `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
@@ -189,9 +192,11 @@ rename [<old-name>] <new-name>
     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.
 ```
@@ -203,6 +208,11 @@ 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
@@ -270,19 +280,36 @@ gh-stack solves this by snapshotting every branch's tip **before** any destructi
 
 Snapshots also power `gh-stack undo`, so the same data structure does double duty.
 
+### Stack Position in PR Titles
+
+`submit` keeps each PR's **title** suffixed with its stack position as `(N/M)`,
+so you can see the order from a bare "needs your review" list — where only
+titles show, not descriptions — and review bottom-up:
+
+```
+feat(paid-subs): tiers overview list [BEE-20531] (1/4)
+feat(paid-subs): tier detail page [BEE-20550] (2/4)
+feat(paid-subs): tier create wizard [BEE-20579] (3/4)
+feat(paid-subs): advanced settings step [BEE-20587] (4/4)
+```
+
+Parentheses (not brackets) avoid colliding with `[BEE-1234]` ticket tags. It's
+self-healing and idempotent: re-running `submit` after adding or reordering a
+branch renumbers the whole stack, and a no-op re-submit changes nothing. The
+position is the only managed part of the title — your text (and ticket tags)
+are preserved. Single-PR stacks get no suffix.
+
 ### Stack Visualization
 
-`submit` automatically adds a stack section to all PR descriptions, with each
-branch numbered by its position in the stack (handy for spotting "which one is
-PR 6 of 12"):
+`submit` also adds a stack section to every PR description:
 
 ```
 ### 📚 Stacked on
 ⚫ main
 ┃
-┣━ 1. #123 Backend models
+┣━ #123 feat: backend models (1/2)
 ┃
-┗━ 2. #124 Frontend UI 👈
+┗━ #124 feat: frontend UI (2/2) 👈
 ```
 
 The block is rendered entirely from local metadata plus one repo-identity
@@ -299,7 +326,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)
@@ -337,8 +364,10 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gh-stack",
-  "version": "0.10.0",
+  "version": "0.12.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

@@ -513,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/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

@@ -11,7 +11,6 @@ import {
   metadataExists,
   legacyMetadataExists,
   getOrderedBranches,
-  findStackForBranch,
   stackBase,
 } from "../lib/metadata.ts";
 
@@ -72,7 +71,10 @@ metadata. Use --json as a stable interface so scripts don't parse the
     // Detached HEAD or not on a branch — fine, just no "current" context.
   }
 
-  const currentStackName = currentBranch ? findStackForBranch(meta, currentBranch) : null;
+  // 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)
@@ -99,7 +101,7 @@ metadata. Use --json as a stable interface so scripts don't parse the
     console.log(
       JSON.stringify(
         {
-          current_stack: currentStackName ?? meta.current_stack ?? null,
+          current_stack: currentStackName,
           current_branch: currentBranch,
           stacks: entries,
         },

package/src/commands/submit.ts

@@ -13,7 +13,7 @@ import { isAutoYes } from "../lib/ui.ts";
 import type { StackMetadata } from "../types.ts";
 import { getPrNumber } from "../lib/github.ts";
 import { resolveOrCreateStack } from "../lib/chain.ts";
-import { refreshStackViz, branchToTitle } from "./update-prs.ts";
+import { reconcilePrTitles, refreshStackViz, branchToTitle } from "./update-prs.ts";
 
 const HELP = `
 gh-stack submit — Push branches and create/update PRs
@@ -353,14 +353,17 @@ export default async function submit(args: string[]): Promise<void> {
     return;
   }
 
-  // ── Phase 2: Refresh the stack visualization (renders locally, PATCHes only
-  // the PRs whose block actually changed; see issue #16). ──
-  p.log.info(pc.cyan("Updating stack visualization..."));
+  // ── Phase 2: Reconcile PR titles (stack position) then refresh the stack
+  // visualization. Titles first so the viz renders the numbered titles. Both
+  // render locally and only hit the network for PRs that actually changed
+  // (see issue #16), so a no-op re-submit is free. ──
+  p.log.info(pc.cyan("Updating PR titles & stack visualization..."));
+  const titles = await reconcilePrTitles(stack, ordered);
   const viz = await refreshStackViz(meta, stack, ordered);
 
   // One persist for everything we cached this run (discovered PRs, base edits,
-  // backfilled titles, viz hashes).
-  if (metadataChanged || viz.dirty) {
+  // backfilled/renumbered titles, viz hashes).
+  if (metadataChanged || titles.dirty || viz.dirty) {
     await writeMetadata(meta);
   }
 
@@ -368,7 +371,7 @@ export default async function submit(args: string[]): Promise<void> {
   console.log();
   p.outro(
     pc.green(
-      `Done! Pushed ${pushed} branch(es), created ${created} PR(s), updated ${viz.updated} description(s)` +
+      `Done! Pushed ${pushed} branch(es), created ${created} PR(s), updated ${viz.updated} description(s), ${titles.updated} title(s)` +
         (viz.unchanged > 0 ? `, ${viz.unchanged} unchanged` : ""),
     ),
   );

package/src/commands/update-prs.ts

@@ -16,8 +16,15 @@ import {
   writeMetadata,
 } from "../lib/metadata.ts";
 import { ensureMetadata } from "../lib/safety.ts";
-import { getPrInfo, getPrBody, updatePrBody, getRepoNwo, prUrlFor } from "../lib/github.ts";
-import type { StackMetadata, Stack } from "../types.ts";
+import {
+  getPrInfo,
+  getPrBody,
+  updatePrBody,
+  updatePrTitle,
+  getRepoNwo,
+  prUrlFor,
+} from "../lib/github.ts";
+import type { StackMetadata, Stack, Branch } from "../types.ts";
 
 /** The ref a stack is rooted on, for rendering the base node of the viz. */
 export interface BaseRef {
@@ -103,6 +110,66 @@ function mergeViz(body: string, viz: string): string {
   return base ? `${base}\n\n${viz}` : viz;
 }
 
+// ── PR-title stack numbering ──
+//
+// The stack position lives in the PR title as a ` (N/M)` suffix so reviewers
+// can see order from a bare "needs review" list (parens, not brackets, to avoid
+// colliding with `[BEE-1234]` ticket tags). The cached `prTitle` tracks exactly
+// what's on GitHub; we recover the base title by stripping the suffix and
+// re-applying the current position, so reordering/adding a branch renumbers the
+// whole stack and a no-op re-submit touches nothing.
+
+/** Matches a trailing ` (N/M)` stack-position suffix, e.g. " (2/4)". */
+const SEQ_SUFFIX = /\s*\(\d+\/\d+\)\s*$/;
+
+/** Strip a trailing ` (N/M)` suffix to recover the base PR title. */
+export function stripSeqSuffix(title: string): string {
+  return title.replace(SEQ_SUFFIX, "").trimEnd();
+}
+
+/** The title a branch at `position` of `total` should have. Idempotent. */
+export function numberedTitle(title: string, position: number, total: number): string {
+  const base = stripSeqSuffix(title);
+  return total >= 2 ? `${base} (${position}/${total})` : base;
+}
+
+export interface TitleResult {
+  updated: number; // PR titles we edited on GitHub
+  dirty: boolean; // metadata mutated (cached prTitle changed) — caller persists
+}
+
+/**
+ * Reconcile every PR title in the stack to carry its `(N/M)` stack position.
+ * Backfills any missing cached titles first (so we never clobber a real GitHub
+ * title with a branch-name guess), renders the desired title from the cached
+ * one, and only calls `gh pr edit --title` when it actually changed — a no-op
+ * re-submit makes zero edits, while adding/reordering a branch renumbers the
+ * whole stack. Run this BEFORE refreshStackViz so the viz shows numbered titles.
+ */
+export async function reconcilePrTitles(stack: Stack, ordered: string[]): Promise<TitleResult> {
+  const dirtyBackfill = await backfillTitles(stack, ordered);
+  const total = ordered.length;
+
+  const plans: { pr: number; desired: string; bm: Branch }[] = [];
+  for (let i = 0; i < ordered.length; i++) {
+    const bm = stack.branches[ordered[i]!]!;
+    // Need a known base title — never guess from the branch name for an
+    // existing PR (backfill couldn't fetch it → skip rather than clobber).
+    if (bm.pr == null || !bm.prTitle) continue;
+    const desired = numberedTitle(bm.prTitle, i + 1, total);
+    if (desired !== bm.prTitle) plans.push({ pr: bm.pr, desired, bm });
+  }
+
+  const oks = await mapLimit(plans, 8, async (plan) => {
+    const ok = await updatePrTitle(plan.pr, plan.desired);
+    if (ok) plan.bm.prTitle = plan.desired;
+    return ok;
+  });
+
+  const updated = oks.filter(Boolean).length;
+  return { updated, dirty: dirtyBackfill || updated > 0 };
+}
+
 export interface VizResult {
   updated: number; // PRs whose description we PATCHed
   unchanged: number; // PRs skipped because their rendered block was identical
@@ -192,16 +259,17 @@ PRs whose rendered block is unchanged are skipped; --force rewrites all.
   console.log();
 
   const s = p.spinner();
-  s.start("Updating PR descriptions...");
+  s.start("Updating PR titles & descriptions...");
+  const titles = await reconcilePrTitles(stack, ordered);
   const result = await refreshStackViz(meta, stack, ordered, { force });
   s.stop("Done");
 
-  if (result.dirty) await writeMetadata(meta);
+  if (titles.dirty || result.dirty) await writeMetadata(meta);
 
   console.log();
   p.outro(
     pc.green(
-      `Updated ${result.updated} PR(s)` +
+      `Updated ${result.updated} description(s), ${titles.updated} title(s)` +
         (result.unchanged > 0 ? `, ${result.unchanged} unchanged` : "") +
         (result.skipped > 0 ? `, ${result.skipped} without PRs` : ""),
     ),
@@ -249,9 +317,9 @@ export function buildStackViz(
     // Tree character
     const tree = isLast ? "┗━" : "┣━";
 
-    // Leading `N.` is the branch's 1-based position in the stack — makes it
-    // easy to tell which PR is #6 in a 12-PR stack at a glance.
-    lines.push(`${tree} ${i + 1}. ${prLink} ${info.prTitle}${marker}`);
+    // No leading `N.` — the stack position now lives in the PR title itself as
+    // a `(N/M)` suffix (see reconcilePrTitles), so the tree just shows titles.
+    lines.push(`${tree} ${prLink} ${info.prTitle}${marker}`);
 
     if (!isLast) {
       lines.push("┃");

package/src/lib/github.ts

@@ -136,6 +136,18 @@ export async function updatePrBody(prNumber: number, body: string): Promise<bool
   }
 }
 
+/**
+ * Update a PR's title.
+ */
+export async function updatePrTitle(prNumber: number, title: string): Promise<boolean> {
+  try {
+    await $`gh pr edit ${prNumber} --title ${title}`.quiet();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Get PR body text.
  */

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 {
@@ -136,9 +137,91 @@ export async function readMetadata(): Promise<StackMetadata | null> {
   // (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.

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.
  */