gh-stack 0.19.8 → 0.19.10

package/README.md

@@ -95,6 +95,7 @@ add [branch] [--parent <branch>]
     A PR that gh-stack already recorded for a branch in git config (in
     another worktree of the repo) is kept, so a stack submitted from a
     worktree can be tracked in the main checkout and merged from there.
+    The adding worktree takes the branch over from then on.
 
     --parent <branch>: stack it directly on <branch> (which it must
     already be based on), tracking <branch> first if needed. Use this
@@ -498,7 +499,8 @@ config [--json]
 doctor
     Migrate old (v2) metadata to the v3 layout, split any stack left
     with several root branches into one stack per root, reconcile git
-    branch config against the topology files, flag stacks whose base
+    branch config against the topology files (leaving branches another
+    worktree is stacking alone), flag stacks whose base
     stack appears already-merged into main, and report stacks that
     still fail the checks other commands run before loading a stack.
     Safe to run repeatedly.
@@ -652,7 +654,9 @@ Review/CI status is intentionally not shown here. Run `gh-stack update-prs`
 ### Metadata (v3)
 
 Stack metadata lives under `.git/.gh-stack/` (never committed) — a folder of
-per-stack files plus git-native branch config, rather than a single JSON blob:
+per-stack files plus git-native branch config, rather than a single JSON blob.
+A linked worktree keeps its own folder in its own git dir
+(`.git/worktrees/<name>/.gh-stack/`), so each worktree has its own stacks:
 
 ```
 .git/.gh-stack/
@@ -687,8 +691,16 @@ 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)
+branch.<name>.ghstack-gitdir  <path>   git dir of the worktree that owns it
 ```
 
+Git config is shared by every worktree, so each branch records the worktree
+that owns it. A write in one worktree never clears or overwrites a branch
+another live worktree owns. `add` (or any command that starts tracking a
+branch) takes a branch over, which is how a stack is handed from one worktree
+to another. Once a worktree is removed, or its checkout is deleted, the next
+write anywhere clears the config it left behind.
+
 The two representations cross-check each other; `gh-stack doctor` reconciles
 any drift. Why this shape:
 
@@ -719,6 +731,14 @@ you at `doctor`.
 
 Before any destructive operation (restack, sync, merge, delete), gh-stack saves a snapshot of all branch HEADs as an append-only file under `snapshots/`, retained per-stack. Run `gh-stack undo` to restore.
 
+### Busy Repositories (git locks)
+
+Git doesn't wait for a lock: a checkout or rebase that finds `index.lock` held fails at once. The usual holder is a background `git status` (an editor, a watcher, another agent session), which takes the lock for a few milliseconds. So every git step gh-stack runs that takes a lock (checkout, rebase, reset, commit, branch and tag writes, branch config) waits and retries: after 0.1, 0.2, 0.4, 0.8, 1.6 and 2 seconds, about 5 seconds in all. A rebase that a lock interrupts midway is continued, not reported as a conflict.
+
+If the lock is still held after that, gh-stack names it and stops with exit 1, never "Rebase Conflict". Nothing conflicted, and the step changed nothing: once the lock is gone, run the command again, or `gh-stack restack --resume` for an interrupted restack or sync. A lock left by a crashed git process stays until you remove it.
+
+gh-stack also runs its own git calls with `GIT_OPTIONAL_LOCKS=0`, so its reads never take the lock.
+
 ## Example Workflow
 
 ```bash

package/package.json

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

package/src/commands/delete.ts

@@ -50,7 +50,8 @@ OPTIONS
     : ensureCurrentStack(meta);
   await ensureValidStack(meta, stackName);
   const stack = meta.stacks[stackName]!;
-  const currentBranch = await git.currentBranch();
+  // Detached HEAD is fine: `delete <branch>` doesn't need a current branch.
+  const currentBranch = (await git.currentBranch().catch(() => null)) ?? undefined;
 
   p.intro(pc.cyan("Delete Branch from Stack"));
 

package/src/commands/doctor.ts

@@ -17,7 +17,6 @@ import {
 import { validateStack } from "../lib/safety.ts";
 import { legacyMetadataPath, legacyRestackStatePath, restackStateFile } from "../lib/paths.ts";
 import { writeSnapshotFile } from "../lib/snapshot.ts";
-import { allBranchMemberships } from "../lib/branch-config.ts";
 
 const HELP = `
 gh-stack doctor — Migrate & repair stack metadata
@@ -28,9 +27,10 @@ USAGE
 Migrates old (v2) metadata to the v3 layout (per-stack files under
 .git/.gh-stack/ + git branch config), splits any stack left with several
 root branches into one stack per root, reconciles branch config against
-the topology files, flags stacks whose base stack looks already-merged
-into main, and reports stacks that still fail the checks other commands
-run before they load a stack.
+the topology files (leaving branches another worktree is stacking
+alone), flags stacks whose base stack looks already-merged into main,
+and reports stacks that still fail the checks other commands run
+before they load a stack.
 
 Safe to run repeatedly — it's idempotent.
 `;
@@ -204,11 +204,6 @@ function inferStack(
 // ── Reconciliation ──
 
 async function reconcile(meta: StackMetadata): Promise<void> {
-  // Re-syncing config is what writeMetadata already does: set desired
-  // membership, clear stale. Snapshot the before-state so we can report what
-  // drifted, then apply.
-  const before = await allBranchMemberships();
-
   // Report topology branches that no longer exist locally (can't auto-fix
   // safely — re-parenting children is a judgement call).
   const deadBranches: { stack: string; branch: string }[] = [];
@@ -220,31 +215,22 @@ async function reconcile(meta: StackMetadata): Promise<void> {
     }
   }
 
-  // Build desired membership to diff against `before`.
-  const desired = new Set<string>();
-  let drift = 0;
-  for (const [name, stack] of Object.entries(meta.stacks)) {
-    for (const [branch, b] of Object.entries(stack.branches)) {
-      desired.add(branch);
-      const cur = before.get(branch);
-      if (!cur || cur.stack !== name || cur.parent !== b.parent || cur.pr !== b.pr) drift++;
-    }
-  }
-  let orphans = 0;
-  for (const branch of before.keys()) {
-    if (!desired.has(branch)) orphans++;
-  }
-
-  // Apply the reconciliation (idempotent).
-  await writeMetadata(meta);
+  // Re-syncing config is what writeMetadata already does: set desired
+  // membership, clear stale, leave other worktrees' branches alone.
+  const { updated, cleared, foreign } = await writeMetadata(meta);
 
-  if (drift > 0 || orphans > 0) {
+  if (updated.length > 0 || cleared.length > 0) {
     p.log.success(
-      `Reconciled branch config: ${drift} updated, ${orphans} stale membership(s) cleared.`,
+      `Reconciled branch config: ${updated.length} updated, ${cleared.length} stale membership(s) cleared.`,
     );
   } else {
     p.log.info("Branch config already in sync with topology.");
   }
+  if (foreign.length > 0) {
+    p.log.info(
+      `Left ${foreign.length} branch(es) alone that another worktree is stacking: ${foreign.join(", ")}`,
+    );
+  }
 
   if (deadBranches.length > 0) {
     console.log();

package/src/commands/join.ts

@@ -277,7 +277,7 @@ export default async function join(args: string[]): Promise<void> {
   await verifyResult(plan);
 
   if (startBranch && startBranch !== (await git.currentBranch().catch(() => null))) {
-    await $`git checkout ${startBranch}`.nothrow().quiet();
+    await git.tryCheckout(startBranch);
   }
 
   const endMeta = await freshMeta();

package/src/commands/submit.ts

@@ -226,8 +226,11 @@ export default async function submit(args: string[]): Promise<void> {
     await runSubmit(args, run, jsonMode);
   } catch (err) {
     // A ConfigError (bad config file or env value) is an expected stop too: in
-    // --json mode it becomes the document's error, like any refusal.
-    const expected = err instanceof SubmitAbort || err instanceof ConfigError;
+    // --json mode it becomes the document's error, like any refusal. So is a
+    // git lock that outlasted the retries; outside --json, index.ts explains it.
+    if (!jsonMode && err instanceof git.GitLockError) throw err;
+    const expected =
+      err instanceof SubmitAbort || err instanceof ConfigError || err instanceof git.GitLockError;
     if (!jsonMode && !expected) throw err;
     if (!expected) console.error(err);
     error = (err as Error).message;

package/src/commands/undo.ts

@@ -6,7 +6,6 @@ import { ensureMetadata, ensureCleanWorkingTree } from "../lib/safety.ts";
 import { getLastSnapshot, popSnapshot } from "../lib/snapshot.ts";
 import { clearRestackState, loadRestackState } from "../lib/metadata.ts";
 import { confirmAction } from "../lib/ui.ts";
-import { $ } from "bun";
 
 export default async function undo(args: string[]): Promise<void> {
   if (args.includes("--help")) {
@@ -60,9 +59,9 @@ a destructive operation (restack, merge, sync, remove).
   for (const [branch, sha] of Object.entries(snapshot.branches)) {
     try {
       if (branch === activeBranch) {
-        await $`git reset --hard ${sha}`.quiet();
+        await git.runGitOrThrow(["reset", "--hard", sha]);
       } else {
-        await $`git branch -f ${branch} ${sha}`.quiet();
+        await git.runGitOrThrow(["branch", "-f", branch, sha]);
       }
       p.log.success(`Restored ${pc.yellow(branch)} → ${sha.slice(0, 8)}`);
     } catch {

package/src/index.ts

@@ -19,6 +19,12 @@ const colorOff =
   process.env.GH_STACK_PLAIN === "1";
 if (colorOff) process.env.NO_COLOR = "1";
 
+// gh-stack's own read-only git calls (status, diff) shouldn't take index.lock
+// to save a refreshed stat cache: that only contends with our own writes and
+// with a gh-stack running in another worktree (#69). Bun's shell reads
+// process.env at each call, so this reaches every git we run.
+process.env.GIT_OPTIONAL_LOCKS ??= "0";
+
 const { ensureGitRepo } = await import("./lib/safety.ts");
 const { parseCliArgs } = await import("./lib/cli.ts");
 const { setAutoYes } = await import("./lib/ui.ts");
@@ -64,6 +70,7 @@ const commandArgs = parsed.commandArgs;
 // A config problem (malformed TOML, a non-boolean env value) is reported as
 // one clean line, whichever command hit it.
 const { ConfigError } = await import("./lib/config.ts");
+const { GitLockError } = await import("./lib/git.ts");
 try {
   switch (command) {
     case "log":
@@ -183,11 +190,39 @@ try {
       process.exit(1);
   }
 } catch (err) {
+  if (err instanceof GitLockError) await reportHeldLock(err);
   if (!(err instanceof ConfigError)) throw err;
   console.error(`gh-stack: ${err.message}`);
   process.exit(1);
 }
 
+/**
+ * Another git process held a lock past every retry (#69). Say so plainly:
+ * nothing conflicted, and the step runs again once the lock is gone.
+ */
+async function reportHeldLock(err: InstanceType<typeof GitLockError>): Promise<never> {
+  const { findPendingRun } = await import("./lib/run-log.ts");
+  const pending = await findPendingRun().catch(() => null);
+  const lines = [
+    `gh-stack: another git process holds ${err.lockPath}, and still did after waiting ${(err.waitedMs / 1000).toFixed(1)}s.`,
+    `  Nothing conflicted: ${err.command} couldn't take the lock, so it changed nothing.`,
+  ];
+  if (err.rebaseInProgress) {
+    lines.push(
+      `  The rebase is paused, not conflicted. Once the lock is gone:`,
+      `    git rebase --continue`,
+    );
+  }
+  lines.push(
+    pending
+      ? `  Once the lock is gone, pick the run up where it stopped:\n    gh-stack restack --resume`
+      : `  Once the lock is gone, run the command again.`,
+    `  If no other git process is running, the lock is stale; remove it:\n    rm ${err.lockPath}`,
+  );
+  console.error(lines.join("\n"));
+  process.exit(1);
+}
+
 function printHelp() {
   console.log(`
 gh-stack v${VERSION} — Stacked PR manager for squash-merge workflows

package/src/lib/branch-config.ts

@@ -7,6 +7,7 @@
 //   branch.<name>.ghstack-parent  <parent-branch>
 //   branch.<name>.ghstack-pr      <number>
 //   branch.<name>.ghstack-id      <uuid>  (stable identity; survives rename)
+//   branch.<name>.ghstack-gitdir  <path>  (the git dir of the worktree that owns it)
 //
 // Why config and not JSON: git maintains the `branch.<name>` section for us.
 //   • `git branch -m old new`  → the section moves      → rename tracking free
@@ -18,13 +19,22 @@
 // alphanumerics and `-` in config keys (underscores are rejected outright),
 // and it lowercases the variable portion on read — so `ghstack-stack` round
 // -trips exactly while a camelCase key would read back mangled.
+//
+// Git config is shared by every worktree of a repo, but each worktree keeps its
+// own stack files (under its own git dir). `ghstack-gitdir` records which
+// worktree wrote a branch's membership, so a write in one worktree leaves the
+// branches another worktree is stacking alone (#64).
 import { $ } from "bun";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import { runGit } from "./git.ts";
 
 export interface BranchMembership {
   stack?: string;
   parent?: string;
   pr?: number;
   id?: string;
+  gitdir?: string;
 }
 
 const KEY_PREFIX = "ghstack-";
@@ -32,6 +42,7 @@ const STACK_KEY = "ghstack-stack";
 const PARENT_KEY = "ghstack-parent";
 const PR_KEY = "ghstack-pr";
 const ID_KEY = "ghstack-id";
+const GITDIR_KEY = "ghstack-gitdir";
 
 function configKey(branch: string, key: string): string {
   return `branch.${branch}.${key}`;
@@ -50,6 +61,7 @@ export async function setBranchMembership(
   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);
+  await setOrUnset(branch, GITDIR_KEY, membership.gitdir);
 }
 
 async function setOrUnset(branch: string, key: string, value: string | undefined): Promise<void> {
@@ -57,12 +69,16 @@ async function setOrUnset(branch: string, key: string, value: string | undefined
     await unsetKey(branch, key);
     return;
   }
-  await $`git config ${configKey(branch, key)} ${value}`.quiet().nothrow();
+  // The repo's config is shared by every worktree, so another gh-stack (or any
+  // `git config` write) can hold config.lock for a moment: runGit waits it out
+  // instead of silently dropping the write.
+  await runGit(["config", configKey(branch, key), value]);
 }
 
 async function unsetKey(branch: string, key: string): Promise<void> {
-  // `--unset` exits 5 when the key is already absent — harmless, so nothrow.
-  await $`git config --unset ${configKey(branch, key)}`.quiet().nothrow();
+  // `--unset` exits 5 when the key is already absent — harmless, so the exit
+  // code is ignored.
+  await runGit(["config", "--unset", configKey(branch, key)]);
 }
 
 /**
@@ -83,6 +99,7 @@ export async function clearBranchMembership(branch: string): Promise<void> {
   await unsetKey(branch, PARENT_KEY);
   await unsetKey(branch, PR_KEY);
   await unsetKey(branch, ID_KEY);
+  await unsetKey(branch, GITDIR_KEY);
 }
 
 /**
@@ -121,6 +138,7 @@ export async function allBranchMemberships(): Promise<Map<string, BranchMembersh
     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 === GITDIR_KEY) m.gitdir = value;
     else if (field === PR_KEY) {
       const n = Number(value);
       if (Number.isFinite(n)) m.pr = n;
@@ -130,3 +148,29 @@ export async function allBranchMemberships(): Promise<Map<string, BranchMembersh
 
   return out;
 }
+
+/**
+ * True if `m` belongs to a worktree other than `mine` that still exists.
+ * Membership with no owner (written before owners were recorded) or with an
+ * owner that's gone is up for grabs.
+ */
+export function ownedByOtherWorktree(m: BranchMembership | undefined, mine: string): boolean {
+  return !!m?.gitdir && m.gitdir !== mine && gitDirIsLive(m.gitdir);
+}
+
+/**
+ * A worktree's git dir is live while it exists and, for a linked worktree,
+ * while its checkout does too: `.git/worktrees/<name>/gitdir` names the
+ * checkout's `.git` file, which is what `git worktree prune` checks. The main
+ * checkout's git dir has no `gitdir` file.
+ */
+function gitDirIsLive(dir: string): boolean {
+  if (!existsSync(dir)) return false;
+  const pointer = path.join(dir, "gitdir");
+  if (!existsSync(pointer)) return true;
+  try {
+    return existsSync(readFileSync(pointer, "utf8").trim());
+  } catch {
+    return false;
+  }
+}

package/src/lib/git.ts

@@ -2,10 +2,168 @@
 import { $ } from "bun";
 import { createHash } from "node:crypto";
 import { mkdir } from "node:fs/promises";
+import pc from "picocolors";
 
 export const STACK_SYNC_TAG_PREFIX = "stack-sync-base";
 export const STACK_SYNC_TAG_GLOB = `${STACK_SYNC_TAG_PREFIX}-*`;
 
+// ── Lock contention (#69) ──────────────────────────────────────────────────
+//
+// Git doesn't wait for a lock: a checkout, rebase or config write that finds
+// `index.lock` (or `config.lock`, a ref lock) already present fails at once.
+// The usual holder is a background reader (an editor's or agent's `git
+// status`) that grabs index.lock for a few milliseconds to save a refreshed
+// stat cache, so the lock is gone almost immediately. Every gh-stack git call
+// that takes a lock goes through runGit, which waits and retries instead.
+
+/** git's message for a lock file that already exists (lockfile.c). */
+const LOCK_HELD = /Unable to create '([^']+\.lock)': File exists/;
+/**
+ * `git config` words it differently, naming the config file rather than its
+ * lock (and it already waits about a second on its own before failing).
+ */
+const CONFIG_LOCK_HELD = /could not lock config file (.+): File exists/;
+
+/** Waits between attempts: quick at first, then backing off (~5 s in all). */
+const DEFAULT_LOCK_RETRY_DELAYS_MS = [100, 200, 400, 800, 1600, 2000];
+let lockRetryDelaysMs = DEFAULT_LOCK_RETRY_DELAYS_MS;
+
+/** Shorten the retry schedule in tests; `null` restores the default. */
+export function setLockRetryDelays(delays: number[] | null): void {
+  lockRetryDelaysMs = delays ?? DEFAULT_LOCK_RETRY_DELAYS_MS;
+}
+
+/** The lock file another process holds, if git's output says one blocked it. */
+export function heldLock(output: string): string | null {
+  const lock = LOCK_HELD.exec(output)?.[1];
+  if (lock) return lock;
+  const config = CONFIG_LOCK_HELD.exec(output)?.[1];
+  return config ? `${config}.lock` : null;
+}
+
+/**
+ * A lock was still held after every retry. Nothing conflicted: the step can
+ * simply run again once the other git process lets go.
+ */
+export class GitLockError extends Error {
+  constructor(
+    readonly lockPath: string,
+    readonly command: string,
+    /** The lock interrupted a rebase midway; it's paused, not conflicted. */
+    readonly rebaseInProgress: boolean,
+    /** How long gh-stack waited for it before giving up. */
+    readonly waitedMs: number,
+  ) {
+    super(`another git process holds ${lockPath} (${command})`);
+    this.name = "GitLockError";
+  }
+}
+
+export interface GitResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Run `git <args>`, retrying while another process holds a lock it needs.
+ * Retrying is safe because git takes the lock before changing anything: the
+ * failed attempt left the repo as it was. Throws GitLockError when retries
+ * run out; any other failure is returned for the caller to judge.
+ *
+ * `echo` replays git's output to the terminal (rebase progress and conflict
+ * messages), leaving out the attempts a lock blocked.
+ */
+export async function runGit(args: string[], opts: { echo?: boolean } = {}): Promise<GitResult> {
+  return retryLocks(args, opts.echo ?? false, async () => ({ next: args }));
+}
+
+/** Run `git <args>` with lock retries, throwing if it fails for another reason. */
+export async function runGitOrThrow(args: string[], opts: { echo?: boolean } = {}): Promise<void> {
+  const { exitCode, stderr } = await runGit(args, opts);
+  if (exitCode !== 0) {
+    throw new Error(`git ${args.join(" ")} failed (exit ${exitCode}): ${stderr.trim()}`);
+  }
+}
+
+interface Retry {
+  next: string[];
+  /** The retry resumes a rebase that a lock paused midway. */
+  resumesRebase?: boolean;
+}
+
+/**
+ * A rebase, retried around lock contention. A lock held when the rebase
+ * starts fails it before anything happens ("could not detach HEAD"), so it
+ * runs again as is. A lock that turns up midway makes git reschedule the
+ * pick it couldn't apply and pause, with nothing conflicted: `git rebase
+ * --continue` picks it up. Returns false only for a real conflict.
+ * (Exported for tests; commands use rebaseOnto and rebase.)
+ */
+export async function runRebase(args: string[]): Promise<boolean> {
+  const result = await retryLocks(args, true, async () => {
+    if (!(await isRebaseInProgress())) return { next: args };
+    // A conflict leaves unmerged paths; a lock-paused rebase doesn't.
+    if (await hasUnmergedPaths()) return null;
+    return { next: ["rebase", "--continue"], resumesRebase: true };
+  });
+  return result.exitCode === 0;
+}
+
+/**
+ * The retry loop. When an attempt fails because a lock is held, `onLocked`
+ * returns the command to retry with (or null to stop and return the failure).
+ */
+async function retryLocks(
+  args: string[],
+  echo: boolean,
+  onLocked: () => Promise<Retry | null>,
+): Promise<GitResult> {
+  let retry: Retry = { next: args };
+  let announced = false;
+  let waitedMs = 0;
+  for (let attempt = 0; ; attempt++) {
+    let shell = $`git ${retry.next}`.quiet().nothrow();
+    // Resuming a lock-paused pick reuses the commit's message; never stop to
+    // open an editor for it.
+    if (retry.resumesRebase) shell = shell.env({ ...process.env, GIT_EDITOR: "true" });
+    const raw = await shell;
+    const result = {
+      exitCode: raw.exitCode,
+      stdout: raw.stdout.toString(),
+      stderr: raw.stderr.toString(),
+    };
+
+    const lock = result.exitCode === 0 ? null : heldLock(result.stderr);
+    const next = lock ? await onLocked() : null;
+    if (!lock || !next) {
+      if (echo) {
+        process.stdout.write(result.stdout);
+        process.stderr.write(result.stderr);
+      }
+      return result;
+    }
+
+    const delay = lockRetryDelaysMs[attempt];
+    if (delay === undefined) {
+      throw new GitLockError(lock, `git ${args.join(" ")}`, next.resumesRebase ?? false, waitedMs);
+    }
+    if (!announced) {
+      console.error(pc.dim(`  Another git process holds ${lock}; waiting for it to finish…`));
+      announced = true;
+    }
+    await Bun.sleep(delay);
+    waitedMs += delay;
+    retry = next;
+  }
+}
+
+/** Whether the index has unmerged (conflicted) entries. */
+async function hasUnmergedPaths(): Promise<boolean> {
+  const out = await $`git diff --name-only --diff-filter=U`.quiet().nothrow().text();
+  return out.trim() !== "";
+}
+
 /**
  * Get the current branch name.
  * Throws if in detached HEAD state.
@@ -39,6 +197,15 @@ export async function gitDir(): Promise<string> {
   return result.trim();
 }
 
+/**
+ * Absolute path to this worktree's git dir. `gitDir()` is relative (`.git`) in
+ * the main checkout, which can't identify a worktree from another one.
+ */
+export async function absoluteGitDir(): Promise<string> {
+  const result = await $`git rev-parse --absolute-git-dir`.text();
+  return result.trim();
+}
+
 /**
  * Get the absolute path to the repository's working-tree root.
  */
@@ -52,9 +219,13 @@ export async function repoRoot(): Promise<string> {
  * Refreshes the index first to avoid false positives from stale stat info.
  */
 export async function isCleanWorkingTree(): Promise<boolean> {
+  // Refresh index to avoid false positives from stat changes (timestamps, etc.).
+  // Outside the try: a lock that never frees must surface, not read as dirty.
+  // No -q: it also hides the lock message, and a refresh the lock blocked
+  // leaves stale stat info that makes a clean tree look dirty. The output
+  // ("needs update" lines) is captured and dropped.
+  await runGit(["update-index", "--refresh"]);
   try {
-    // Refresh index to avoid false positives from stat changes (timestamps, etc.)
-    await $`git update-index -q --refresh`.quiet().nothrow();
     await $`git diff-index --quiet HEAD --`.quiet();
     return true;
   } catch {
@@ -87,13 +258,13 @@ export async function isRebaseInProgress(): Promise<boolean> {
 }
 
 /**
- * Checkout a branch. Throws a raw ShellError on failure — only use this where a
- * failure is unexpected (e.g. after ensureCleanWorkingTree). For user-facing
- * branch switching, prefer tryCheckout so a dirty-tree refusal can be rendered
- * as a clean message instead of a stack trace.
+ * Checkout a branch. Throws on failure — only use this where a failure is
+ * unexpected (e.g. after ensureCleanWorkingTree). For user-facing branch
+ * switching, prefer tryCheckout so a dirty-tree refusal can be rendered as a
+ * clean message instead of a stack trace.
  */
 export async function checkout(branch: string): Promise<void> {
-  await $`git checkout ${branch}`.quiet();
+  await runGitOrThrow(["checkout", branch]);
 }
 
 /**
@@ -102,15 +273,15 @@ export async function checkout(branch: string): Promise<void> {
  * message and the offending file list when a dirty tree blocks the switch).
  */
 export async function tryCheckout(branch: string): Promise<{ ok: boolean; stderr: string }> {
-  const { exitCode, stderr } = await $`git checkout ${branch}`.quiet().nothrow();
-  return { ok: exitCode === 0, stderr: stderr.toString() };
+  const { exitCode, stderr } = await runGit(["checkout", branch]);
+  return { ok: exitCode === 0, stderr };
 }
 
 /**
  * Create and checkout a new branch from the current HEAD.
  */
 export async function createBranch(name: string): Promise<void> {
-  await $`git checkout -b ${name}`;
+  await runGitOrThrow(["checkout", "-b", name], { echo: true });
 }
 
 /**
@@ -315,7 +486,7 @@ export async function localBranchExists(branch: string): Promise<boolean> {
  * the branch didn't exist or the delete failed.
  */
 export async function deleteLocalBranch(branch: string): Promise<boolean> {
-  const { exitCode } = await $`git branch -D ${branch}`.nothrow().quiet();
+  const { exitCode } = await runGit(["branch", "-D", branch]);
   return exitCode === 0;
 }
 
@@ -325,7 +496,7 @@ export async function deleteLocalBranch(branch: string): Promise<boolean> {
  * 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();
+  const { exitCode } = await runGit(["branch", "-m", oldName, newName]);
   return exitCode === 0;
 }
 
@@ -341,7 +512,7 @@ export async function deleteRemoteBranch(branch: string): Promise<boolean> {
  * Create a temporary tag at a specific commit.
  */
 export async function createTag(name: string, commit: string): Promise<void> {
-  await $`git tag -f ${name} ${commit}`.quiet();
+  await runGitOrThrow(["tag", "-f", name, commit]);
 }
 
 /**
@@ -352,7 +523,7 @@ export async function deleteTagsMatching(pattern: string): Promise<void> {
     const result = await $`git tag -l ${pattern}`.text();
     const tags = result.trim().split("\n").filter(Boolean);
     for (const tag of tags) {
-      await $`git tag -d ${tag}`.quiet();
+      await runGitOrThrow(["tag", "-d", tag]);
     }
   } catch {
     // No tags to delete — that's fine
@@ -377,8 +548,7 @@ export async function rebaseOnto(
   oldBase: string,
   branch: string,
 ): Promise<boolean> {
-  const { exitCode } = await $`git rebase --onto ${newBase} ${oldBase} ${branch}`.nothrow();
-  return exitCode === 0;
+  return runRebase(["rebase", "--onto", newBase, oldBase, branch]);
 }
 
 /**
@@ -386,7 +556,7 @@ export async function rebaseOnto(
  * Returns true if successful. Caller must have verified the tree is clean.
  */
 export async function resetHard(ref: string): Promise<boolean> {
-  const { exitCode } = await $`git reset --hard ${ref}`.nothrow().quiet();
+  const { exitCode } = await runGit(["reset", "--hard", ref]);
   return exitCode === 0;
 }
 
@@ -395,8 +565,7 @@ export async function resetHard(ref: string): Promise<boolean> {
  * Returns true if successful, false if conflicts occurred.
  */
 export async function rebase(target: string): Promise<boolean> {
-  const { exitCode } = await $`git rebase ${target}`.nothrow();
-  return exitCode === 0;
+  return runRebase(["rebase", target]);
 }
 
 /**
@@ -404,7 +573,7 @@ export async function rebase(target: string): Promise<boolean> {
  * Returns true if successful.
  */
 export async function mergeSquash(branch: string): Promise<boolean> {
-  const { exitCode } = await $`git merge --squash ${branch}`.nothrow();
+  const { exitCode } = await runGit(["merge", "--squash", branch], { echo: true });
   return exitCode === 0;
 }
 
@@ -412,7 +581,7 @@ export async function mergeSquash(branch: string): Promise<boolean> {
  * Commit with a message.
  */
 export async function commit(message: string): Promise<void> {
-  await $`git commit -m ${message}`;
+  await runGitOrThrow(["commit", "-m", message], { echo: true });
 }
 
 /**

package/src/lib/metadata.ts

@@ -29,6 +29,7 @@ import {
   allBranchMemberships,
   setBranchMembership,
   clearBranchMembership,
+  ownedByOtherWorktree,
   type BranchMembership,
 } from "./branch-config.ts";
 import { loadSnapshots } from "./snapshot.ts";
@@ -256,7 +257,7 @@ function serializeStack(stack: Stack): string {
  * tombstone any stack file that's no longer present, and reconcile git branch
  * config to match active membership.
  */
-export async function writeMetadata(meta: StackMetadata): Promise<void> {
+export async function writeMetadata(meta: StackMetadata): Promise<BranchConfigSync> {
   await ensureDirs();
 
   // 0. stamp a stable id on any active branch that lacks one, so a later
@@ -269,6 +270,13 @@ export async function writeMetadata(meta: StackMetadata): Promise<void> {
   const aDir = await activeDir();
   const arDir = await archivedDir();
 
+  // Branches this worktree tracked before this write. Any other active branch
+  // is joining it now, which claims its config from another worktree.
+  const tracked = new Set<string>();
+  for (const stack of Object.values(await readStackDir(aDir))) {
+    for (const name of Object.keys(stack.branches ?? {})) tracked.add(name);
+  }
+
   // 2. write active + archived stack files (write desired state BEFORE
   //    removing anything — that's what makes "can't vanish" hold).
   for (const [name, stack] of Object.entries(meta.stacks)) {
@@ -286,7 +294,7 @@ export async function writeMetadata(meta: StackMetadata): Promise<void> {
   await reconcileStale(arDir, archivedNames, (name) => activeNames.has(name));
 
   // 4. mirror active membership into git config
-  await syncBranchConfig(meta);
+  return syncBranchConfig(meta, tracked);
 }
 
 /**
@@ -321,38 +329,80 @@ async function reconcileStale(
   }
 }
 
+/** What `syncBranchConfig` changed. */
+export interface BranchConfigSync {
+  /** Branches whose membership was written. */
+  updated: string[];
+  /** Branches whose stale membership was removed. */
+  cleared: string[];
+  /** Branches left alone because another live worktree owns them. */
+  foreign: string[];
+}
+
 /**
- * Reconcile git branch config so it exactly mirrors active-stack membership.
+ * Reconcile git branch config so it mirrors this worktree's active membership.
  * Only branches whose recorded membership differs are touched, to avoid
  * shelling out to `git config` for every branch on every write.
+ *
+ * Git config is shared by every worktree, so a branch another live worktree
+ * owns is left alone (#64): it isn't cleared when this worktree doesn't track
+ * it, and it isn't overwritten when both do. The exception is a branch joining
+ * this worktree's stacks in this write (`add`, `create`, adopting a chain),
+ * which is the handoff, so this worktree takes it over. `tracked` is what this
+ * worktree tracked before the write.
  */
-async function syncBranchConfig(meta: StackMetadata): Promise<void> {
+async function syncBranchConfig(
+  meta: StackMetadata,
+  tracked: Set<string>,
+): Promise<BranchConfigSync> {
+  const mine = await git.absoluteGitDir();
   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, id: b.id });
+      desired.set(branchName, {
+        stack: stackName,
+        parent: b.parent,
+        pr: b.pr,
+        id: b.id,
+        gitdir: mine,
+      });
     }
   }
 
   const existing = await allBranchMemberships();
+  const result: BranchConfigSync = { updated: [], cleared: [], foreign: [] };
 
   for (const [branch, m] of desired) {
     const cur = existing.get(branch);
+    if (tracked.has(branch) && ownedByOtherWorktree(cur, mine)) {
+      result.foreign.push(branch);
+      continue;
+    }
     if (
       !cur ||
       cur.stack !== m.stack ||
       cur.parent !== m.parent ||
       cur.pr !== m.pr ||
-      cur.id !== m.id
+      cur.id !== m.id ||
+      cur.gitdir !== m.gitdir
     ) {
       await setBranchMembership(branch, m);
+      result.updated.push(branch);
     }
   }
 
   // Branches that still carry gh-stack config but are no longer active members.
-  for (const branch of existing.keys()) {
-    if (!desired.has(branch)) await clearBranchMembership(branch);
+  for (const [branch, m] of existing) {
+    if (desired.has(branch)) continue;
+    if (ownedByOtherWorktree(m, mine)) {
+      result.foreign.push(branch);
+      continue;
+    }
+    await clearBranchMembership(branch);
+    result.cleared.push(branch);
   }
+
+  return result;
 }
 
 /**
@@ -564,11 +614,6 @@ export async function removeBranchFromStack(
     }
     delete stack.branches[branchName];
 
-    // The removed branch may still exist in git but is no longer a member —
-    // drop its membership config explicitly (syncBranchConfig also would, but
-    // be direct since the branch is gone from `meta`).
-    await clearBranchMembership(branchName);
-
     if (stack.last_branch === branchName) {
       const remaining = Object.keys(stack.branches);
       stack.last_branch = remaining.length > 0 ? remaining[remaining.length - 1]! : null;

package/src/lib/using-gh-stack.md

@@ -133,6 +133,8 @@ no-publish path.)
 but the PR numbers gh-stack records in git config are shared. So after
 submitting from a worktree, `gh-stack add <top-branch>` in the main checkout
 tracks the whole chain _with_ its PRs, and `sync`/`merge --base` work there.
+Each branch's config records the worktree that owns it, so worktrees running
+gh-stack side by side don't clear each other's; `add` takes a branch over.
 
 **Splice an existing branch/PR into a stack — `gh-stack join`.** For a branch
 that should have been stacked but was cut from main on its own (often with its
@@ -301,6 +303,13 @@ it (its PR would be diffed against the parent's old history); the run lists it
 as held and exits 1 until `--resume` gets the parent pushed. `merge` and `join`
 refuse to run while a restack/sync is pending.
 
+**"Another git process holds …index.lock"**: some other process (often a
+background `git status`) held a git lock. gh-stack waits and retries for about 5
+seconds first, so seeing this means the lock outlasted that. It is not a
+conflict and the step changed nothing: run the same command again, or
+`gh-stack restack --resume` if a restack/sync was interrupted. If no git process
+is running, the lock is stale; remove the file it names.
+
 **Why did the push fail?** gh-stack prints the last lines of `git push`'s
 output, which includes a pre-push hook's own messages, and saves all of it to
 `.git/.gh-stack/push-failure.log`. Fix the cause (a failing check, say), then