@erclx/aitk 3.26.1 → 3.28.0

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

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

package/claude/skills/claude-orchestrate/REQUIREMENT.md

@@ -67,12 +67,16 @@ The session also records nothing of what it learns. Both other callers of memory
 - Write each re-test into the row and its measurement into that task's Findings, since a result reported in chat is gone at the next compaction and the next pass measures the same thing
 - Plan a row the re-test clears, since a cleared row carrying no plan is one the next pass looks at again
 - Split a task whose file set collides with every other by construction, rather than re-measuring a scoping defect that reads as a blocker
+- Check a candidate branch is unclaimed by an existing worktree or a live session before dispatching a background worker for it, since the measured failure this closes is a worker colliding with someone else's work already sitting in the row
+- Cap concurrent self-dispatched workers at three, counted by a session name no human-launched worker carries, since the evidence behind self-dispatch is one task shipped once
+- Report each self-dispatch and the row it fired against loudly enough to follow, since a person no longer watches the launch step happen
+- Stop dispatching once `## Run now` is empty or every row in it reads claimed, rather than waking again to fire on a board nobody is clearing
 
 ## Must not
 
 - Implement a feature or edit any tracked file from this session, at any size, since the ban offers no proportionality exception
 - Merge. Recommend merge or changes and leave the gate to the human.
-- Spawn worker sessions with agents, since every build is meant to be an independent steerable stream
+- Spawn a worker with the Agent tool, since an in-process subagent shares this session's context and cannot be steered or reached independently. A dispatched `claude --bg` process is not this: it is a separate session with its own worktree and its own PR, gated by the collision check and the worker cap.
 - Hand a worker anything but a plan, because scope lives there
 - Run a second orchestrator against the same board
 - Promote a task to fill the queue when nothing qualifies. A thin queue is a real answer.
@@ -88,10 +92,12 @@ The session also records nothing of what it learns. Both other callers of memory
 - Cross-version sequencing asked for: say no surface carries it, rather than asserting an active version the tree does not state
 - This body dropped from a long session approaching a compaction: name the re-invocation and the runbook paths, since the routing lives in the body and a user-invoked skill routes nothing once it is gone
 - Blocker only an operator can clear: record the row as untestable this pass and name the action owed, rather than re-measuring what no session can move
+- Collision check refuses, with no session registry or no repository resolved: treat the candidate as unverified and fall back to the human-launch line, rather than reading a check that could not run as a clear one
+- Worker cap already at three: stop dispatching for the pass and leave the row ready, rather than queueing past it
 
 ## Out of scope
 
 - Writing the plan itself, which `claude-feature` owns and this session runs rather than reimplements
 - Reviewing a worker's pull request, which `claude-pr-review` owns
-- Entering the worktree a build runs in, which the human opens
+- Entering the worktree a build runs in, which the worker opens for itself whether a human launched it or this session dispatched it
 - The operating model this enacts, which the toolkit's own docs hold

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

@@ -10,7 +10,8 @@ This session is the orchestrator: the one warm session that holds the
 cross-feature picture. It plans and reviews.
 
 It does not build, and it does not merge. Building happens in cold worker
-sessions the human launches. Merging is the human's gate.
+sessions, dispatched by this skill once the collision check clears or launched
+by the human when it does not. Merging is the human's gate.
 
 This skill holds the framing, the board procedure, and the dispatch. Every step
 that builds something runs an existing skill. The queue rules below decide which
@@ -101,7 +102,7 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
 1. Plan the next feature. Run `claude-feature` here, with the cross-feature context, to write a plan to `.claude/plans/`. Planning stays in this warm session so the plan front-loads reasoning a cold worker would otherwise re-derive. Every plan written from here also carries a constraint per track in flight, which the paragraph below this list states.
 2. Decide parallelism and merge order. Note which plans touch a shared wiring seam so their PRs merge in sequence, not at once.
 3. Verify the plan against the tree. Reading it is not enough, since a plan goes stale from whatever merged after it was written. Grep for each construct it names and count the sites against the count it claims. Check that every phase label it cites is still open. Open each file it describes rather than trusting its account of the contents. Correct the plan before handing it over.
-4. Hand off. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The orchestrator does not spawn workers.
+4. Hand off. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-dispatch.md` and follow it: check the branch is unclaimed, check the worker cap, then dispatch a background worker with `claude --bg`. Fall back to the human-launch line it replaces when the check refuses, the cap is reached, or the row fails Parallelism against something already in flight.
 5. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate.
    - Learning that a PR moved is the mechanical half, so read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and start the poll it carries on the first dispatch rather than checking the board by hand. That runbook holds the routing, and a summary of it here is a second source that drifts from it.
 6. Dispatch the handback. A pass posting anything owed, a finding at any severity or a testing question, tells the session holding that branch to run `claude-address-review`, rather than waiting for a person to relay it. Re-review when the answer lands, then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
@@ -126,7 +127,8 @@ Stamp the block with the commit this session read the tree at, which the same se
 - Run one orchestrator at a time. The board is gitignored, so a second session sees none of this one's writes: two task files land minutes apart under different labels for the same work, one session archives a task mid-sweep in the other, and each archives a plan the other had retargeted. An Owner column does not fix this, since neither session can read the other's rows.
 - Do not implement features in this session. Hand the plan to a worker.
 - Do not merge. Recommend merge or changes. The human merges.
-- Do not spawn worker sessions with agents. The human launches each worktree so every build is an independent, steerable stream with its own PR. The handback dispatch in step 6 reaches a session the human already launched, so it leaves this boundary where it is.
+- Do not spawn a worker with the Agent tool. An in-process subagent shares this session's context and cannot be steered or reached independently, which breaks the property this boundary protects rather than the mechanism it names. The dispatch in `orchestrator-dispatch.md` is a separate `claude --bg` process with its own worktree and its own PR, so it preserves that property instead.
+- Dispatch a background worker only once the collision check in `orchestrator-dispatch.md` clears and the worker cap still has room. Colliding with an existing worktree or session, or exceeding the cap, is what the check and the cap exist to catch, not a judgment call this session makes case by case.
 - Do not edit tracked files from this session, at any size. The boundary offers no proportionality exception and nothing enforces it.
 - Do not hand a worker anything but a plan, since scope lives there. A plan carries exact diffs only when they are already known, otherwise it states the scope and the open questions and lets the worker write the diff.
 

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

@@ -0,0 +1,44 @@
+---
+title: Orchestrator dispatch runbook
+description: The collision check before a self-dispatch, the worker cap, the launch command, 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.
+
+## Derive the candidate
+
+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>`.
+
+## 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.
+
+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.
+
+## Check the worker cap
+
+Run `aitk sessions list --json` with no `--branch`, then count entries whose `name` starts with `orchestrator-` and whose `repository` matches this run's own (`git rev-parse --path-format=absolute --git-common-dir`). An unscoped listing spans every repository on the machine, so the repository match is what keeps a busy sibling project from binding this one's cap. Every dispatch below names its session that way for exactly this count, so a worker the human launched by hand carries no such name and is never counted against it.
+
+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.
+
+## Dispatch
+
+```bash
+claude --bg -n "orchestrator-<slug>" "/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.
+
+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.
+
+## Fall back to the human
+
+Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one: the collision check refused, the cap is reached, or the row's file set failed the Parallelism test against something already out.
+
+## Stop the loop
+
+Wrapped in `/loop`, re-run the check against `## Run now` on each wake. Stop rather than firing again once the group is empty or every row in it reads `claimed: true`. Report that once, on the wake that finds it, and let the loop end rather than continuing to poll a board nobody is clearing. `orchestrator-poll.md` already carries this reasoning for the review trigger, and it binds a dispatcher the same way.

package/docs/agents/commands.md

@@ -59,11 +59,22 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk census [path]`       | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                 |
 | `aitk audits run`          | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)                               |
 | `aitk audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                                            |
+| `aitk inventory [subject]` | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`)                                 |
 | `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                                                |
 | `aitk upgrade`             | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                                                |
 
 `aitk demo` is the second browser command and the one that ships, since its purpose is running in a target rather than regenerating what this repository commits. It needs a browser binary the package does not carry, installed once with `bunx playwright install chromium`.
 
+`aitk inventory` is the third and takes the same answer for the same reason. It reads `inventory.toml` at the project root for its base URL, its routes, and the element query each subject runs over, so what it walks comes from the project rather than from the toolkit. It reports how many different answers a site gives for one property and never gates, because whether five focus rings across four routes is a defect is a judgment. A missing server and an unmatched query are both refusals rather than empty listings, since a listing with no rows reads as one consistent answer.
+
+```toml
+base-url = "http://localhost:4173"
+routes = ["/", "/pricing", "/docs"]
+
+[subjects.focus]
+query = "button, a[href], input, select, textarea, [tabindex]"
+```
+
 ## Domain commands
 
 Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.
@@ -76,6 +87,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`                                                               |
 | `claude`    | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `skills rank`, `setup [dest]` |
 | `demo`      | `compile`, `run`                                                                                                                      |
+| `inventory` | `run`                                                                                                                                 |
 | `wiki`      | `init`                                                                                                                                |
 | `design`    | `render`                                                                                                                              |
 | `slides`    | `render`, `list`                                                                                                                      |

package/docs/agents/sessions.md

@@ -34,6 +34,16 @@ A bare run reports every repository and carries a `repository` field on each row
 
 The match can return more than one session. Read the count rather than the first row, since nothing stops two sessions holding one branch, and a caller that treats the result as singular picks among candidates without knowing it.
 
+## 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).
+
+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.
+
+`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.
+
+`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.
+
 ## Why the verb exists
 
 A session listing reports a name, a kind, a status, and how long each session has been running. None of those names a branch. Resolving a branch to a session therefore meant ordering the roster by start time and matching it against the order the worktrees were created, which is an inference that fails whenever two sessions start inside the same minute.

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. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The worker 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. 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.26.1",
+  "version": "3.28.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/browser/engine.ts

@@ -0,0 +1,40 @@
+/**
+ * What every browser-driving command needs to know before it can report a
+ * failure honestly: how the binary is installed, and how each of the two ways
+ * it can be absent reads when it is thrown.
+ *
+ * The two are different states with different remedies. A package that never
+ * resolved means the target installed the CLI without the engine, and a binary
+ * that was never downloaded means the engine is present and its browser is not.
+ * Both were spelled inside `src/demo/` when `demo` was the only command driving
+ * a browser, and a second command is what makes them shared rather than local.
+ */
+
+/** Fetches the browser revision the pinned engine expects. */
+export const INSTALL_BROWSER = 'bunx playwright install chromium'
+
+/**
+ * Separates a browser binary that was never installed from every other launch
+ * failure, because the first is a setup step the operator has to run and the
+ * second is a defect. A target inherits that setup step, which is the stated
+ * cost of shipping a browser command outside the toolkit.
+ */
+export function isBrowserMissing(error: unknown): boolean {
+  const text = error instanceof Error ? error.message : String(error)
+  return /executable doesn't exist|playwright install/i.test(text)
+}
+
+/**
+ * Reports the engine package failing to resolve, which is the case a target
+ * hits before installing it. Any other import failure is a defect inside the
+ * module being loaded and propagates, rather than being reported as a missing
+ * dependency.
+ */
+export function isEngineMissing(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    error.code === 'ERR_MODULE_NOT_FOUND'
+  )
+}

package/src/cli.ts

@@ -16,6 +16,7 @@ import { register as design } from '@/commands/design'
 import { register as slides } from '@/commands/slides'
 import { register as capture } from '@/commands/capture'
 import { register as demo } from '@/commands/demo'
+import { register as inventory } from '@/commands/inventory'
 import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
@@ -59,6 +60,7 @@ function showHelp(): void {
     `${GREY}│${NC}    slides [cmd]       ${GREY}# Slide deck commands (render, list)${NC}`,
     `${GREY}│${NC}    capture [source]   ${GREY}# Render HTML capture sources to PNG${NC}`,
     `${GREY}│${NC}    demo [cmd]         ${GREY}# Record a running app (compile, run)${NC}`,
+    `${GREY}│${NC}    inventory [subj]   ${GREY}# Report one computed property across every route${NC}`,
     `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/feedback/${NC}`,
     `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
@@ -102,6 +104,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk slides render`,
     `${GREY}│${NC}    aitk slides list --json`,
     `${GREY}│${NC}    aitk capture assets/install.html`,
+    `${GREY}│${NC}    aitk inventory focus --json`,
     `${GREY}│${NC}    pbpaste | aitk feedback`,
     `${GREY}│${NC}    aitk transcripts https://youtu.be/VIDEO_ID`,
     `${GREY}│${NC}    aitk tasks archive --pull-request 673 --json`,
@@ -153,6 +156,7 @@ design(program)
 slides(program)
 capture(program)
 demo(program)
+inventory(program)
 feedback(program)
 transcripts(program)
 tasks(program)

package/src/commands/demo.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, dirname, extname, join, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
+import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
 import { parseDraft } from '@/demo/beats'
 import { compilePlan, parsePlan, unresolved } from '@/demo/compile'
 import { convertToMp4, INSTALL_CONVERTER } from '@/demo/container'
@@ -9,7 +10,6 @@ import { loadCursorTheme } from '@/demo/theme'
 import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
 
 const DEFAULT_OUT = 'demos'
-const INSTALL_BROWSER = 'bunx playwright install chromium'
 
 /**
  * Holds wiring only. Every browser reference sits behind `loadDriver`, because
@@ -359,20 +359,11 @@ async function loadDriver(): Promise<Driver | undefined> {
   try {
     return await import('@/demo/drive')
   } catch (error) {
-    if (isModuleNotFound(error)) return undefined
+    if (isEngineMissing(error)) return undefined
     throw error
   }
 }
 
-function isModuleNotFound(error: unknown): boolean {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    'code' in error &&
-    error.code === 'ERR_MODULE_NOT_FOUND'
-  )
-}
-
 /**
  * Resolves where one artifact lands. `--out` replaces the directory the plan
  * names rather than acting as a root the plan's own directory hangs off, which

package/src/commands/inventory.ts

@@ -0,0 +1,256 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
+import {
+  CONFIG_REL,
+  type ConfigRefusal,
+  readInventoryConfig,
+} from '@/inventory/config'
+import { abbreviate, groupByTreatment } from '@/inventory/group'
+import { findSubject, SUBJECTS } from '@/inventory/subjects'
+import type { WalkRefusal } from '@/inventory/walk'
+import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+/**
+ * Holds wiring only. Every browser reference sits behind `loadWalker`, because
+ * `src/cli.ts` imports this module at startup and resolving the engine there
+ * would put a browser launch in front of every other command.
+ */
+type Walker = typeof import('@/inventory/walk')
+
+interface RunOptions {
+  readonly root?: string
+  readonly baseUrl?: string
+  readonly json?: boolean
+}
+
+/** What a reader does about each way the config produced no walk. */
+const CONFIG_REFUSALS: Record<ConfigRefusal, string> = {
+  'no-config': `No ${CONFIG_REL} here, so no routes and no element query are declared.`,
+  'unreadable-config': `${CONFIG_REL} is not valid TOML, so no route could be read.`,
+  'no-routes': `${CONFIG_REL} carries no route under routes, so there is nothing to walk.`,
+  'no-base-url': `${CONFIG_REL} carries no base-url, so no route resolves to an address.`,
+  'no-subjects': `${CONFIG_REL} declares no subject, and the element query comes from this project rather than from the toolkit.`,
+}
+
+const WALK_REFUSALS: Record<WalkRefusal, string> = {
+  'browser-missing': 'The browser binary is not installed in this project.',
+  'server-unreachable':
+    'Nothing answered at the base URL, so no route was read.',
+  'walk-failed': 'The walk failed against a running server.',
+}
+
+export function register(program: Command): void {
+  const inventory = program
+    .command('inventory')
+    .description('Report one computed property across every route of a project')
+    .helpOption('-h, --help', 'Show this help message')
+
+  inventory
+    .command('run', { isDefault: true })
+    .description(
+      'Walk every route and group its elements by the answer each gives',
+    )
+    .argument('[subject]', 'Treatment to read, defaulting to focus', 'focus')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Project to read, defaulting to the cwd')
+    .option('--base-url <url>', 'Address to walk, overriding the config')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Reads ${CONFIG_REL} for the base URL, the routes, and the element query`,
+        'each subject runs over, so what gets walked comes from the project',
+        'rather than from the toolkit.',
+        '',
+        'It reports a listing and never a verdict. The value is seeing how many',
+        'different answers one site gives, and a gate collapses that to one bit.',
+        '',
+        'Needs a running server and a browser binary. Install the browser with:',
+        `  ${INSTALL_BROWSER}`,
+        '',
+        'Subjects:',
+        ...SUBJECTS.map((subject) => `  ${subject.name}  ${subject.summary}`),
+        '',
+        'Exit codes:',
+        '  0  the walk read at least one element and reported its rows',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  aitk inventory focus',
+        '  aitk inventory focus --json',
+        '  aitk inventory focus --base-url http://localhost:3000',
+        '',
+      ].join('\n'),
+    )
+    .action(async (subject: string, opts: RunOptions) => {
+      process.exitCode = await runInventory(subject, opts)
+    })
+}
+
+async function runInventory(
+  subjectName: string,
+  opts: RunOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro(`aitk inventory ${subjectName}`)
+
+  const subject = findSubject(subjectName)
+  if (!subject) {
+    const known = SUBJECTS.map((entry) => entry.name).join(', ')
+    return refuse(
+      emitJson,
+      root,
+      'unknown-subject',
+      `No reader named ${subjectName}. This build ships: ${known}.`,
+    )
+  }
+
+  const read = readInventoryConfig(root)
+  if (read.kind === 'refused') {
+    return refuse(emitJson, root, read.reason, CONFIG_REFUSALS[read.reason])
+  }
+
+  const declared = read.config.subjects.find(
+    (entry) => entry.name === subjectName,
+  )
+  if (!declared) {
+    const named = read.config.subjects.map((entry) => entry.name).join(', ')
+    return refuse(
+      emitJson,
+      root,
+      'undeclared-subject',
+      `${CONFIG_REL} declares no query for ${subjectName}. It declares: ${named}.`,
+    )
+  }
+
+  const baseUrl = opts.baseUrl ?? read.config.baseUrl
+
+  logStep('Scope')
+  logInfo(
+    `${plural(read.config.routes.length, 'route')} from ${baseUrl}, matching ${declared.query}`,
+  )
+
+  const walker = await loadWalker()
+  if (!walker) {
+    logStep('Browser')
+    logError('the browser engine is not installed in this project')
+    logWarn(`Install it with: ${INSTALL_BROWSER}`)
+    outro()
+    emit(emitJson, {
+      root,
+      subject: subjectName,
+      reason: 'engine-missing',
+      install: INSTALL_BROWSER,
+    })
+    return 1
+  }
+
+  const result = await walker.walk({
+    baseUrl,
+    routes: read.config.routes,
+    subject,
+    query: declared.query,
+  })
+
+  if (result.status === 'failed') {
+    logStep('Refused')
+    logWarn(WALK_REFUSALS[result.reason])
+    if (result.reason === 'server-unreachable') {
+      logWarn(`Start the project at ${baseUrl}, then run this again.`)
+    }
+    if (result.reason === 'browser-missing') {
+      logWarn(`Install the browser binary with: ${INSTALL_BROWSER}`)
+    }
+    logWarn(result.message.split('\n')[0] ?? '')
+    outro()
+    emit(emitJson, {
+      root,
+      subject: subjectName,
+      baseUrl,
+      reason: result.reason,
+      message: result.message,
+      ...(result.reason === 'browser-missing'
+        ? { install: INSTALL_BROWSER }
+        : {}),
+    })
+    return 1
+  }
+
+  const groups = groupByTreatment(result.readings)
+
+  logStep('Routes')
+  for (const route of result.routes) {
+    logInfo(`${route.route}  ${plural(route.elements, 'element')}`)
+  }
+
+  // A walk that matched nothing refuses rather than printing an empty listing,
+  // because no rows and one row read the same to anything counting them, and
+  // the first says the query reached nothing while the second says the site
+  // gives one consistent answer.
+  if (groups.length === 0) {
+    return refuse(
+      emitJson,
+      root,
+      'no-elements',
+      `No element matched ${declared.query} on any of the ${plural(result.routes.length, 'route')} walked.`,
+    )
+  }
+
+  logStep('Treatments')
+  logInfo(
+    `${plural(groups.length, 'answer')} across ${plural(result.readings.length, 'element')}`,
+  )
+  for (const group of groups) {
+    logInfo(`  ${group.count}x  ${group.treatment}`)
+    logInfo(
+      `      ${abbreviate(group.samples, group.count)} on ${abbreviate(group.routes, group.routes.length)}`,
+    )
+  }
+  outro()
+
+  emit(emitJson, {
+    root,
+    subject: subjectName,
+    baseUrl,
+    routes: result.routes,
+    elements: result.readings.length,
+    treatments: groups,
+    durationMs: result.durationMs,
+  })
+  return 0
+}
+
+/**
+ * Frames a refusal on stderr and puts the record on stdout, so an operator
+ * reading the terminal sees the reason rather than a command that appeared to
+ * do nothing.
+ */
+function refuse(
+  emitJson: boolean,
+  root: string,
+  reason: string,
+  message: string,
+): number {
+  logStep('Refused')
+  logWarn(message)
+  outro()
+  emit(emitJson, { root, reason, message })
+  return 1
+}
+
+async function loadWalker(): Promise<Walker | undefined> {
+  try {
+    return await import('@/inventory/walk')
+  } catch (error) {
+    if (isEngineMissing(error)) return undefined
+    throw error
+  }
+}
+
+function emit(json: boolean, record: unknown): void {
+  if (json) process.stdout.write(`${JSON.stringify(record)}\n`)
+}

package/src/commands/sessions.ts

@@ -1,4 +1,5 @@
 import type { Command } from 'commander'
+import { checkClaim, type ClaimReport } from '@/sessions/claim'
 import {
   repositoryOf,
   type ResolvedSession,
@@ -58,6 +59,18 @@ export function register(program: Command): void {
         'A bare run reports every repository and carries the repository field,',
         '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.',
+        '',
+        '"sessionsReadable" is false when the session roster could not be read,',
+        'which leaves "claimed" covering the worktree half alone. Treat that',
+        'case as unverified rather than as a clean "false".',
+        '',
         'The match can return more than one session. Read the count rather than',
         'the first row, since two sessions can hold one branch.',
         '',
@@ -132,9 +145,17 @@ async function runList(opts: ListCommandOptions): Promise<number> {
       )
     : report.sessions
 
+  const claim = opts.branch
+    ? await checkClaim(opts.branch, {
+        cwd: process.cwd(),
+        resolve: async () => report,
+      })
+    : null
+
   intro('aitk sessions list')
   reportConfidence(report)
   reportSessions(shown, opts.branch, repository)
+  if (claim) reportClaim(claim)
   outro()
 
   if (opts.json) {
@@ -144,6 +165,9 @@ async function runList(opts: ListCommandOptions): Promise<number> {
         confidence: report.confidence,
         branch: opts.branch ?? null,
         repository,
+        worktree: claim?.worktree ?? null,
+        claimed: claim?.claimed ?? null,
+        sessionsReadable: claim?.sessionsReadable ?? null,
         sessions: shown,
       })}\n`,
     )
@@ -229,3 +253,19 @@ function reportSessions(
       .join('\n'),
   )
 }
+
+function reportClaim(claim: ClaimReport): void {
+  logStep('Claim')
+
+  if (claim.worktree) {
+    logInfo(`Worktree: ${claim.worktree}`)
+  }
+
+  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.',
+    )
+  }
+}

package/src/demo/drive.ts

@@ -3,6 +3,7 @@ import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { chromium } from 'playwright-core'
 import type { Browser, BrowserContext, Page } from 'playwright-core'
+import { isBrowserMissing } from '@/browser/engine'
 import { deriveSteps } from '@/demo/compile'
 import type { DemoPlan, DemoStep } from '@/demo/compile'
 import type { CursorSet } from '@/demo/pointer'
@@ -181,20 +182,17 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
 }
 
 /**
- * Separates a browser binary that was never installed from every other launch
- * failure, because the first is a setup step the operator has to run and the
- * second is a defect. A target inherits that setup step, which is the stated
- * cost of shipping this command outside the toolkit.
+ * Reads the launch through `@/browser/engine`, which is where the separation
+ * between a binary that was never installed and every other launch failure now
+ * lives. It moved out of this file when `aitk inventory` became the second
+ * command needing it, rather than being copied.
  */
 async function launch(): Promise<Launch> {
   try {
     return { status: 'launched', value: await chromium.launch() }
   } catch (error) {
-    const text = error instanceof Error ? error.message : String(error)
     return failed(
-      /executable doesn't exist|playwright install/i.test(text)
-        ? 'browser-missing'
-        : 'drive-failed',
+      isBrowserMissing(error) ? 'browser-missing' : 'drive-failed',
       error,
     )
   }

package/src/inventory/config.ts

@@ -0,0 +1,117 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Where a project declares what an inventory walks, spelled once.
+ *
+ * It sits at the project root rather than under `.claude/`, because the routes
+ * and the element queries describe the application rather than the agent
+ * surface, and a target reads them the way it reads any other build input.
+ */
+export const CONFIG_REL = 'inventory.toml'
+
+/** One measurable treatment and the elements that carry it, as the project spells them. */
+export interface InventorySubject {
+  readonly name: string
+  readonly query: string
+}
+
+export interface InventoryConfig {
+  readonly baseUrl: string
+  readonly routes: readonly string[]
+  readonly subjects: readonly InventorySubject[]
+}
+
+/**
+ * Why a config could not be used, which is never the same as a walk that read
+ * nothing.
+ *
+ * Every value here is a refusal rather than an empty listing, because a listing
+ * with no rows reads as a site giving one consistent answer, which is the
+ * report an unconfigured project would get for free and the exact wrong reading.
+ */
+export type ConfigRefusal =
+  | 'no-config'
+  | 'unreadable-config'
+  | 'no-base-url'
+  | 'no-routes'
+  | 'no-subjects'
+
+export type ConfigRead =
+  | { readonly kind: 'config'; readonly config: InventoryConfig }
+  | { readonly kind: 'refused'; readonly reason: ConfigRefusal }
+
+function readSubjects(table: unknown): InventorySubject[] {
+  if (typeof table !== 'object' || table === null || Array.isArray(table)) {
+    return []
+  }
+
+  const subjects: InventorySubject[] = []
+  for (const [name, value] of Object.entries(table)) {
+    if (typeof value !== 'object' || value === null) continue
+    const query = (value as Record<string, unknown>).query
+    if (typeof query !== 'string' || query === '') continue
+    subjects.push({ name, query })
+  }
+
+  return subjects
+}
+
+/**
+ * Parses config text, so a caller holding the bytes skips the filesystem.
+ *
+ * A malformed route or subject is dropped rather than refused, matching the row
+ * handling in `@/labels/map`: one bad entry should not blind the walk to the
+ * other twenty. What that costs is a typo reading as an entry nobody wrote,
+ * which the listing surfaces from the other side as a route with no elements.
+ */
+export function parseInventoryConfig(source: string): ConfigRead {
+  let parsed: Record<string, unknown>
+  try {
+    parsed = Bun.TOML.parse(source) as Record<string, unknown>
+  } catch {
+    return { kind: 'refused', reason: 'unreadable-config' }
+  }
+
+  const baseUrl = parsed['base-url']
+  if (typeof baseUrl !== 'string' || baseUrl === '') {
+    return { kind: 'refused', reason: 'no-base-url' }
+  }
+
+  const routes = Array.isArray(parsed.routes)
+    ? parsed.routes.filter(
+        (route): route is string => typeof route === 'string' && route !== '',
+      )
+    : []
+  if (routes.length === 0) return { kind: 'refused', reason: 'no-routes' }
+
+  const subjects = readSubjects(parsed.subjects)
+  if (subjects.length === 0) return { kind: 'refused', reason: 'no-subjects' }
+
+  return { kind: 'config', config: { baseUrl, routes, subjects } }
+}
+
+/** Reads the config a project declares at `root`, or says why it could not. */
+export function readInventoryConfig(root: string): ConfigRead {
+  let source: string
+  try {
+    source = readFileSync(join(root, CONFIG_REL), 'utf8')
+  } catch {
+    return { kind: 'refused', reason: 'no-config' }
+  }
+
+  return parseInventoryConfig(source)
+}
+
+/**
+ * Joins a base and a route into the address a walk opens.
+ *
+ * Concatenation rather than `new URL(route, base)`, because the resolver reads
+ * a leading slash as absolute and drops any path the base already carries, so a
+ * project served under a subdirectory would have every route walk the origin.
+ */
+export function routeUrl(baseUrl: string, route: string): string {
+  const base = baseUrl.replace(/\/+$/, '')
+  const path = route.startsWith('/') ? route : `/${route}`
+  return `${base}${path}`
+}

package/src/inventory/group.ts

@@ -0,0 +1,76 @@
+/**
+ * How many elements a row names before it stops naming them. A row exists to
+ * say how many answers a site gives, and the elements under it are there to
+ * make one findable rather than to enumerate the set.
+ */
+export const SAMPLE_LIMIT = 3
+
+/**
+ * Names a bounded head of a list and says how many it left out, so a treatment
+ * carried by fifty routes reads as fifty rather than as the three named.
+ *
+ * `total` arrives separately because the two lists reach here differently. A
+ * row's samples are already capped when they are collected, so their own length
+ * cannot say how many elements the row covers, while its routes arrive whole.
+ */
+export function abbreviate(entries: readonly string[], total: number): string {
+  const head = entries.slice(0, SAMPLE_LIMIT)
+  const elided = total - head.length
+  return elided > 0 ? `${head.join(', ')} and ${elided} more` : head.join(', ')
+}
+
+/** One element as the walk read it, on the route it was read from. */
+export interface Reading {
+  readonly route: string
+  readonly selector: string
+  readonly treatment: string
+}
+
+/** One answer the site gives, and what carries it. */
+export interface TreatmentGroup {
+  readonly treatment: string
+  readonly count: number
+  readonly routes: readonly string[]
+  readonly samples: readonly string[]
+}
+
+/**
+ * Turns a per-element walk into a per-answer listing, which is the whole point
+ * of the command.
+ *
+ * Grouping by the component instead was the obvious shape and it reports what a
+ * reader already knows, that a site has buttons and links. Grouping by the
+ * computed answer reports the thing nobody can see while building, which is
+ * that five components resolved to five different rings.
+ *
+ * Order is heaviest first, then by treatment, so the dominant answer leads and
+ * two runs over one site report one order rather than whatever the walk hit.
+ */
+export function groupByTreatment(
+  readings: readonly Reading[],
+): readonly TreatmentGroup[] {
+  const byTreatment = new Map<
+    string,
+    { count: number; routes: string[]; samples: string[] }
+  >()
+
+  for (const { route, selector, treatment } of readings) {
+    const row = byTreatment.get(treatment) ?? {
+      count: 0,
+      routes: [],
+      samples: [],
+    }
+    row.count += 1
+    if (!row.routes.includes(route)) row.routes.push(route)
+    if (row.samples.length < SAMPLE_LIMIT) row.samples.push(selector)
+    byTreatment.set(treatment, row)
+  }
+
+  return [...byTreatment.entries()]
+    .map(([treatment, row]) => ({ treatment, ...row }))
+    .sort(
+      (left, right) =>
+        right.count - left.count ||
+        left.treatment.localeCompare(right.treatment),
+    )
+}

package/src/inventory/subjects.ts

@@ -0,0 +1,114 @@
+/**
+ * The readers an inventory can run, one per treatment.
+ *
+ * A reader runs inside the page rather than here, so each one is serialized to
+ * source and evaluated by the browser. That is why every helper a reader needs
+ * is declared inside its own body: a reference to anything at module scope
+ * survives typechecking and throws once the page tries to call it.
+ *
+ * `focus` is the first and, for now, the only subject. The four sibling
+ * instruments this shape was lifted from differ only in their element query and
+ * the property they read, which is what makes a subject a row here rather than
+ * a command of its own.
+ */
+
+/** One element as a reader saw it, before any grouping. */
+export interface SubjectReading {
+  readonly selector: string
+  readonly treatment: string
+}
+
+export interface Subject {
+  readonly name: string
+  /** What the listing means, printed above the rows so a count reads correctly. */
+  readonly summary: string
+  readonly read: (query: string) => SubjectReading[]
+}
+
+/**
+ * Reports what each element changes about itself when it takes focus, which is
+ * the reading `governance/rules/ui/410-a11y.md` states three rules against and
+ * nothing measures.
+ *
+ * The difference between rest and focus is the treatment, rather than the
+ * focused style on its own. A card carrying a resting shadow computes a shadow
+ * either way, so reading only the focused state would report a ring on an
+ * element whose appearance never moves.
+ *
+ * An element the browser refuses to focus is named as such rather than folded
+ * into the no-treatment row, since a disabled control and a control with no
+ * ring are different findings with different remedies.
+ */
+function readFocusTreatments(query: string): SubjectReading[] {
+  const PROPERTIES = [
+    'outlineStyle',
+    'outlineWidth',
+    'outlineColor',
+    'outlineOffset',
+    'boxShadow',
+    'borderColor',
+    'backgroundColor',
+    'color',
+  ] as const
+
+  const describe = (element: Element): string => {
+    const tag = element.tagName.toLowerCase()
+    if (element.id) return `${tag}#${element.id}`
+    const className = element.getAttribute('class')?.trim().split(/\s+/)[0]
+    return className ? `${tag}.${className}` : tag
+  }
+
+  const snapshot = (element: Element): Record<string, string> => {
+    const computed = getComputedStyle(element)
+    const values: Record<string, string> = {}
+    for (const property of PROPERTIES) values[property] = computed[property]
+    return values
+  }
+
+  const rows: SubjectReading[] = []
+
+  // The walk presses Tab before this runs, which leaves one element focused.
+  // Reading that element's rest state while it holds focus reports no
+  // difference and hides whatever ring it actually draws, so the page starts
+  // from nothing focused and every element is blurred again after its turn.
+  const entryFocus = document.activeElement
+  if (entryFocus instanceof HTMLElement) entryFocus.blur()
+
+  for (const element of Array.from(document.querySelectorAll(query))) {
+    if (!(element instanceof HTMLElement)) continue
+
+    const rest = snapshot(element)
+    element.focus()
+    if (document.activeElement !== element) {
+      rows.push({ selector: describe(element), treatment: 'not focusable' })
+      continue
+    }
+
+    const focused = snapshot(element)
+    const changed = PROPERTIES.filter(
+      (property) => rest[property] !== focused[property],
+    ).map((property) => `${property} ${focused[property]}`)
+
+    rows.push({
+      selector: describe(element),
+      treatment:
+        changed.length === 0 ? 'no visible change' : changed.join(', '),
+    })
+    element.blur()
+  }
+
+  return rows
+}
+
+const FOCUS: Subject = {
+  name: 'focus',
+  summary: 'what each element changes about itself when it takes focus',
+  read: readFocusTreatments,
+}
+
+export const SUBJECTS: readonly Subject[] = [FOCUS]
+
+/** Resolves a subject by name, so an unknown one is the caller's to report. */
+export function findSubject(name: string): Subject | undefined {
+  return SUBJECTS.find((subject) => subject.name === name)
+}

package/src/inventory/walk.ts

@@ -0,0 +1,129 @@
+import { chromium } from 'playwright-core'
+import type { Browser } from 'playwright-core'
+import { isBrowserMissing } from '@/browser/engine'
+import { routeUrl } from '@/inventory/config'
+import type { Reading } from '@/inventory/group'
+import type { Subject } from '@/inventory/subjects'
+
+/**
+ * Walks a running application and reads one property off every element a
+ * subject names. Every browser reference the inventory feature adds lives here,
+ * and `src/commands/inventory.ts` reaches it through a dynamic import so no
+ * other command resolves the engine at startup.
+ *
+ * Like `@/demo/drive` and unlike `@/capture/render`, this module ships, because
+ * a command whose whole purpose is running inside someone else's project cannot
+ * stay toolkit-only.
+ */
+
+/**
+ * The reader and the query arrive apart because they come from different
+ * owners. The toolkit ships the reader and the project declares which elements
+ * it runs over, which is what keeps the walk answering to the target rather
+ * than to a fixed selector nobody there chose.
+ */
+export interface WalkOptions {
+  readonly baseUrl: string
+  readonly routes: readonly string[]
+  readonly subject: Subject
+  readonly query: string
+}
+
+/** A route that answered, and the elements read off it. */
+export interface RouteReading {
+  readonly route: string
+  readonly elements: number
+}
+
+export type WalkRefusal =
+  | 'browser-missing'
+  | 'server-unreachable'
+  | 'walk-failed'
+
+export type WalkResult =
+  | {
+      readonly status: 'read'
+      readonly readings: readonly Reading[]
+      readonly routes: readonly RouteReading[]
+      readonly durationMs: number
+    }
+  | {
+      readonly status: 'failed'
+      readonly reason: WalkRefusal
+      readonly message: string
+    }
+
+function failed(reason: WalkRefusal, error: unknown): WalkResult {
+  return {
+    status: 'failed',
+    reason,
+    message: error instanceof Error ? error.message : String(error),
+  }
+}
+
+/**
+ * Separates a server nobody started from a page that failed for its own
+ * reasons. The first is the precondition this command cannot create, and
+ * reporting it as an empty listing would say the site gives no answers when
+ * nothing was ever asked.
+ */
+function isServerUnreachable(error: unknown): boolean {
+  const text = error instanceof Error ? error.message : String(error)
+  return /ERR_CONNECTION_REFUSED|ERR_NAME_NOT_RESOLVED|ERR_CONNECTION_RESET|ERR_EMPTY_RESPONSE/i.test(
+    text,
+  )
+}
+
+export async function walk(options: WalkOptions): Promise<WalkResult> {
+  const started = Date.now()
+
+  let browser: Browser
+  try {
+    browser = await chromium.launch()
+  } catch (error) {
+    return failed(
+      isBrowserMissing(error) ? 'browser-missing' : 'walk-failed',
+      error,
+    )
+  }
+
+  const readings: Reading[] = []
+  const routes: RouteReading[] = []
+
+  try {
+    const page = await browser.newPage()
+
+    for (const route of options.routes) {
+      await page.goto(routeUrl(options.baseUrl, route), {
+        waitUntil: 'domcontentloaded',
+      })
+
+      // Puts the page in keyboard modality before anything is focused, because
+      // a `:focus-visible` ring is the treatment a pointer never reveals and
+      // programmatic focus alone does not match it.
+      await page.keyboard.press('Tab')
+
+      const rows = await page.evaluate(options.subject.read, options.query)
+      for (const row of rows) readings.push({ route, ...row })
+      routes.push({ route, elements: rows.length })
+    }
+  } catch (error) {
+    return failed(
+      isServerUnreachable(error) ? 'server-unreachable' : 'walk-failed',
+      error,
+    )
+  } finally {
+    // The rejection is dropped rather than propagated, because a close that
+    // fails beside a walk that already failed would replace the refusal the
+    // caller was about to receive with a reason about teardown. Nothing the
+    // caller does depends on the browser having closed cleanly.
+    await browser.close().catch(() => undefined)
+  }
+
+  return {
+    status: 'read',
+    readings,
+    routes,
+    durationMs: Date.now() - started,
+  }
+}

package/src/sessions/claim.ts

@@ -0,0 +1,59 @@
+import {
+  repositoryOf,
+  resolveSessions,
+  type ResolvedSession,
+  type SessionReport,
+} from '@/sessions/resolve'
+import { listWorktrees, 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". */
+  readonly sessionsReadable: boolean
+}
+
+export interface ClaimOptions {
+  readonly cwd?: string
+  readonly resolve?: () => Promise<SessionReport>
+  readonly listWorktrees?: (cwd: string) => Promise<readonly WorktreeEntry[]>
+}
+
+/**
+ * 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.
+ */
+export async function checkClaim(
+  branch: string,
+  opts: ClaimOptions = {},
+): Promise<ClaimReport> {
+  const cwd = opts.cwd ?? process.cwd()
+  const resolve = opts.resolve ?? resolveSessions
+  const listAll = opts.listWorktrees ?? listWorktrees
+
+  const [repository, worktrees, report] = await Promise.all([
+    repositoryOf(cwd),
+    listAll(cwd),
+    resolve(),
+  ])
+
+  const worktree =
+    worktrees.find((entry) => entry.branch === branch)?.path ?? null
+
+  const sessions =
+    report.kind === 'resolved'
+      ? report.sessions.filter(
+          (session) =>
+            session.branch === branch && session.repository === repository,
+        )
+      : []
+
+  return {
+    claimed: worktree !== null || sessions.length > 0,
+    worktree,
+    sessions,
+    sessionsReadable: report.kind === 'resolved',
+  }
+}

package/src/sessions/resolve.ts

@@ -1,4 +1,5 @@
 import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
 import {
   type Confidence,
   liveness,
@@ -67,7 +68,10 @@ export interface Located {
  * that has a worktree and no branch and the second has neither.
  */
 async function locate(cwd: string): Promise<Located> {
-  const top = await $`git -C ${cwd} rev-parse --show-toplevel`.quiet().nothrow()
+  const top = await $`git -C ${cwd} rev-parse --show-toplevel`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
 
   if (top.exitCode !== 0) {
     // git absent and git refusing the directory are both non-zero here. The
@@ -85,7 +89,10 @@ async function locate(cwd: string): Promise<Located> {
 
   const worktree = top.stdout.toString().trim()
   const repository = await repositoryOf(cwd)
-  const head = await $`git -C ${cwd} branch --show-current`.quiet().nothrow()
+  const head = await $`git -C ${cwd} branch --show-current`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
   const branch = head.stdout.toString().trim()
 
   if (head.exitCode !== 0 || branch.length === 0) {
@@ -105,6 +112,7 @@ async function locate(cwd: string): Promise<Located> {
 export async function repositoryOf(cwd: string): Promise<string | null> {
   const dir =
     await $`git -C ${cwd} rev-parse --path-format=absolute --git-common-dir`
+      .env(gitEnv())
       .quiet()
       .nothrow()
 

package/src/worktree.ts

@@ -1,4 +1,5 @@
 import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
 
 /**
  * Resolves the root of the checkout the caller is standing in, which is the
@@ -10,7 +11,10 @@ import { $ } from 'bun'
  * subdirectory would resolve a root holding none of the trees a verb reads.
  */
 export async function currentWorktreeRoot(): Promise<string> {
-  const result = await $`git rev-parse --show-toplevel`.quiet().nothrow()
+  const result = await $`git rev-parse --show-toplevel`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
   if (result.exitCode !== 0) return process.cwd()
 
   return result.stdout.toString().trim() || process.cwd()
@@ -27,7 +31,10 @@ export async function currentWorktreeRoot(): Promise<string> {
  * root in-process is the route a skill body has.
  */
 export async function mainWorktreeRoot(): Promise<string> {
-  const result = await $`git worktree list --porcelain`.quiet().nothrow()
+  const result = await $`git worktree list --porcelain`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
   if (result.exitCode !== 0) return process.cwd()
 
   const line = result.stdout
@@ -37,3 +44,47 @@ export async function mainWorktreeRoot(): Promise<string> {
 
   return line ? line.slice('worktree '.length).trim() : process.cwd()
 }
+
+export interface WorktreeEntry {
+  readonly path: string
+  readonly branch: string | null
+}
+
+/**
+ * Parses `git worktree list --porcelain`, which emits one block per worktree
+ * separated by a blank line. A detached worktree carries no `branch` line,
+ * reported here as `null` rather than a guessed name.
+ */
+export async function listWorktrees(
+  cwd: string = process.cwd(),
+): Promise<readonly WorktreeEntry[]> {
+  const result = await $`git -C ${cwd} worktree list --porcelain`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return []
+
+  const entries: WorktreeEntry[] = []
+  let path: string | undefined
+  let branch: string | null = null
+
+  for (const line of result.stdout.toString().split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (path !== undefined) entries.push({ path, branch })
+      path = line.slice('worktree '.length).trim()
+      branch = null
+      continue
+    }
+
+    if (line.startsWith('branch ')) {
+      const ref = line.slice('branch '.length).trim()
+      branch = ref.startsWith('refs/heads/')
+        ? ref.slice('refs/heads/'.length)
+        : ref
+    }
+  }
+
+  if (path !== undefined) entries.push({ path, branch })
+
+  return entries
+}