fix(stacks): resolve GitHub stack membership by checkout identity, not branch name

The Stacks view matched a stack purely by `git branch --show-current`, so
switching to a PR (review worktree, detached HEAD, `gh pr checkout`/rename)
never resolved a stack even though the checkout was clearly a member. Detect
via a precedence-ordered identity match instead: PR number (parsed from a
`pr/<n>-review` branch) > branch name > upstream ref > HEAD commit sha,
falling back to a target-only match, with dissolved (`open: false`) stacks
excluded. Also derive per-member status (open/draft/merged/closed) and a
local "Blocked downstack" approximation, since the Stacks API doesn't report
per-PR mergeability, and fix a stale-view race and a leaked debounce timer
in the refresh path.

Restyle the Stacks webview rows to match GitHub's own stack map: a status
icon + badge per PR, dimmed merged/closed rows, and the target rendered as a
code chip.

Author: Test

README.md

@@ -41,7 +41,7 @@ All commands are grouped under the `GSC:` prefix in the Command Palette.
 | Open a terminal in a selected worktree's directory | `GSC: Open Worktree Dev Terminal...` | [Open worktree dev terminal](docs/open-worktree-dev-terminal.md) |
 | Remove several Git worktrees at once with a single confirmation | `GSC: Remove Multiple Worktrees...` | [Remove multiple worktrees](docs/remove-multiple-worktrees.md) |
 | Browse all worktrees for the open repositories in a dedicated "Worktrees" view (activity bar), with dirty/ahead-behind/PR-review status, last commit + relative age, an upstream-gone flag with a dedicated inline Remove action, an auto-stash marker, live refresh on external git activity, and a badge showing the count of dirty worktrees, plus inline Open/Terminal/Copy WIP/Remove actions | *(tree view — right-click an item for Add to Workspace, Copy Path, Reveal in Finder/Explorer)* | — |
-| Detect the GitHub-native [stacked PR](https://docs.github.com/en/rest/pulls/stacks) chain the current branch belongs to, and browse it in a dedicated "Stacks" view (activity bar) showing each PR's title and branch plus the branch the stack is ultimately targeting. Click a row (or its target chip) to check it out using the currently selected checkout/stash strategy; right-click for "Open PR in Browser". Nothing is cached — an in-view refresh icon re-checks live at any time. A status bar indicator (`$(layers) <position>/<size>`) appears only while the current branch is part of a stack; click it to reveal the Stacks view. | `GSC: Refresh Stacks` | [Stacks](docs/stacks.md) |
+| Detect the GitHub-native [stacked PR](https://docs.github.com/en/rest/pulls/stacks) chain the current checkout belongs to — resolved by branch, PR-review worktree, HEAD commit, or upstream ref, so it works whether you switched branches or switched PRs — and browse it in a dedicated "Stacks" view (activity bar) with a GitHub-style status icon/badge per PR (open/draft/merged/closed/blocked downstack) plus the branch the stack is ultimately targeting. Click a row (or its target chip) to check it out using the currently selected checkout/stash strategy; right-click for "Open PR in Browser". Nothing is cached — an in-view refresh icon re-checks live at any time. A status bar indicator (`$(layers) <position>/<size>`) appears only while the current checkout is part of a stack, including on a matched detached HEAD; click it to reveal the Stacks view. | `GSC: Refresh Stacks` | [Stacks](docs/stacks.md) |
 | Create a new PR from selected commits in another GitHub PR | `GSC: Clone Pull Request...` | [GitHub PR clone](docs/github-pr-clone.md) |
 | Generate and optionally push a tag from a reusable template | `GSC: Create Tag from Template...` | [Create tag from template](docs/create-tag-from-template.md) |
 | Create and check out a branch from a template (Jira, file, regex, scripts) | `GSC: Create Branch from Template...` | [Create branch from template](docs/create-branch-from-template.md) |

docs/stacks.md

@@ -18,21 +18,29 @@ Whether a single PR onto trunk counts as a stack, how forks in history are resol
 
 ## The Stacks View
 
-Shows the stack containing the **current branch**, top PR first, target branch as a chip at the bottom. Each row shows the PR title and `#number · branch`; the current branch/target is highlighted.
+Shows the stack containing the **current checkout**, top PR first, target branch as a code chip at the bottom. Each row shows a GitHub-style status icon, the PR title, a right-aligned status badge, and `#number · head-ref` (the PR's own head branch — not necessarily your local branch name, see [Detection](#detection)); the current row is marked with a left accent bar.
 
-- **Click a row (or the target chip)** to check out that branch, using whichever [stash mode](switch-mode.md) is currently active — including the manual prompt if that's what's configured.
+- **Status icon and badge**: open (green), draft (dashed, "Draft"), merged (purple check, "Merged"), closed (red ×, "Closed"), or blocked (warning circle, "Blocked downstack" — shown when an unmerged draft/closed PR sits below it in the stack; this is a local approximation, since the Stacks API doesn't report per-member mergeability). Merged and closed rows render dimmed but stay in the list, matching their place in the real stack.
+- **Click a row (or the target chip)** to check out that PR's head branch, using whichever [stash mode](switch-mode.md) is currently active — including the manual prompt if that's what's configured.
 - **Right-click a row** (or use the inline external-link icon) for "Open PR in Browser".
 - The target chip shows **⇡N ⇣N** (commits waiting to be pushed / commits to pull), read directly from the branch's upstream tracking info — the same convention as the Worktrees view — whenever the target branch has an upstream configured. Next to it, a **fetch icon (⟳, "Fetch latest changes")** fetches the target branch from its remote (updating the remote-tracking ref only, no checkout, no merge) and refreshes the indicator.
-- The **refresh icon (⟳)** in the view's title bar re-fetches the current branch's stack status from GitHub on demand — useful right after a stack changes on GitHub (a PR merged, or the stack was reordered/dissolved), since nothing is cached locally.
-- When the current branch isn't part of any stack, the view shows an empty state with a Refresh button.
+- The **refresh icon (⟳)** in the view's title bar re-fetches the current stack status from GitHub on demand — useful right after a stack changes on GitHub (a PR merged, or the stack was reordered/dissolved), since nothing is cached locally.
+- When the current checkout isn't part of any stack, the view shows an empty state with a Refresh button.
 
 ## Status Bar Indicator
 
-`$(layers) <position>/<size>` appears immediately to the left of the stash-mode item, but **only** while the current branch is part of a detected stack — it's hidden when stacks are disabled, the extension's status bar is off, HEAD is detached, or the branch simply isn't stacked. The count is of **stacked PRs only** — the target branch doesn't count toward `<size>`, so sitting on the target itself shows no position (there's no PR there). Its tooltip lists the chain top-to-bottom with PR numbers/titles, plus the target branch on its own line. Click it to reveal the Stacks view.
+`$(layers) <position>/<size>` appears immediately to the left of the stash-mode item, but **only** while the current checkout is part of a detected stack — it's hidden when stacks are disabled, the extension's status bar is off, or the checkout simply isn't stacked. Unlike earlier versions, a detached HEAD does **not** hide the indicator on its own: a detached checkout sitting on a stack member's commit is still resolved and shown (see [Detection](#detection)). The count is of **stacked PRs only** — the target branch doesn't count toward `<size>`, so sitting on the target itself shows no position (there's no PR there). Its tooltip lists the chain top-to-bottom with PR numbers/titles, plus the target branch on its own line. Click it to reveal the Stacks view.
 
 ## Detection
 
-Detection is automatic and always on for GitHub repositories, with no configuration knob: whenever the current branch is the target or a stacked PR's head in one of the repository's stacks (as reported live by `GET /repos/{owner}/{repo}/stacks`), it shows up. Nothing is cached — a stack can be reordered or dissolved on GitHub at any time, so every refresh re-fetches live rather than risking a stale view.
+Detection is automatic and always on for GitHub repositories, with no configuration knob. Every refresh resolves the current checkout's *identity* — its branch name, HEAD commit sha, any `pr/<n>-review` worktree it's parsed from, and its upstream branch name — and matches that identity against the members and targets of the repository's stacks (as reported live by `GET /repos/{owner}/{repo}/stacks`), by precedence:
+
+1. **PR number** — a `GSC: Review PR by number` / "Review PR in worktree" checkout (branch `pr/<n>-review`) matches PR `<n>` directly, even though that branch name never appears in any PR's `head.ref`.
+2. **Branch name** — the checked-out local branch equals a stacked PR's `head.ref`, or the stack's `base.ref` (a target-only match, used only when no member matched).
+3. **Upstream ref** — the checked-out branch's remote-tracking branch (e.g. after `gh pr checkout` or a local rename) equals a stacked PR's `head.ref`.
+4. **HEAD commit sha** — a detached HEAD sitting exactly on a stacked PR's `head.sha`.
+
+A member match always wins over a target match, even across different stacks (e.g. standing on `main`, which is the target of one stack but also happens to be a stacked PR's head in another, resolves to the stack you're actually in). Stacks with `open: false` (dissolved on GitHub) are never matched. Nothing is cached — a stack can be reordered or dissolved on GitHub at any time, so every refresh re-fetches live rather than risking a stale view.
 
 Disable everything with:
 

src/commands/reviewPrByNumberCommand/index.ts

@@ -43,6 +43,12 @@ export function getReviewBranchName(prNumber: number): string {
   return `pr/${prNumber}-review`;
 }
 
+/** Parses the PR number out of a `pr/<n>-review` branch name, or undefined when it doesn't match. */
+export function parseReviewBranchName(branchName: string): number | undefined {
+  const match = /^pr\/(\d+)-review$/.exec(branchName);
+  return match ? Number(match[1]) : undefined;
+}
+
 interface ExistingReviewWorktree {
   worktreePath: string;
   branchName: string;

src/common/api/ghClient.ts

@@ -293,10 +293,8 @@ export class GitHubClient {
   }
 
   /**
-   * List all open pull requests for the repository. Used by stack detection
-   * to find PR base-branch chains; returns an empty array (rather than
-   * throwing) on any API failure so detection can fall back to the local
-   * ancestry heuristic without crashing.
+   * List all open pull requests for the repository. Returns an empty array
+   * (rather than throwing) on any API failure.
    */
   public async listOpenPullRequests(): Promise<GitHubPR[]> {
     try {
@@ -309,11 +307,10 @@ export class GitHubClient {
 
   /**
    * Same as {@link listOpenPullRequests}, but propagates API failures instead
-   * of swallowing them into an empty array. `StackService` needs this
-   * distinction: an empty list because there genuinely are no open PRs must
-   * not be conflated with a 401/rate-limit failure, which should instead fall
-   * back to a cached PR list (or the heuristic) rather than silently
-   * reporting "not stacked".
+   * of swallowing them into an empty array. `StackService` uses this list
+   * only to enrich a GitHub-native stack's members with title/URL — a failure
+   * here still yields a stack, with placeholder titles for members missing
+   * from the list (see `prStackFromGithubStack`).
    */
   public async listOpenPullRequestsOrThrow(): Promise<GitHubPR[]> {
     const endpoint = `/repos/${this.owner}/${this.repo}/pulls?state=open`;

src/common/git/gitExecutor.ts

@@ -611,6 +611,23 @@ export class GitExecutor {
     } catch { return undefined; }
   }
 
+  /** Short upstream branch name (remote prefix stripped) for the current HEAD, or undefined when there is none. */
+  async getUpstreamRef(): Promise<string | undefined> {
+    try {
+      const { stdout } = await this.#execGitCommand([
+        'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}',
+      ]);
+      const upstream = stdout.trim();
+      if (!upstream) {
+        return undefined;
+      }
+      const slashIndex = upstream.indexOf('/');
+      return slashIndex === -1 ? upstream : upstream.slice(slashIndex + 1);
+    } catch {
+      return undefined;
+    }
+  }
+
   async pullFromRemoteBranch(options: { rebase?: boolean } = {}) {
     await this.#execGitCommand(['pull', ...(options.rebase ? ['--rebase'] : [])]);
   }

src/extension.ts

@@ -248,28 +248,35 @@ export function activate(context: vscode.ExtensionContext) {
   );
 
   /**
-   * Refreshes the current branch's PR stack (GitHub PR chains, authoritative;
-   * the local ancestry heuristic only runs as an offline fallback — see
-   * `StackService`) and pushes the result to the Stacks webview and the
-   * status bar indicator. Never throws — detection failures (no GitHub
-   * remote/token, git errors) are swallowed so they can't break activation
-   * or command completion.
+   * Refreshes the current checkout's PR stack (GitHub's native Stacks API,
+   * matched by branch, PR-review worktree, HEAD sha, or upstream ref — see
+   * `findGithubStackForCheckout` in `StackService`) and pushes the result to
+   * the Stacks webview and the status bar indicator. Never throws —
+   * detection failures (no GitHub remote/token, git errors) are swallowed so
+   * they can't break activation or command completion. Guarded against
+   * out-of-order completion: activation, config-change, and debounced
+   * refreshes can all be in flight at once, and an older one finishing last
+   * must not clobber a newer view.
    */
+  let stackRefreshSequence = 0;
   const refreshStacks = async (): Promise<void> => {
+    const sequence = ++stackRefreshSequence;
     try {
       const result = await stackService.refresh();
+      if (sequence !== stackRefreshSequence) {
+        return;
+      }
       stackWebViewProvider.setStack(result.view);
       statusBarManager.setStackIndicator({
         isDetached: result.isDetached,
-        data:
-          result.view && result.currentBranch
-            ? {
-                orderedBranches: indicatorBranchesOf(result.view),
-                currentBranch: result.currentBranch,
-                target: result.view.target,
-                info: stackInfoMapOf(result.view),
-              }
-            : undefined,
+        data: result.view
+          ? {
+              orderedBranches: indicatorBranchesOf(result.view),
+              currentIndex: result.view.currentIndex,
+              target: result.view.target,
+              info: stackInfoMapOf(result.view),
+            }
+          : undefined,
       });
     } catch (error) {
       logService.warn(`Stack detection failed: ${error}`);
@@ -626,10 +633,22 @@ export function activate(context: vscode.ExtensionContext) {
       void refreshStacks();
     }, delayMs);
   };
+  // A checked-out-HEAD change (branch switch, PR-review checkout) should
+  // refresh the Stacks view promptly; ordinary working-tree churn (saves,
+  // stages) keeps the longer debounce so it doesn't spend API calls on
+  // every keystroke-driven git status update.
+  const currentHeadsSnapshot = (): string =>
+    (vscode.workspace.workspaceFolders ?? [])
+      .map((folder) => vscodeGitProvider?.getCurrentBranch(folder.uri.fsPath) ?? '')
+      .join('\x1f');
+  let lastStackHeadsSnapshot = currentHeadsSnapshot();
   const gitStateListener = vscodeGitProvider?.onDidChangeAnyRepositoryState(() => {
     worktreeTreeDataProvider.refreshDebounced();
     stashTreeDataProvider.refreshDebounced();
-    refreshStacksDebounced();
+    const heads = currentHeadsSnapshot();
+    const headChanged = heads !== lastStackHeadsSnapshot;
+    lastStackHeadsSnapshot = heads;
+    refreshStacksDebounced(headChanged ? 250 : 2000);
   });
 
   // Listen for configuration changes
@@ -662,6 +681,7 @@ export function activate(context: vscode.ExtensionContext) {
     windowStateListener,
     workspaceFoldersListener,
     ...(gitStateListener ? [gitStateListener] : []),
+    { dispose: () => clearTimeout(stackRefreshDebounceTimer) },
     telemetryChangeListener,
     statusBarManager,
     logService,