@erclx/aitk 0.91.1 → 0.92.0

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

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

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

@@ -39,7 +39,7 @@ Poll GitHub for pull request movement by running <POLL_SCRIPT>, then act on what
 - A line starting `poll:`: report it verbatim and treat that pull request as unread this run. It is a failed query, not a state.
 - Nothing changed: say exactly "No movement." and nothing else.
 
-After any pass that posts a critical or should-fix finding, tell the session holding that branch to run the aitk:claude-address-review skill, resolving it from a session listing taken at that moment. Name the worktree and branch you believe the reader holds and ask to be corrected. Report the invocation for me instead when no live session holds it. A pass carrying only minor findings dispatches nobody.
+After any pass that posts a critical or should-fix finding, tell the session holding that branch to run the aitk:claude-address-review skill. Resolve the target by running `aitk sessions list --branch <branch> --json` at that moment, which scopes the match to this repository, then route on how many sessions it returned. Zero: report the invocation for me and dispatch nobody. Exactly one, with the confidence field reading "confirmed": address that name directly. Any other count, any other confidence, or a command that is missing or refuses: fall back to picking from a session listing, open by naming the worktree and branch you believe the reader holds, and ask to be corrected. Two sessions can hold one branch, so read the count rather than the first row. A pass carrying only minor findings dispatches nobody.
 ```
 
 ## Reading the output

package/claude/skills/toolkit-operator/REQUIREMENT.md

@@ -15,7 +15,9 @@ The third failure is duplication. A front door that answers everything itself re
 
 A fourth failure sits between the router and what it runs. This skill executes the install and sync commands whose effect on an existing file is invisible from the command line, and the reference stating that effect per surface is named in the boundary below, which Claude Code never loads. The router therefore overwrites a customized golden config with the answer sitting one skill away and unread.
 
-The last failure is writing without re-checking. A domain sync brought a stricter standard into a target and left ten of its eleven context entries non-compliant in the same moment, and the run reported success because reporting the command was where its work ended. A person found the breakage afterwards by running an audit by hand. The audit that would have caught it is built and reachable from nothing the router offers, so one session held both the defect and its detector and connected neither to the other.
+The fifth failure is writing without re-checking. A domain sync brought a stricter standard into a target and left ten of its eleven context entries non-compliant in the same moment, and the run reported success because reporting the command was where its work ended. A person found the breakage afterwards by running an audit by hand. The audit that would have caught it is built and reachable from nothing the router offers, so one session held both the defect and its detector and connected neither to the other.
+
+The last failure is a section no route reaches. `## Route` maps an intent or a diagnostic finding to one lifecycle phase, so audit offers sitting below that table with no row naming them are unreachable by a correct reading. Two runs asked what the toolkit could measure and both took the scaffold handoff, the row the table declares. A route in settles half of it, since a project carrying a context folder and no installed domain fires the scaffold row and two audit conditions at once, and a body ranking neither leaves the choice to whichever the session read last.
 
 ## Must
 
@@ -26,6 +28,8 @@ The last failure is writing without re-checking. A domain sync brought a stricte
 - Read the overwrite contract from the body before any install or sync, and name each surface it lists as overwritten before running one
 - Read the reverse walk beside the forward sections, so a folder the toolkit stopped shipping and a migration with a live case both reach the user
 - Hand off a named migration to the skill the report names, the way an unmigrated domain reaches `migration-standards`
+- Route a measurement intent to the audit offers from the route table itself, rather than leaving the section reachable only by reading past the table
+- Rank a lifecycle row against the audit offers where the route table itself states it, so a session acting on the lifecycle row reads the ranking without opening the section being ranked
 - Offer every audit whose surface the target carries, and offer none whose surface it lacks
 - Re-check the target after any operation that wrote, and report what those writes changed against the state read before acting
 
@@ -52,3 +56,5 @@ The last failure is writing without re-checking. A domain sync brought a stricte
 - Seed and preamble drift in installed files: `claude-seed-sync`
 - Governance rule install and index bootstrap: `setup-gov` and `setup-indexes`
 - What a given sync overwrites once it runs: `toolkit-cli`
+
+That last contract carries no row for the governance install this skill routes to, so the overwrite `Must` above reads nothing at one of its own destinations. The row belongs to the skill owning the table. This file records the silence rather than answering it, since a rule written here for a silent contract teaches a session that silence means safe.

package/claude/skills/toolkit-operator/SKILL.md

@@ -38,7 +38,9 @@ A `reverse` key the report does not carry at all is a CLI predating the field ra
 
 ## Route
 
-Map the stated intent, or what `## Diagnose` found, to one lifecycle phase, then act:
+Map the stated intent, or what `## Diagnose` found, to one lifecycle phase, then act.
+
+The two can name different rows, and a reply answers both rather than picking one. Run or hand off what the finding names, then answer the intent in the same reply. A measurement intent therefore reaches the audit offers below even on a target whose diagnostic found scaffold work, which is the case a session leaving from the scaffold row would otherwise never read.
 
 - A domain in `unmigrated`: hand off to `migration-standards`
 - An entry in `migrations`: hand off to the skill its `skill` field names, spelled as the report spells it. Both of them propose without writing, so the handoff is where this stops
@@ -52,9 +54,12 @@ Map the stated intent, or what `## Diagnose` found, to one lifecycle phase, then
 - Install one snippet, standard, or rule: run the domain `install` command
 - Sync one domain or every installed domain: run `aitk <domain> sync` or `aitk sync`
 - Fix only the ignore entries of the installed stack: run `aitk tooling inject --gitignore <stack>`
+- Measure a surface without changing it: offer the audits under `### Audits`
 - Browse what is available: run `aitk <domain> list`
 
-That row runs on a measured tooling report alone, so `measured` decides before `chain` is read at all. A false one splits three ways. Report tooling as unmeasured in each, name the cause, and run nothing, since the zero counts underneath are unmeasured rather than clean:
+### The ignore-only row
+
+The ignore-only row runs on a measured tooling report alone, so `measured` decides before `chain` is read at all. A false one splits three ways. Report tooling as unmeasured in each, name the cause, and run nothing, since the zero counts underneath are unmeasured rather than clean:
 
 - An empty `chain` at a workspace root, which carries `pnpm-workspace.yaml` or a `workspaces` key in `package.json`: no chain is recorded there by design, since one would guess at what the packages hold. Name `aitk tooling sync <stack> <path>` against a package.
 - An empty `chain` anywhere else: no tooling install is recorded, so name `aitk tooling sync` as the command that records one rather than asking the user for a stack.
@@ -66,6 +71,8 @@ On a measured report, take `<stack>` from the first name in `tooling.chain`, whi
 
 Four audits measure a surface without changing it. Offer the ones whose surface the target carries, list them together, and let the user pick. Run none of them unasked, and never treat a finding as a reason to abandon the operation the user asked for, since each reports judgments beside facts.
 
+A lifecycle row and these offers fire together on a project carrying a context folder and no installed domain, which is the ranking the preamble states. Scaffold work on a target with nothing installed is real work, so an audit offered instead of it answers a question nobody asked, while an audit dropped in favor of it loses the one the user did.
+
 - `.claude/context/` present: offer `aitk context audit`
 - A record folder present under `.claude/`, one of `plans`, `groundwork`, `intake`, or `memory`: offer `aitk records validate <kind>` for each one found
 - Markdown that git lists: offer `aitk markdown audit`

package/docs/agents/capture.md

@@ -17,6 +17,8 @@ aitk capture assets --out .claude/review/captures
 
 Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `aitk capture assets/hero.html` when the check reports the HTML changed.
 
+Every render writes a stamp beside its PNG, `hero.png` next to `hero.stamp`, holding the source filename, a `source-sha256` over the markup bytes it read, and an `image-sha256` over the image bytes it wrote. Both digests are what `bun run check` compares, so a markup edit committed without a capture and a PNG swapped under unchanged markup each fail. The stamp is tracked and commits alongside the pair. Nothing hand-edits it, and a capture that cannot write it reports that source as failed and exits 1, so an image whose stamp never landed is reported rather than passed over.
+
 | Option             | Behavior                                          |
 | ------------------ | ------------------------------------------------- |
 | `--out <dir>`      | Write every PNG here instead of beside its source |

package/docs/agents/commands.md

@@ -35,6 +35,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk records validate`    | Report a session record against the standard governing it, per kind (`--json`)                                                            |
 | `aitk records push`        | Commit the eight backed record folders and push them to a private records remote (`--json`)                                               |
 | `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                   |
+| `aitk sessions list`       | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                            |
 | `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                                    |
 | `aitk context audit`       | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift |
 | `aitk markdown audit`      | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                    |

package/docs/agents/index.md

@@ -23,5 +23,6 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Records](records.md): Validating the gitignored session records under .claude/, the per-kind checks, the refusal reasons, backing the folders to a private remote, and why the root defaults to the main worktree
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
+- [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, and the requirement gate that is the only failing one
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board checks validate runs, and why the board root defaults to the main worktree

package/docs/agents/sessions.md

@@ -0,0 +1,67 @@
+---
+title: Sessions
+description: Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on
+---
+
+# Sessions
+
+## List
+
+`aitk sessions list` reports every live Claude Code session on the machine with the working directory and branch it holds.
+
+```bash
+aitk sessions list
+aitk sessions list --json
+aitk sessions list --branch feat/parser --json
+```
+
+| Option            | Behavior                                     |
+| ----------------- | -------------------------------------------- |
+| `--json`          | Add a machine-readable record on stdout      |
+| `--branch <name>` | Report the sessions holding this branch here |
+
+It reads and never writes. The question it answers is which session to address when work has to reach the one holding a given branch, which a session listing cannot answer on its own.
+
+Exit codes: `0` the roster was read, `1` refused. The refusal carries a `reason` of `no-registry` or `no-repository`.
+
+## Scope and count
+
+`--branch` scopes the match to the repository the command runs in, and refuses outside one. A branch name identifies a branch inside a repository and nothing across a machine, so an unscoped match reaches a session working in a different project, and `main` collides on every machine running two of them.
+
+A bare run reports every repository and carries a `repository` field on each row, holding the shared git directory that a main checkout and all its linked worktrees agree on. That is what a caller filters on when it wants a scope of its own.
+
+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.
+
+## 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.
+
+Each session writes its own record on disk carrying its working directory beside its own name. This verb reads those records, so a name joins to a branch by an exact match on one file rather than by a guess across two orderings.
+
+## What a row carries
+
+Every row names the session, the process holding it, its working directory, and the branch checked out there. The status field repeats what the session listing reports, so a caller picking a target reads one output instead of two.
+
+A field the record did not carry is reported as null rather than as a value, so an absent start time never reads as a session launched in 1970 and an absent identifier never reads as an empty one.
+
+A row whose branch cannot be read is kept and marked rather than dropped. A caller has to be able to tell a session holding no branch from one the resolver never saw, and the second is the failure the verb replaces. The `unresolved` field carries the reason:
+
+- `detached-head`: the session holds a worktree with no branch name
+- `not-a-repository`: the session is working outside any git repository
+- `git-unavailable`: git is not on the path, so nothing could be read
+
+## The confidence field
+
+Every report states how liveness was decided, on a pass as well as a failure.
+
+`confirmed` means each row's process was matched against the start time its own record stamped at launch, so the process holding the pid is the session that wrote the file. A caller can address a row of that kind directly.
+
+`unverified` means only that the pid answers a probe. That cannot separate the original session from an unrelated process that inherited its pid after the session ended, so the roster is a candidate list rather than an identity. Treat the mapping as inferred and open the message by naming the branch the reader is believed to hold, asking to be corrected.
+
+The registry holds one record per session and is never pruned, so it accumulates thousands of entries. On the `unverified` path a stale record whose pid has been reused reads as live, which is why the field is reported rather than assumed.
+
+## What the read depends on
+
+The records live under the Claude Code configuration directory, which the verb resolves from `CLAUDE_CONFIG_DIR` and falls back to `~/.claude`. Their location, their filenames, and the fields inside them are a client implementation detail rather than a published interface, so a client change can move them. The verb reports an absent registry as a refusal rather than as a machine running no sessions, which is what surfaces the move instead of burying it in an empty roster.
+
+The start-time comparison reads the process filesystem and exists only on some platforms. Where it does not, the verb still answers and marks the confidence, so a target without it keeps a working roster rather than losing the command.

package/package.json

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

package/scripts/core/regen-hero.sh

@@ -5,7 +5,9 @@
 # bytes move with the browser version, so asserting it in verify.sh would fail
 # on a machine whose chromium differs rather than on a stale count. Rebuild the
 # image with `aitk capture assets/hero.html` after this script reports a change.
-# The frame carries no version. `package.json` is bumped on main by the release
+# That capture also writes assets/hero.stamp, which records the digest of the
+# markup it rendered and is what the Hero stage compares, so all three files
+# commit together. The frame carries no version. `package.json` is bumped on main by the release
 # tooling, so embedding it drifts every open branch on the next release and the
 # stage then fails for work that touched nothing.
 #

package/scripts/core/verify.sh

@@ -111,21 +111,90 @@ collect_plugin_manifests() {
   } | sort -u
 }
 
+# sha256 of a file under the coreutils name and the macOS one. `aitk capture`
+# writes the same digest into the stamp through node's crypto, so the two sides
+# agree on an algorithm rather than on a tool being installed.
+#
+# Neither tool present returns 1 and says so. Falling through to an empty digest
+# reports a mismatch against a blank value, which tells the reader the image is
+# wrong when the truth is that the checker never ran.
+#
+# The refusal goes to stderr because every caller reads this through `$(...)`,
+# which captures stdout into the digest variable and would swallow the message.
+# `run_check` folds stderr into what it pipes, so the reader still sees it.
+file_sha256() {
+  local digest
+  if command -v sha256sum >/dev/null 2>&1; then
+    digest=$(sha256sum "$1")
+  elif command -v shasum >/dev/null 2>&1; then
+    digest=$(shasum -a 256 "$1")
+  else
+    echo "Neither sha256sum nor shasum is installed, so $1 cannot be hashed." >&2
+    return 1
+  fi
+  printf '%s\n' "${digest%% *}"
+}
+
+# One digest the stamp recorded against the file it was taken over. An absent
+# field reports itself rather than comparing against an empty string, so a stamp
+# predating the current format is distinguishable from a file that moved.
+#
+# Both names in the message come off the paths rather than from arguments. The
+# caller passes absolute paths and the reader wants repository-relative ones, and
+# deriving them here is what keeps a name from disagreeing with the file it
+# labels once a second capture source calls this.
+assert_stamp_field() {
+  local stamp=$1 field=$2 file=$3
+  local stamp_label=${stamp#"$PROJECT_ROOT"/}
+  local file_label=${file#"$PROJECT_ROOT"/}
+  local recorded actual
+  recorded=$(awk -v key="$field:" '$1 == key { print $2; exit }' "$stamp")
+  if [ -z "$recorded" ]; then
+    echo "$stamp_label carries no $field line, so it predates the capture that writes one."
+    return 1
+  fi
+  actual=$(file_sha256 "$file") || return 1
+  if [ "$recorded" != "$actual" ]; then
+    echo "$stamp_label records $field $recorded"
+    echo "$file_label hashes to $actual"
+    return 1
+  fi
+}
+
 # The drift assert covers the HTML because the PNG is a chromium render whose
 # bytes move with the browser. That leaves the artifact a visitor actually sees
 # asserted nowhere, so a branch that regenerates the HTML and never runs the
 # capture passes every stage while shipping an image with the old counts.
 #
-# The two files move together or the image is stale, so their last-touching
-# commit is the same commit. Comparing the branch's file list instead would pass
-# any branch that touched both anywhere, including one that regenerated the HTML
-# alone in a later commit. Both absent resolves to two empty strings and passes,
-# which is correct for a tree that carries neither.
-assert_hero_pair() {
-  local html_commit png_commit
-  html_commit=$(git -C "$PROJECT_ROOT" log -1 --format=%H -- assets/hero.html)
-  png_commit=$(git -C "$PROJECT_ROOT" log -1 --format=%H -- assets/hero.png)
-  [ "$html_commit" = "$png_commit" ]
+# `aitk capture` records a digest of the markup it rendered and one of the image
+# it wrote, so this reads provenance rather than timing. Comparing the commit
+# that last touched each file passes any pair that moved together whatever the
+# two files hold, which is what a binary conflict resolved by taking either side
+# produces. All three absent passes, which is correct for a tree that carries
+# none of them.
+#
+# Both digests are checked because either file can move alone. The markup side
+# catches an edit committed with no capture, and the image side catches a PNG
+# replaced under markup that never changed, which is the case the timing read
+# caught by accident and a markup-only digest would drop.
+assert_hero_stamp() {
+  local html="$PROJECT_ROOT/assets/hero.html"
+  local png="$PROJECT_ROOT/assets/hero.png"
+  local stamp="$PROJECT_ROOT/assets/hero.stamp"
+
+  if [ ! -f "$html" ] && [ ! -f "$png" ] && [ ! -f "$stamp" ]; then return 0; fi
+
+  local missing=""
+  [ -f "$html" ] || missing="$missing assets/hero.html"
+  [ -f "$png" ] || missing="$missing assets/hero.png"
+  [ -f "$stamp" ] || missing="$missing assets/hero.stamp"
+  if [ -n "$missing" ]; then
+    echo "Missing from the hero set:$missing"
+    return 1
+  fi
+
+  assert_stamp_field "$stamp" source-sha256 "$html" || return 1
+  assert_stamp_field "$stamp" image-sha256 "$png" || return 1
 }
 
 # Entries the audit actually measured, summed across the folders it resolved.
@@ -188,8 +257,8 @@ main() {
   # machine whose chromium differs rather than on a stale count.
   log_step "Hero"
   run_check "bash $PROJECT_ROOT/scripts/core/regen-hero.sh" "Hero regen failed"
-  assert_no_drift "assets/hero.html" "Hero counts drifted. Run bun run check, then aitk capture assets/hero.html, and commit assets/hero.html with assets/hero.png."
-  run_check "assert_hero_pair" "Hero HTML and image last moved in different commits, so the image may be stale. Run aitk capture assets/hero.html and commit both files together."
+  assert_no_drift "assets/hero.html" "Hero counts drifted. Run bun run check, then aitk capture assets/hero.html, and commit assets/hero.html with assets/hero.png and assets/hero.stamp."
+  run_check "assert_hero_stamp" "The hero set disagrees with the stamp written when the image was captured. Run aitk capture assets/hero.html and commit all three files together."
   log_info "Hero clean"
 
   log_step "Skill references"

package/src/cli.ts

@@ -25,6 +25,7 @@ import { register as comments } from '@/commands/comments'
 import { register as context } from '@/commands/context'
 import { register as markdown } from '@/commands/markdown'
 import { register as records } from '@/commands/records'
+import { register as sessions } from '@/commands/sessions'
 import { PROJECT_ROOT } from '@/project-root'
 
 const GREY = '\x1b[0;90m'
@@ -59,6 +60,7 @@ function showHelp(): void {
     `${GREY}│${NC}    context [cmd]      ${GREY}# Report context folder health (audit)${NC}`,
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
     `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, push, pull)${NC}`,
+    `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
     `${GREY}│${NC}`,
     `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
     `${GREY}│${NC}    aitk sandbox             ${GREY}# Interactive scenario picker${NC}`,
@@ -95,6 +97,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk markdown audit .claude/rules --json`,
     `${GREY}│${NC}    aitk records validate plans`,
     `${GREY}│${NC}    aitk records push --json`,
+    `${GREY}│${NC}    aitk sessions list --json`,
     `${GREY}└${NC}`,
   ]
   console.log(lines.join('\n'))
@@ -151,5 +154,6 @@ comments(program)
 context(program)
 markdown(program)
 records(program)
+sessions(program)
 
 program.parse()

package/src/commands/sessions.ts

@@ -0,0 +1,231 @@
+import type { Command } from 'commander'
+import {
+  repositoryOf,
+  type ResolvedSession,
+  resolveSessions,
+  type SessionReport,
+} from '@/sessions/resolve'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/ui'
+
+interface ListCommandOptions {
+  readonly json?: boolean
+  readonly branch?: string
+}
+
+const REASONS: Record<string, string> = {
+  'not-a-repository': 'working outside any git repository',
+  'detached-head': 'detached HEAD, so the worktree holds no branch name',
+  'git-unavailable': 'git is not on the path, so nothing could be read',
+}
+
+export function register(program: Command): void {
+  const sessions = program
+    .command('sessions')
+    .description(
+      'Resolve live peer sessions to the worktree and branch each holds',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+
+  sessions
+    .command('list')
+    .description(
+      'Report every live session with its working directory and branch',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--branch <name>',
+      'Report only the sessions holding this branch in this repository',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the roster was read',
+        '  1  refused, with the reason on stderr',
+        '',
+        '--branch scopes the match to the repository the command runs in, since',
+        'a branch name identifies a branch there and nothing across a machine.',
+        'A bare run reports every repository and carries the repository field,',
+        'so a caller filtering by hand has something that identifies one.',
+        '',
+        'The match can return more than one session. Read the count rather than',
+        'the first row, since two sessions can hold one branch.',
+        '',
+        'Each session writes its own working directory beside its own name, so a',
+        'name from a session listing joins to a branch by an exact match rather',
+        'than by ordering the roster on start time.',
+        '',
+        'The confidence field says how the liveness of a row was decided.',
+        '"confirmed" matched the running process against the start time the',
+        'record stamped. "unverified" means only that the pid answers, which',
+        'cannot rule out a pid handed to an unrelated process, so a roster',
+        'reported that way is a candidate list rather than an identity.',
+        '',
+        'Examples:',
+        '  aitk sessions list',
+        '  aitk sessions list --json',
+        '  aitk sessions list --branch feat/parser --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ListCommandOptions) => {
+      process.exitCode = await runList(opts)
+    })
+}
+
+async function runList(opts: ListCommandOptions): Promise<number> {
+  const report = await resolveSessions()
+
+  if (report.kind === 'absent') {
+    intro('aitk sessions list')
+    logStep('Refused')
+    logWarn(
+      `No session registry at ${report.dir}. Nothing was read, so this is not a machine with no sessions.`,
+    )
+    outro()
+
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({ dir: report.dir, reason: 'no-registry', sessions: [] })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  // A branch name identifies a branch inside one repository and nothing across
+  // a machine, so an unscoped match reaches a session working in a different
+  // project. `main` is the name that collides on every machine running two.
+  const repository = opts.branch ? await repositoryOf(process.cwd()) : null
+
+  if (opts.branch && repository === null) {
+    intro('aitk sessions list')
+    logStep('Refused')
+    logWarn(
+      '--branch scopes the match to the repository this command runs in, and no repository resolved here. Run it inside one, or read the whole roster and filter on the repository field.',
+    )
+    outro()
+
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({ dir: report.dir, reason: 'no-repository', sessions: [] })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  const shown = opts.branch
+    ? report.sessions.filter(
+        (session) =>
+          session.branch === opts.branch && session.repository === repository,
+      )
+    : report.sessions
+
+  intro('aitk sessions list')
+  reportConfidence(report)
+  reportSessions(shown, opts.branch, repository)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        dir: report.dir,
+        confidence: report.confidence,
+        branch: opts.branch ?? null,
+        repository,
+        sessions: shown,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+/**
+ * States how liveness was decided on every run, including the run that decided
+ * it the strong way.
+ *
+ * A caller reading a roster has no other way to tell a confirmed identity from
+ * a pid that merely answered, and the two support different actions: the first
+ * addresses a session directly and the second opens by asking to be corrected.
+ */
+function reportConfidence(
+  report: Extract<SessionReport, { kind: 'resolved' }>,
+): void {
+  logStep('Liveness')
+
+  // A roster of none decided nothing, so the confirmed line would claim a check
+  // over rows that do not exist. The registry is never pruned and holds a record
+  // per session ever run, which is what makes the empty result worth stating.
+  if (report.sessions.length === 0) {
+    logInfo(
+      'No row to decide. Every record belongs to a session that has ended.',
+    )
+    return
+  }
+
+  if (report.confidence === 'confirmed') {
+    logInfo(
+      'Every row matched a running process against the start time its record stamped.',
+    )
+    return
+  }
+
+  logWarn(
+    'Start times could not be read, so rows rest on a pid answering alone. Treat the mapping as inferred and open by asking to be corrected.',
+  )
+}
+
+function reportSessions(
+  sessions: readonly ResolvedSession[],
+  branch: string | undefined,
+  repository: string | null,
+): void {
+  logStep('Sessions')
+
+  if (branch) {
+    logInfo(
+      `Scoped to ${repository}, since a branch name identifies one there.`,
+    )
+  }
+
+  if (sessions.length === 0) {
+    logInfo(
+      branch
+        ? `No live session in this repository holds ${branch}.`
+        : 'No live session. Every record in the registry belongs to a session that has ended.',
+    )
+    return
+  }
+
+  // The count is what a dispatch turns on. One row is a target and several are
+  // candidates, and the caller cannot tell them apart from a roster alone.
+  if (branch && sessions.length > 1) {
+    logWarn(
+      `${sessions.length} sessions hold ${branch}. Confirm which one before addressing it.`,
+    )
+  }
+
+  logInfo(plural(sessions.length, 'live session'))
+  pipeOutput(
+    sessions
+      .map((session) => {
+        const held =
+          session.branch ??
+          `unresolved: ${REASONS[session.unresolved ?? ''] ?? 'unknown'}`
+        return `${session.name}  ${session.status}  ${held}\n  ${session.cwd}`
+      })
+      .join('\n'),
+  )
+}

package/src/sessions/live.ts

@@ -0,0 +1,79 @@
+import { readFileSync } from 'node:fs'
+import type { SessionRecord } from '@/sessions/registry'
+
+/**
+ * How far the liveness answer can be trusted.
+ *
+ * `confirmed` means the running process was matched against the start time the
+ * record stamped, so the pid belongs to the session that wrote the file.
+ * `unverified` means the pid answers a signal probe and nothing more, which
+ * cannot separate the original session from whatever inherited its pid.
+ */
+export type Confidence = 'confirmed' | 'unverified'
+
+export interface Liveness {
+  readonly alive: boolean
+  readonly confidence: Confidence
+}
+
+export interface LivenessProbes {
+  /** The start time of a running process, or null where it cannot be read. */
+  readonly procStartOf: (pid: number) => string | null
+  /** Whether the pid answers at all, ignoring which process holds it. */
+  readonly responds: (pid: number) => boolean
+}
+
+/**
+ * Reads a running process's start time from the process filesystem.
+ *
+ * The comm field is parenthesised and may itself contain spaces, so the split
+ * runs from the last `)` rather than over the whole line. Fields resume at the
+ * third, which puts the twenty-second at offset nineteen.
+ */
+function procStartOf(pid: number): string | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+    const tail = stat.slice(stat.lastIndexOf(')') + 1).trim()
+    return tail.split(/\s+/)[19] ?? null
+  } catch {
+    return null
+  }
+}
+
+/** Signal zero performs the permission and existence checks and delivers nothing. */
+function responds(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    // A live process owned by another user answers EPERM, which is an answer.
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+export const SYSTEM_PROBES: LivenessProbes = { procStartOf, responds }
+
+/**
+ * Decides whether a record describes a session that is still running.
+ *
+ * The two paths are not interchangeable and the caller is told which one ran.
+ * Where the process filesystem answers, a start-time mismatch is a dead session
+ * whose pid was reused and the record is discarded. Where it does not, the
+ * probe alone stands, and every surviving row is marked so a caller never reads
+ * a recycled pid as a confirmed identity.
+ */
+export function liveness(
+  record: SessionRecord,
+  probes: LivenessProbes = SYSTEM_PROBES,
+): Liveness {
+  const started = record.procStart
+
+  if (started !== undefined && started.length > 0) {
+    const running = probes.procStartOf(record.pid)
+    if (running !== null) {
+      return { alive: running === started, confidence: 'confirmed' }
+    }
+  }
+
+  return { alive: probes.responds(record.pid), confidence: 'unverified' }
+}

package/src/sessions/registry.ts

@@ -0,0 +1,120 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/**
+ * One session's own record of itself, as the client writes it.
+ *
+ * Only the fields this domain reads are declared. The client writes several
+ * more, and naming them here would put a second copy of its schema in a
+ * repository that does not own it.
+ */
+export interface SessionRecord {
+  readonly pid: number
+  readonly cwd: string
+  readonly name: string
+  /**
+   * Optional because the guard admitting a record checks the three fields above
+   * and no more. A client predating any of these writes a record the roster
+   * still wants, so the type says what the guard actually proved.
+   */
+  readonly sessionId: string | undefined
+  readonly kind: string | undefined
+  readonly status: string | undefined
+  readonly startedAt: number | undefined
+  /**
+   * The process start time the client stamped at launch, compared against the
+   * running process to separate a live session from a record whose pid has
+   * been handed to something else.
+   */
+  readonly procStart: string | undefined
+}
+
+/**
+ * Resolves the folder holding one file per session.
+ *
+ * `CLAUDE_CONFIG_DIR` comes first because a client honouring it writes its
+ * records nowhere near the home directory, and a read that ignored it would
+ * report an empty roster on a machine running sessions.
+ */
+export function registryDir(): string {
+  const configured = process.env.CLAUDE_CONFIG_DIR
+  const base =
+    configured && configured.length > 0
+      ? configured
+      : join(homedir(), '.claude')
+  return join(base, 'sessions')
+}
+
+/**
+ * Fields whose absence leaves a row unable to answer the question asked of it.
+ *
+ * The pid has to be positive rather than merely numeric. Signal zero addresses
+ * the caller's own process group rather than a process, so a record carrying
+ * zero would answer the liveness probe and enter the roster as a live session.
+ */
+function isUsable(value: Partial<SessionRecord>): value is SessionRecord {
+  return (
+    typeof value.pid === 'number' &&
+    Number.isInteger(value.pid) &&
+    value.pid > 0 &&
+    typeof value.cwd === 'string' &&
+    value.cwd.length > 0 &&
+    typeof value.name === 'string' &&
+    value.name.length > 0
+  )
+}
+
+/**
+ * An absent folder and an empty one are separate answers.
+ *
+ * The first means no client ever wrote a record here, so the read never ran and
+ * a roster of none would report a machine with no sessions when the truth is a
+ * lookup that failed. The second is a machine whose sessions have all ended.
+ */
+export type Registry =
+  | { readonly kind: 'absent'; readonly dir: string }
+  | {
+      readonly kind: 'read'
+      readonly dir: string
+      readonly records: SessionRecord[]
+    }
+
+/**
+ * Reads every session record in the folder, newest first.
+ *
+ * A file that does not parse, or that parses without the fields a row is built
+ * from, is dropped rather than reported. The folder accumulates a record per
+ * session and is never pruned, so it holds thousands of entries from clients
+ * spanning many versions, and a finding per stale shape would bury the live
+ * sessions this exists to name.
+ */
+export function readRegistry(dir: string = registryDir()): Registry {
+  let names: string[]
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return { kind: 'absent', dir }
+  }
+
+  const records: SessionRecord[] = []
+
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue
+
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(join(dir, name), 'utf8'))
+      if (typeof parsed !== 'object' || parsed === null) continue
+      const record = parsed as Partial<SessionRecord>
+      if (isUsable(record)) records.push(record)
+    } catch {
+      // Unreadable or malformed. See the note above.
+    }
+  }
+
+  return {
+    kind: 'read',
+    dir,
+    records: records.sort((a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0)),
+  }
+}

package/src/sessions/resolve.ts

@@ -0,0 +1,180 @@
+import { $ } from 'bun'
+import {
+  type Confidence,
+  liveness,
+  type LivenessProbes,
+  SYSTEM_PROBES,
+} from '@/sessions/live'
+import { readRegistry, type SessionRecord } from '@/sessions/registry'
+
+/** Why a row carries no branch, stated rather than left as an absent key. */
+export type Unresolved =
+  | 'not-a-repository'
+  | 'detached-head'
+  | 'git-unavailable'
+
+export interface ResolvedSession {
+  readonly name: string
+  readonly pid: number
+  readonly sessionId: string | null
+  readonly cwd: string
+  readonly kind: string
+  readonly status: string
+  readonly startedAt: string | null
+  /**
+   * The shared git directory every worktree of one repository resolves to,
+   * which is what identifies the repository a row belongs to. A branch name is
+   * unique inside one and says nothing across a machine.
+   */
+  readonly repository: string | null
+  readonly worktree: string | null
+  readonly branch: string | null
+  /** Null exactly when `branch` is set. The two are written together. */
+  readonly unresolved: Unresolved | null
+}
+
+export type SessionReport =
+  | { readonly kind: 'absent'; readonly dir: string }
+  | {
+      readonly kind: 'resolved'
+      readonly dir: string
+      /**
+       * The weakest confidence any surviving row was decided at, so one read
+       * tells a caller whether the roster can be trusted as an identity.
+       */
+      readonly confidence: Confidence
+      readonly sessions: readonly ResolvedSession[]
+    }
+
+export interface ResolveOptions {
+  readonly dir?: string
+  readonly probes?: LivenessProbes
+  readonly locate?: (cwd: string) => Promise<Located>
+}
+
+export interface Located {
+  readonly repository: string | null
+  readonly worktree: string | null
+  readonly branch: string | null
+  readonly unresolved: Unresolved | null
+}
+
+/**
+ * Asks git what a directory is checked out to.
+ *
+ * A detached HEAD and a directory outside any repository are separated here
+ * rather than collapsed into one empty answer, because the first is a session
+ * 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()
+
+  if (top.exitCode !== 0) {
+    // git absent and git refusing the directory are both non-zero here. The
+    // first is the platform report the plan asked for and the second is an
+    // ordinary answer, so the distinguishing read is whether git ran at all.
+    const version = await $`git --version`.quiet().nothrow()
+    return {
+      repository: null,
+      worktree: null,
+      branch: null,
+      unresolved:
+        version.exitCode === 0 ? 'not-a-repository' : 'git-unavailable',
+    }
+  }
+
+  const worktree = top.stdout.toString().trim()
+  const repository = await repositoryOf(cwd)
+  const head = await $`git -C ${cwd} branch --show-current`.quiet().nothrow()
+  const branch = head.stdout.toString().trim()
+
+  if (head.exitCode !== 0 || branch.length === 0) {
+    return { repository, worktree, branch: null, unresolved: 'detached-head' }
+  }
+
+  return { repository, worktree, branch, unresolved: null }
+}
+
+/**
+ * Resolves the shared git directory a working directory belongs to.
+ *
+ * The common directory is what a linked worktree and its main checkout agree
+ * on, so two rows in one repository match here while the toplevel would place
+ * every worktree in a repository of its own.
+ */
+export async function repositoryOf(cwd: string): Promise<string | null> {
+  const dir =
+    await $`git -C ${cwd} rev-parse --path-format=absolute --git-common-dir`
+      .quiet()
+      .nothrow()
+
+  if (dir.exitCode !== 0) return null
+
+  const resolved = dir.stdout.toString().trim()
+  return resolved.length > 0 ? resolved : null
+}
+
+/**
+ * An absent field is rendered as an absence rather than as a value.
+ *
+ * A missing start time formatted from zero reads as a session launched in 1970
+ * and a missing identifier as an empty one, both of which a caller would take
+ * for data. Null says the record did not carry it, which is the same
+ * distinction the registry draws between an absent folder and an empty one.
+ */
+function present(record: SessionRecord, located: Located): ResolvedSession {
+  return {
+    name: record.name,
+    pid: record.pid,
+    sessionId: record.sessionId ?? null,
+    cwd: record.cwd,
+    kind: record.kind ?? 'unknown',
+    status: record.status ?? 'unknown',
+    startedAt:
+      record.startedAt === undefined
+        ? null
+        : new Date(record.startedAt).toISOString(),
+    repository: located.repository,
+    worktree: located.worktree,
+    branch: located.branch,
+    unresolved: located.unresolved,
+  }
+}
+
+/**
+ * Resolves every live session to the worktree and branch it holds.
+ *
+ * The registry is the whole source. Each session writes its own working
+ * directory beside its own name, so a caller matching a listing row to a branch
+ * reads both from one record instead of ordering the roster by start time and
+ * hoping the order holds.
+ *
+ * A row whose branch cannot be read is kept and marked. Dropping it would leave
+ * a caller unable to tell a session that holds no branch from one the resolver
+ * never saw, and the second is the failure this replaces.
+ */
+export async function resolveSessions(
+  opts: ResolveOptions = {},
+): Promise<SessionReport> {
+  const probes = opts.probes ?? SYSTEM_PROBES
+  const find = opts.locate ?? locate
+  const registry = readRegistry(opts.dir)
+
+  if (registry.kind === 'absent') return { kind: 'absent', dir: registry.dir }
+
+  const live: SessionRecord[] = []
+  let confidence: Confidence = 'confirmed'
+
+  for (const record of registry.records) {
+    const state = liveness(record, probes)
+    if (!state.alive) continue
+    if (state.confidence === 'unverified') confidence = 'unverified'
+    live.push(record)
+  }
+
+  const sessions = await Promise.all(
+    live.map(async (record) => present(record, await find(record.cwd))),
+  )
+
+  return { kind: 'resolved', dir: registry.dir, confidence, sessions }
+}