@erclx/aitk 3.29.0 → 3.29.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.29.0",
+  "version": "3.29.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-orchestrate/references/orchestrator-dispatch.md

@@ -1,6 +1,6 @@
 ---
 title: Orchestrator dispatch runbook
-description: The collision check before a self-dispatch, the worker cap, the launch command, and the loop's stopping condition
+description: The collision check before a self-dispatch, the worker cap, the branch and model the launch names, and the loop's stopping condition
 ---
 
 Run this at loop step 4, for a `## Run now` row whose plan is verified and whose file set has already cleared the Parallelism test against every track in flight, in place of handing the worktree to a human.
@@ -9,15 +9,27 @@ Run this at loop step 4, for a `## Run now` row whose plan is verified and whose
 
 Resolve `<slug>` from the row's plan the way `claude-worktree` Step 2 resolves a plan-matched name, per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Resolve `<type>` off that plan's `## Summary` and `**Files to touch:**` lines, per `${CLAUDE_SKILL_DIR}/../../standards/branch.md`, defaulting to `feat` when the lines settle nothing. The candidate branch is `<type>/<slug>`.
 
+This is the branch the worker takes, not a guess at one it will derive for itself. Carry the exact string into the launch below. Both halves of that derivation have already disagreed in production: one run checked `docs/remaining-skill-verdicts` against a worker that took `docs/skill-verdicts-decide`, and a later one checked `fix/path-form-hook` against a worker that took `feat/path-form-hook`. A check against a branch nobody uses verifies nothing, and the run dies anyway, since `claude-autoship` resolves its plan from the slug the worker actually took.
+
 ## Check the branch is unclaimed
 
 Run `aitk sessions list --branch <type>/<slug> --json` and read `claimed` off the record.
 
-- `claimed: true`: the row is not free. Report what holds it, `worktree` when it names a path and `sessions` when it carries a row, and move to the next candidate rather than colliding.
-- `claimed: false` and `sessionsReadable: true`: proceed to the cap check.
-- `claimed: false` and `sessionsReadable: false`, or the command refuses, or the record carries no `claimed` key (`reason` reads `no-registry` or `no-repository`): treat the candidate as unverified rather than clear. Report the refusal and fall back to the human-launch line below. Dispatching on a check that could not be read reproduces the exact collision this exists to prevent.
+- `claimed: true`: the row is not free. Report what holds it, `worktree` when it names a path, `sessions` when it carries a row, and `refs` when the branch already exists. Move to the next candidate rather than colliding.
+- `claimed: false`, `sessionsReadable: true`, and `refsReadable: true`: proceed to the cap check.
+- `claimed: false` with either flag false, or the command refuses, or the record carries no `claimed` key (`reason` reads `no-registry` or `no-repository`): treat the candidate as unverified rather than clear. Report which reading could not be taken and fall back to the human-launch line below. Dispatching on a check that could not be read reproduces the exact collision this exists to prevent.
+
+Reading `claimed` off the record is what keeps this a check rather than a rule a session can talk itself out of. The field is already the composed answer across the worktree listing, the live session roster, and the refs that name the branch, so nothing here re-derives the OR.
+
+`refs` is the reading that catches a shipped row. A branch behind a merged pull request has no worktree and no session, so the check answered clear on one until a worker refused the instruction and named the consequences: a second pull request against a head GitHub already shows merged, a row whose pull-request line points at two numbers, and the `ambiguous` refusal `aitk tasks archive` documents.
+
+What the ref read cannot see is a branch pushed from another machine since the last fetch, because it reads the remote-tracking ref rather than the remote. Nobody has hit that, and a `git ls-remote` per dispatch costs 0.438s against 0.001s, so the gap is recorded rather than closed.
+
+## Hold what this pass already launched
+
+A worker registers with `branch: main` and the main worktree as its `cwd` until `claude-autoship` Step 0 moves it, which took several seconds on both measured runs. Neither the roster nor the refs name the candidate during that window, so a second check inside it reads clear.
 
-Reading `claimed` off the record is what keeps this a check rather than a rule a session can talk itself out of. The field is already the composed answer across the worktree listing and the live session listing, so nothing here re-derives the OR.
+Keep the branch of every row this pass has launched and treat a candidate matching one as claimed, without re-running the check. That closes the window for this dispatcher and only for it. A second dispatcher in another session reads git and the roster alone, sees none of this record, and can still take the same row. Say so when reporting, rather than implying the window is shut.
 
 ## Check the worker cap
 
@@ -25,15 +37,25 @@ Run `aitk sessions list --json` with no `--branch`, then count entries whose `na
 
 Three already out: report the cap and stop dispatching for this pass, leaving the row ready for the next one. The cap binds the self-dispatch path alone, since the evidence behind it is one task shipped once and the operator's own launches stay uncapped by count.
 
+## Pick the model
+
+A `claude --bg` session inherits the model of whatever launched it rather than reading the machine's configured default. That was measured on 2026-08-27, with `~/.claude/settings.json` set to `sonnet` while both dispatched workers ran `claude-opus-5`. An orchestrator on the larger model therefore spends it on every worker it launches, and the operator who set the default never sees the override.
+
+Name `<model>` on the launch, and pick it against the task rather than copying whatever this session happens to run. Sizing the model to the row is the dispatcher's call, the same call it already makes on the branch. A mechanical row moving files under a written plan is not the row that needs the largest model, and one whose plan carries an open judgment is.
+
 ## Dispatch
 
 ```bash
-claude --bg -n "orchestrator-<slug>" "/aitk:claude-autoship .claude/tasks/<task-file>.md"
+claude --bg --model <model> -n "orchestrator-<slug>" "Run /aitk:claude-worktree <type>/<slug>, then /aitk:claude-autoship .claude/tasks/<task-file>.md"
 ```
 
-`claude-autoship`'s own Step 0 enters the worktree, so this session never does. `--bg, --background` starts the session as a background agent and returns immediately, and `-n, --name` sets the display name `aitk sessions list` reads back for the worker cap.
+`--bg, --background` starts the session as a background agent and returns immediately, `-n, --name` sets the display name `aitk sessions list` reads back for the worker cap, and `--model` overrides the inheritance the section above measured.
+
+The worktree call comes first and carries the branch as its argument, which is tier 0 of `claude-worktree` Step 2 and the only tier a caller can reach. `claude-autoship` Step 0 then finds the session already in a linked worktree and continues, which is a path it already documents. Autoship still resolves its plan, since the slug inside a dispatcher-named `<type>/<slug>` is the slug the dispatcher read off that plan.
+
+Naming the branch in prose instead was tried and closes nothing, because no tier of that ladder reads the prompt. A worker launched onto `main` cannot match tier 1, a board carrying more than one plan puts tier 2 out of reach, and tier 3 tells it to ask a person who is not there. Four workers took the right branch that way, by inference rather than by contract, which is the same judgment both live disagreements came from.
 
-Report the dispatch as loudly as the human-launch line it replaces: name the branch, the task, and the session name, so a person reading the transcript can follow what fired without watching it happen.
+Report the dispatch as loudly as the human-launch line it replaces: name the branch, the model, the task, and the session name, so a person reading the transcript can follow what fired without watching it happen.
 
 ## Fall back to the human
 

package/claude/skills/claude-worktree/SKILL.md

@@ -34,6 +34,7 @@ The directory test separates the defect from a genuinely bare repository, which
 
 Try each source in order. Stop at the first match.
 
+0. **Caller-supplied.** The invocation carried an argument. Take it as the name and infer nothing further. Accept `<name>` or `<type>/<name>`, where a leading segment matching a type in `${CLAUDE_SKILL_DIR}/../../standards/branch.md` sets `<type>` and the rest is `<name>`. A bare `<name>` falls to the default type below.
 1. **Plan matched to current branch.** Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. An empty result falls through to the next source here rather than becoming `latest`, since the slug is one candidate among several. If `<main-root>/.claude/plans/feature-<slug>.md` exists, use `<slug>`.
 2. **Single plan file.** List `<main-root>/.claude/plans/feature-*.md`. If exactly one match, derive `<slug>` from the filename.
 3. **Multiple plan files, no branch match.** Ask the user which plan. Show the candidate slugs as a numbered list. Do not pick.
@@ -41,22 +42,28 @@ Try each source in order. Stop at the first match.
    4b. **Session context.** When on `main` or `master` with no matching plan, read the current conversation to infer a kebab slug from the topic being discussed. Propose it: `Infer: <slug>. Confirm or rename?` Do not enter the worktree until the user confirms or provides a corrected name.
 5. **Ask.** None of the above applies. Ask the user for a name. Do not invent one.
 
+Tier 0 sits ahead of the inference because every tier below it answers from state the caller cannot set, and a caller that already knows the name has no way to say so. That gap is what a dispatched worker meets. It starts on `main`, so tier 1 cannot match, and a board carrying more than one plan puts tier 2 out of reach too, which lands the run on tier 3 and its instruction to ask somebody who is not there. A prompt naming the branch does not reach any of them, since no tier reads the prompt.
+
 Validate the result: letters, digits, dots, underscores, dashes only, max 64 chars (`/` separators are also allowed). If the derived name violates the rule, sanitize by replacing invalid chars with `-` and truncating. Show the sanitized name in the preview before invoking.
 
-Resolve `<type>` here as well, since Step 3 previews it and Step 5 renames onto it. A name from a plan takes the type that plan's own work carries, read off its `## Summary` and `**Files to touch:**` lines. Every other case takes `feat`, which covers a name from a branch, a name from the user, and a plan whose lines settle nothing. Draw the value from the type vocabulary in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`.
+Resolve `<type>` here as well, since Step 3 previews it and Step 5 renames onto it, drawing the value from the type vocabulary in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`. A type the caller spelled in tier 0 wins outright and no reading overrides it. A name from a plan takes the type that plan's own work carries, read off its `## Summary` and `**Files to touch:**` lines. Every other case takes `feat`, which covers a name from a branch, a bare name from the user, and a plan whose lines settle nothing.
+
+The caller's type wins because reading it off a plan is the half that has already disagreed in production. One dispatch checked `fix/path-form-hook` and the worker took `feat/path-form-hook`, both sides reading the same plan and grading it differently.
 
 A wrong type is cheap. `git-branch` renames to conventional format later in the same chain and runs ahead of `git-pr`, so a `feat/` written over a fix is corrected before any pull request opens.
 
 Then test both names the entry is about to claim. Neither read needs a worktree, and a stop after Step 4 leaves one built with the session sitting inside it, so both belong here rather than beside the rename:
 
-- Branch. `git show-ref --verify --quiet refs/heads/<type>/<name>` succeeding means the ref exists. Stop: `❌ Branch <type>/<name> already exists. Resolve manually before continuing.`
+- Branch. `git for-each-ref --format='%(refname)' refs/heads/<type>/<name> refs/remotes/origin/<type>/<name>` printing any ref means the name is taken. Stop: `❌ Branch <type>/<name> already exists. Resolve manually before continuing.` A non-zero exit is a read that failed rather than a free name, so stop on that too and say the read failed.
 - Directory. `<main-root>/.claude/worktrees/<name>/` existing means an earlier entry claimed the name. Stop: `❌ Worktree .claude/worktrees/<name>/ already exists. Resolve manually before continuing.`
 
 Leave both in place. Resolving either automatically risks the wrong one.
 
 The two tests catch different collisions. The branch test misses the one `${CLAUDE_SKILL_DIR}/../../standards/slug.md` records, where two branches differing only in type collapse onto one name: `feat/foo` and `fix/foo` are distinct refs and reach one directory. The directory test is the only read that sees it.
 
-The branch test fires on the tier 1 and tier 4 sources whenever the branch the session started on is already conventional, since a name derived from that branch resolves back onto it. Stopping is the answer there. The concern already has a branch, git refuses a second under the same name, and the bare-name rename this replaces only carried the collision forward to the `git-branch` step.
+The branch test fires on the tier 1 and tier 4 sources whenever the branch the session started on is already conventional, since a name derived from that branch resolves back onto it. Stopping is the answer there. The concern already has a branch, git refuses a second under the same name, and the bare-name rename this replaces only carried the collision forward to the `git-branch` step. It fires on tier 0 as well, where a caller handed a name something already holds.
+
+It reads both ref spaces rather than the local head alone, and it reads them the way `checkClaim` does, so a name this skill clears and a branch a dispatcher cleared are one answer. `git show-ref --verify` is what that replaces. It sees no remote-tracking ref, so a branch pushed from elsewhere passed the test and collided at the first push, and its exit code cannot separate an absent ref from a tree it could not read, which reports a failed read as a free name.
 
 ## Step 3: preview
 

package/docs/agents/sessions.md

@@ -36,13 +36,15 @@ The match can return more than one session. Read the count rather than the first
 
 ## Whether a branch is already claimed
 
-With `--branch`, the JSON record also carries `worktree` (the path of any worktree already checked out to it, or `null`) and `claimed` (`true` when either a worktree or a live session already holds the branch).
+With `--branch`, the JSON record also carries `worktree` (the path of any worktree already checked out to it, or `null`), `refs` (the refs that already name the branch, the local head and the `origin` remote-tracking ref alike), and `claimed` (`true` when any of the three holds it).
 
-Read `claimed` rather than composing the two fields by hand. A worktree can outlive the session that made it, and a session can hold a branch before a worktree exists for it, so either field alone can miss a real claim. A dispatcher deciding whether it is safe to start a build against a branch reads this one field instead of re-deriving the OR itself.
+Read `claimed` rather than composing the three fields by hand. A worktree can outlive the session that made it, and a session can hold a branch before any worktree exists for it. A branch sitting behind a merged pull request has neither and is taken all the same, which is the reading that was missing when a dispatcher cleared a merged branch and told a worker to build on it.
 
-`worktree` and `claimed` are `null` on a bare run with no `--branch`, since neither question has a branch to answer about. A refusal (`no-registry` or `no-repository`) carries neither key at all, which a caller should read as unverified rather than as clear.
+The ref read covers the local head and the remote-tracking ref, which means it sees the remote at whatever the last fetch left behind. A branch pushed from another machine since then reads absent. Closing that gap needs `git ls-remote`, and it is left open deliberately: the remote read costs 0.438s against 0.001s for the local one, on a check that runs before every dispatch.
 
-`sessionsReadable` is `false` when the session roster could not be read, which leaves `claimed` covering the worktree half alone. A `false` here is a report that ran short of evidence, not a report that the branch is clear, so a caller reads it as unverified alongside `claimed` rather than trusting `claimed` on its own.
+`worktree`, `refs`, and `claimed` are `null` on a bare run with no `--branch`, since none of the three questions has a branch to answer about. A refusal (`no-registry` or `no-repository`) carries none of the keys at all, which a caller should read as unverified rather than as clear.
+
+Two flags say which reading came up short. `sessionsReadable` is `false` when the session roster could not be read, and `refsReadable` is `false` when the ref read failed. Either one leaves `claimed` covering the readings around it alone, so a `false` there is a report that ran short of evidence rather than a report that the branch is clear. They stay separate fields because a caller told the roster failed goes and looks at the roster, and folding both into one flag would send it to the wrong place.
 
 ## Why the verb exists
 

package/docs/operating-model.md

@@ -37,7 +37,7 @@ and no later session recovers that vantage.
 One feature travels this path end to end.
 
 1. Orchestrator plans the next feature with `claude-feature`, writing a plan to `.claude/plans/`. Planning stays in the warm session because good planning is cross-feature. It needs the contract other features consume and the shared wiring seam. A cold session would re-derive or guess.
-2. Orchestrator checks the branch is unclaimed and the worker cap has room, then dispatches a background worker with `claude --bg` against the plan. It falls back to naming the invocation for a human to run through `claude-worktree` and `claude-autoship` when the check refuses, the cap is reached, or the plan collides with a track already in flight. Either way, the worker enters its own worktree, builds, self-checks, opens a PR, and stops at the PR boundary.
+2. Orchestrator checks the branch is unclaimed and the worker cap has room, then dispatches a background worker with `claude --bg` against the plan, naming the branch and the model on the launch rather than leaving the worker to derive either. The branch travels as the argument to the worker's own worktree call, which is the one place the name is read rather than inferred. It falls back to naming the invocation for a human to run through `claude-worktree` and `claude-autoship` when the check refuses, the cap is reached, or the plan collides with a track already in flight. Either way, the worker enters its own worktree, builds, self-checks, opens a PR, and stops at the PR boundary.
 3. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
 4. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a finding at any severity, resolving the target then with `aitk sessions list --branch` and reporting the invocation for the human when no live session holds it. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up. A pass carrying only minor findings dispatches too, since the grade runs low often enough that a floor at should-fix loses fixes a worker would have made. `claude-pr-review` states that threshold and the heading follows it, so an open heading is itself the signal to send.
 5. Orchestrator closes the review out with `claude-pr-review` again. The second pass reads only the commits the follow-up added, or the worker's response alone when the follow-up added none, and posts under `## Review` when it finds anything and under `## Review closed` when it finds nothing, so a reader learns from the heading whether work is still owed and takes the merge decision from the counts on the line under it. Repeat from step 4 until a pass closes the review.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.29.0",
+  "version": "3.29.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/indexes.ts

@@ -3,6 +3,7 @@ import { dirname, resolve } from 'node:path'
 import { $ } from 'bun'
 import type { Command } from 'commander'
 import { exitCodeFor, type RegenResult, regenOne } from '@/indexes/regen'
+import { gitEnv } from '@/git-env'
 import { findIndexedAncestor, isIgnored, listIndexes } from '@/indexes/walk'
 import { intro, logAdd, logInfo, logStep, logWarn, outro } from '@/ui'
 
@@ -164,6 +165,7 @@ async function stage(path: string, rel: string, root: string): Promise<void> {
   if (await isIgnored(root, path)) return
 
   const staged = await $`git -C ${root} add -- ${path}`
+    .env(gitEnv())
     .quiet()
     .nothrow()
     .then((result) => result.exitCode === 0)

package/src/commands/sessions.ts

@@ -60,17 +60,23 @@ export function register(program: Command): void {
         'so a caller filtering by hand has something that identifies one.',
         '',
         'With --branch, the JSON also carries "worktree" (the path of any',
-        'worktree already checked out to it, or null) and "claimed" (true when',
-        'either a worktree or a live session already holds it). A dispatcher',
-        'reads "claimed" rather than composing the two fields itself, since',
-        'either one alone can miss a real claim: a worktree can outlive the',
-        'session that made it, and a session can hold a branch before a',
-        'worktree exists for it.',
+        'worktree already checked out to it, or null), "refs" (the refs that',
+        'already name it, local head and origin remote-tracking alike), and',
+        '"claimed" (true when a worktree, a live session, or an existing ref',
+        'holds it). A dispatcher reads "claimed" rather than composing the',
+        'three fields itself, since each alone misses a real claim: a worktree',
+        'can outlive the session that made it, a session can hold a branch',
+        'before a worktree exists for it, and a branch behind a merged pull',
+        'request has neither while still being taken.',
         '',
-        '"sessionsReadable" is false when the session roster could not be read,',
-        'which leaves "claimed" covering the worktree half alone. Treat that',
+        '"sessionsReadable" is false when the session roster could not be read',
+        'and "refsReadable" is false when the ref read failed. Either one',
+        'leaves "claimed" covering the readings around it alone. Treat that',
         'case as unverified rather than as a clean "false".',
         '',
+        'The ref read sees the remote at whatever the last fetch left, so a',
+        'branch pushed from another machine since then reads absent here.',
+        '',
         'The match can return more than one session. Read the count rather than',
         'the first row, since two sessions can hold one branch.',
         '',
@@ -166,8 +172,10 @@ async function runList(opts: ListCommandOptions): Promise<number> {
         branch: opts.branch ?? null,
         repository,
         worktree: claim?.worktree ?? null,
+        refs: claim?.refs ?? null,
         claimed: claim?.claimed ?? null,
         sessionsReadable: claim?.sessionsReadable ?? null,
+        refsReadable: claim?.refsReadable ?? null,
         sessions: shown,
       })}\n`,
     )
@@ -261,11 +269,21 @@ function reportClaim(claim: ClaimReport): void {
     logInfo(`Worktree: ${claim.worktree}`)
   }
 
+  if (claim.refs.length > 0) {
+    logInfo(`Refs: ${claim.refs.join(', ')}`)
+  }
+
   logInfo(claim.claimed ? 'Claimed.' : 'Unclaimed.')
 
   if (!claim.sessionsReadable) {
     logWarn(
-      'The session roster could not be read, so this reads the worktree listing alone. Treat the session half as unverified rather than clear.',
+      'The session roster could not be read, so this leaves the session half out. Treat it as unverified rather than clear.',
+    )
+  }
+
+  if (!claim.refsReadable) {
+    logWarn(
+      'The ref read failed, so this cannot say whether the branch already exists. Treat it as unverified rather than clear.',
     )
   }
 }

package/src/sessions/claim.ts

@@ -4,26 +4,41 @@ import {
   type ResolvedSession,
   type SessionReport,
 } from '@/sessions/resolve'
-import { listWorktrees, type WorktreeEntry } from '@/worktree'
+import {
+  branchRefs,
+  listWorktrees,
+  type RefReport,
+  type WorktreeEntry,
+} from '@/worktree'
 
 export interface ClaimReport {
   readonly claimed: boolean
   readonly worktree: string | null
   readonly sessions: readonly ResolvedSession[]
-  /** False when the session roster could not be read, so `claimed` covers the worktree half alone and cannot be trusted as a clean "unclaimed". */
+  /** The refs already naming the branch, local head and `origin` remote-tracking alike. */
+  readonly refs: readonly string[]
+  /** False when the session roster could not be read, so `claimed` covers the readings around it alone and cannot be trusted as a clean "unclaimed". */
   readonly sessionsReadable: boolean
+  /** False when the ref read failed, which is the same false clean under a different reading. */
+  readonly refsReadable: boolean
 }
 
 export interface ClaimOptions {
   readonly cwd?: string
   readonly resolve?: () => Promise<SessionReport>
   readonly listWorktrees?: (cwd: string) => Promise<readonly WorktreeEntry[]>
+  readonly branchRefs?: (branch: string, cwd: string) => Promise<RefReport>
 }
 
 /**
- * Answers whether a branch is already claimed, composing the two readings
- * neither surface can answer alone: a worktree can outlive the session that
- * made it, and a session can hold a branch before a worktree exists for it.
+ * Answers whether a branch is already claimed, composing the three readings no
+ * one surface can answer alone: a worktree can outlive the session that made
+ * it, a session can hold a branch before a worktree exists for it, and a branch
+ * behind a merged pull request has neither while still being taken.
+ *
+ * The two readable flags stay separate because a caller told the roster failed
+ * looks at the roster. Folding either into `claimed` would report the failure
+ * as a clean "unclaimed", which is the answer this exists to stop giving.
  */
 export async function checkClaim(
   branch: string,
@@ -32,11 +47,13 @@ export async function checkClaim(
   const cwd = opts.cwd ?? process.cwd()
   const resolve = opts.resolve ?? resolveSessions
   const listAll = opts.listWorktrees ?? listWorktrees
+  const readRefs = opts.branchRefs ?? branchRefs
 
-  const [repository, worktrees, report] = await Promise.all([
+  const [repository, worktrees, report, refs] = await Promise.all([
     repositoryOf(cwd),
     listAll(cwd),
     resolve(),
+    readRefs(branch, cwd),
   ])
 
   const worktree =
@@ -51,9 +68,11 @@ export async function checkClaim(
       : []
 
   return {
-    claimed: worktree !== null || sessions.length > 0,
+    claimed: worktree !== null || sessions.length > 0 || refs.refs.length > 0,
     worktree,
     sessions,
+    refs: refs.refs,
     sessionsReadable: report.kind === 'resolved',
+    refsReadable: refs.readable,
   }
 }

package/src/sync/git.ts

@@ -1,5 +1,6 @@
 import { basename } from 'node:path'
 import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
 import type { SyncDomain } from '@/sync/target'
 import { pipeOutput } from '@/ui'
 
@@ -186,13 +187,27 @@ export async function hasGh(): Promise<boolean> {
   return result.exitCode === 0
 }
 
+/**
+ * Both seams strip git's repository-resolution variables, since a hook exports
+ * `GIT_DIR` into every process it runs and it beats `-C`. A sync driven from
+ * inside one would otherwise read the hook's repository and, through `mutate`,
+ * commit and push into it.
+ */
 async function read(target: string, args: readonly string[]): Promise<string> {
-  const result = await execa('git', ['-C', target, ...args], { reject: false })
+  const result = await execa('git', ['-C', target, ...args], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
   return result.exitCode === 0 ? result.stdout : ''
 }
 
 async function mutate(target: string, args: readonly string[]): Promise<void> {
-  const result = await execa('git', ['-C', target, ...args], { reject: false })
+  const result = await execa('git', ['-C', target, ...args], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
 
   if (result.exitCode !== 0) {
     throw new GitCommandError(

package/src/worktree.ts

@@ -50,6 +50,59 @@ export interface WorktreeEntry {
   readonly branch: string | null
 }
 
+export interface RefReport {
+  /** False when the ref read itself failed, so an empty `refs` says nothing about whether the branch exists. */
+  readonly readable: boolean
+  readonly refs: readonly string[]
+}
+
+/**
+ * Reports which of the local head and the `origin` remote-tracking ref already
+ * name a branch, separating an absent branch from a read that failed.
+ *
+ * `git for-each-ref` is what carries that separation. `git show-ref --verify`
+ * handed the same two ref paths exits 128 when one of them is missing, which is
+ * the code it also exits when the directory is no repository, so a caller
+ * cannot tell a half match from an unreadable tree. `for-each-ref` exits zero
+ * with empty output for absent and non-zero only for a failed read.
+ *
+ * A ref path is a pattern here rather than an exact name, so `refs/heads/x`
+ * also matches `refs/heads/x/y`. Git forbids both existing at once, so the
+ * over-match names the branch that blocks the candidate rather than a wrong
+ * one.
+ *
+ * The remote-tracking ref is read at whatever the last fetch left, so a branch
+ * pushed from another machine since then is invisible here. Closing that needs
+ * `git ls-remote`, measured at 0.438s against 0.001s for a local read.
+ */
+export async function branchRefs(
+  branch: string,
+  cwd: string = process.cwd(),
+): Promise<RefReport> {
+  // Every argument is interpolated rather than written inline, since Bun's
+  // shell parses the bare parentheses in `%(refname)` as syntax of its own.
+  const args = [
+    '--format=%(refname)',
+    `refs/heads/${branch}`,
+    `refs/remotes/origin/${branch}`,
+  ]
+
+  const result = await $`git -C ${cwd} for-each-ref ${args}`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return { readable: false, refs: [] }
+
+  return {
+    readable: true,
+    refs: result.stdout
+      .toString()
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0),
+  }
+}
+
 /**
  * Parses `git worktree list --porcelain`, which emits one block per worktree
  * separated by a blank line. A detached worktree carries no `branch` line,