@erclx/aitk 0.91.2 → 0.93.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.2",
+  "version": "0.93.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -6,9 +6,10 @@ description: Memory capture at the close of a session, what to write to .claude/
 Capture what the session learned, then write the pre-compact handoff as orchestrator. Do both before a compaction, because a compaction keeps conclusions and drops the reasoning that produced them, and no other file in the repository carries that reasoning.
 
 1. Invoke `aitk:claude-memory-capture` and tell it this session does not commit. Capture reads the session and this handoff summarizes it, so capturing first lets the handoff cite what was written instead of restating the same lesson in prose.
-2. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Write `.claude/tasks/session.md` under it.
-3. Write only what a compaction destroys and no other file already carries. The board holds the ordering and what each task waits on, a task file holds its own findings, and a groundwork folder holds its track.
-4. Use this shape, resolving `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md` and `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` to absolute paths as you write it and pasting each in place of `<RESUME_RUNBOOK>` and `<POLL_RUNBOOK>`:
+2. Run `aitk claude skills drift <commit this session started from>` and re-read any body it names before writing anything below. Nothing on the machine records that commit, so recover it from how long the session has been running with `git log -1 --format=%H --before='<duration> ago'`, rounding the duration up rather than down. A ref older than the oldest load over-reports and confirming a name costs one read of the body, so the generous end is the safe one and a guess at the exact commit is not worth making. A skill body enters a session once and re-invoking the skill replays the held copy rather than the file, so the drift is worst at exactly this moment and a name here is a body this session has been following out of date. Record what it named under `## Standing cautions`. The verb answers where the working directory carries `claude/skills/` with history behind it, which is the toolkit repository itself, and refuses by naming the absent tree anywhere else. A project consuming the plugin from a marketplace cache is that second case, so read the refusal as the boundary rather than as a fault.
+3. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Write `.claude/tasks/session.md` under it.
+4. Write only what a compaction destroys and no other file already carries. The board holds the ordering and what each task waits on, a task file holds its own findings, and a groundwork folder holds its track.
+5. Use this shape, resolving `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md` and `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` to absolute paths as you write it and pasting each in place of `<RESUME_RUNBOOK>` and `<POLL_RUNBOOK>`:
 
 ```markdown
 ---
@@ -41,10 +42,10 @@ Resume by loading the orchestrator skill and asking it to resume after a compact
 That resume reads the board and stops. It restarts nothing, so the review poll is a second thing owed here, and <POLL_RUNBOOK> holds the prompt and the condition. Do not reach for `session-resume`, which reads tracked work and knows nothing about this board or the workers on it.
 ```
 
-5. Cite a commit, a task, or a file and line for every claim, so the next session can tell a read from a recall.
-6. Overwrite the previous handoff rather than appending to it. A stale entry read as current is worse than no handoff.
+6. Cite a commit, a task, or a file and line for every claim, so the next session can tell a read from a recall.
+7. Overwrite the previous handoff rather than appending to it. A stale entry read as current is worse than no handoff.
 
-The substitution belongs in step 4 because step 6 ends the write. A reader who treats the list as finished there ships the literal placeholders, and the variable expands while this runbook renders rather than in the turn that reads the handoff back, so a path left unresolved reaches a session holding no skill as a string matching nothing. `orchestrator-poll.md` resolves its script at the same point and for the same reason.
+The substitution belongs in step 5 because step 7 ends the write. A reader who treats the list as finished there ships the literal placeholders, and the variable expands while this runbook renders rather than in the turn that reads the handoff back, so a path left unresolved reaches a session holding no skill as a string matching nothing. `orchestrator-poll.md` resolves its script at the same point and for the same reason.
 
 Add a section only for content that fits none of the four and would otherwise be lost. Do not restate the board, and do not summarize the work that shipped, because git already carries it. The closing block is the one exception, and the paragraph below states why.
 

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/commands.md

@@ -35,31 +35,33 @@ 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                                    |
 | `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                            |
+| `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD` (`--json`)                                                         |
 | `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                     |
 
 ## Domain commands
 
 Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.
 
-| Domain      | Subcommands                                                                 |
-| ----------- | --------------------------------------------------------------------------- |
-| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`      |
-| `snippets`  | `list`, `install`, `sync`, `create`                                         |
-| `standards` | `list`, `install`, `sync`, `<name>`                                         |
-| `gov`       | `list`, `install`, `sync`, `build`                                          |
-| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `setup [dest]` |
-| `wiki`      | `init`                                                                      |
-| `design`    | `render`                                                                    |
-| `slides`    | `render`, `list`                                                            |
-| `tasks`     | `archive`, `validate`                                                       |
-| `intake`    | `list`, `answer`                                                            |
-| `comments`  | `scan`                                                                      |
-| `context`   | `audit`                                                                     |
-| `markdown`  | `audit`                                                                     |
+| Domain      | Subcommands                                                                                 |
+| ----------- | ------------------------------------------------------------------------------------------- |
+| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                      |
+| `snippets`  | `list`, `install`, `sync`, `create`                                                         |
+| `standards` | `list`, `install`, `sync`, `<name>`                                                         |
+| `gov`       | `list`, `install`, `sync`, `build`                                                          |
+| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `setup [dest]` |
+| `wiki`      | `init`                                                                                      |
+| `design`    | `render`                                                                                    |
+| `slides`    | `render`, `list`                                                                            |
+| `tasks`     | `archive`, `validate`                                                                       |
+| `intake`    | `list`, `answer`                                                                            |
+| `comments`  | `scan`                                                                                      |
+| `context`   | `audit`                                                                                     |
+| `markdown`  | `audit`                                                                                     |
 
 Common patterns:
 

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
-- [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
+- [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, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [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/docs/agents/skills-audit.md

@@ -1,6 +1,6 @@
 ---
 title: Skill audit
-description: Measuring both skill corpora against standards/skill.md, the checks it reads, and the requirement gate that is the only failing one
+description: Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 ---
 
 # Skill audit
@@ -53,3 +53,36 @@ Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folde
 `--requirements-only` is the half wired into `bun run check`. Presence of a required file is a fact with no false positives, and the rule had nothing reading it, so a skill shipped without the sibling passed every stage while the standard required it.
 
 The check is preventive rather than diagnostic. Every mechanical rule passed across both corpora the day it shipped, so what it buys is the regression it stops rather than a backlog it surfaces.
+
+## Drift since a ref
+
+`aitk claude skills drift <ref>` names the shipped skill bodies rewritten between that commit and the current `HEAD`.
+
+```bash
+aitk claude skills drift HEAD~20
+aitk claude skills drift 02d7b265 --json
+```
+
+| Option   | Behavior                                                   |
+| -------- | ---------------------------------------------------------- |
+| `--json` | Add a machine-readable record on stdout, keeping the frame |
+
+A skill body enters a session once and stays. Re-invoking the skill replays the copy the session already holds rather than re-reading the file, so a session that outlives a merge touching a body it loaded keeps applying what it loaded and nothing compares the two. A compaction carries the held copy forward with the summary it writes, which makes the exposure the age of the oldest load rather than the age of the session.
+
+The ref is required and carries no default. `HEAD` is the only value the command could supply for itself, and it answers every run with nothing moved, which is the silence this verb exists to break. A session passes the commit it started from.
+
+Nothing on the machine records that commit, so a session recovers it from its own elapsed run time with `git log -1 --format=%H --before='<duration> ago'` and rounds the duration up. Over-reporting costs one read of a body while under-reporting costs the answer, so the generous end of the estimate is the correct one and no session needs to pin the exact commit.
+
+### What drift reads
+
+Bodies alone, one `SKILL.md` per folder, across `claude/skills/` and not the internal tree. A reference or a requirement beside the body is read by whoever opens it and holds no copy that outlives the read, and the internal corpus never loads into a target session at all.
+
+The report names the newest commit that rewrote each body rather than the first, so a body rewritten twice in the range points at the version on disk now.
+
+### What drift cannot answer
+
+The report says a file moved, not that a session holds a stale copy. A session cannot read its own loaded body as bytes, so the comparison runs against history and a ref older than the oldest load over-reports. That is the safe direction, since confirming a name costs one read of the body while the failure being answered is silence. Every run states the bound, including the run that names nothing.
+
+Two cases fall outside the range. An uncommitted edit in the working tree is not history yet, so a body changed and left unstaged reports as unmoved. A target project loads the plugin from a marketplace cache with no repository behind it, where the verb refuses and names the absent history rather than reporting a clean tree.
+
+Exit codes are `0` when history was read, whether or not a body moved, and `1` when the question could not be answered. An absent shipped corpus, an absent repository, and a ref matching no commit each refuse with their own reason on stderr. A command exiting zero on a question it never answered is the failure `.claude/ARCHITECTURE.md` already records against two skills, which is why no path here reports an empty result in place of a refusal.

package/package.json

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

package/src/claude/skills-drift.ts

@@ -0,0 +1,156 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { execaSync } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/**
+ * The shipped corpus alone. A session loads a body from the plugin root, which
+ * resolves to `claude/skills/`, so the internal tree carries no held copy that
+ * could go stale in one.
+ *
+ * Held with posix separators because it is passed to git as a pathspec. Git
+ * emits and accepts posix separators on every platform, so a `join()` form would
+ * reach a Windows checkout as `claude\skills`, match no path, and return an
+ * empty log that reads as a tree where nothing moved.
+ */
+const SHIPPED_SKILLS = 'claude/skills'
+
+/** A `%H` line, which is 40 hex characters under sha1 and 64 under sha256. */
+const COMMIT = /^[0-9a-f]{40,64}$/
+
+/**
+ * A skill body, which is the only file in the folder a session loads. A
+ * reference or a requirement beside it is read by whoever opens it, so it holds
+ * no copy that outlives the read.
+ */
+const BODY = /^claude\/skills\/([^/]+)\/SKILL\.md$/
+
+export interface MovedBody {
+  readonly name: string
+  /** The newest commit that rewrote this body, not the first. */
+  readonly commit: string
+}
+
+export type DriftReport =
+  | {
+      readonly kind: 'measured'
+      readonly base: string
+      readonly head: string
+      readonly moved: readonly MovedBody[]
+    }
+  | { readonly kind: 'unreadable'; readonly reason: string }
+
+/**
+ * Reads `--name-only` log output into one entry per skill whose body moved.
+ *
+ * Reverse-chronological input means the first commit naming a body is the
+ * newest that rewrote it, so an existing name is never overwritten. A body
+ * rewritten twice therefore reports the recent commit, which is the one a
+ * session can read to see what it is missing.
+ */
+export function parseMovedBodies(output: string): MovedBody[] {
+  const moved = new Map<string, string>()
+  let commit = ''
+
+  for (const line of output.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+
+    if (COMMIT.test(trimmed)) {
+      commit = trimmed
+      continue
+    }
+
+    const match = BODY.exec(trimmed)
+    if (match === null || commit === '') continue
+    if (!moved.has(match[1])) moved.set(match[1], commit)
+  }
+
+  return [...moved]
+    .map(([name, sha]) => ({ name, commit: sha }))
+    .sort((left, right) => left.name.localeCompare(right.name))
+}
+
+/**
+ * Which shipped skill bodies were rewritten between `ref` and the current
+ * `HEAD` of the tree at `root`.
+ *
+ * This measures a file moving rather than a held copy differing. A session
+ * cannot read its own loaded body as bytes, so the comparison runs against
+ * history and a session passing a ref older than its oldest load over-reports.
+ * That is the safe direction, since confirming a name costs one read of the
+ * body while the failure this answers is silence.
+ *
+ * Every path that cannot answer returns `unreadable` with its own reason. A
+ * target project loads the plugin from a marketplace cache with no history
+ * behind it, where reporting an empty result would read as a clean tree.
+ */
+export function readDrift(root: string, ref: string): DriftReport {
+  if (!existsSync(join(root, SHIPPED_SKILLS))) {
+    return {
+      kind: 'unreadable',
+      reason: `No shipped skill corpus under ${root}. Looked for ${SHIPPED_SKILLS}.`,
+    }
+  }
+
+  const head = revParse(root, 'HEAD')
+  if (head === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `No git history under ${root}. A plugin loaded from a marketplace cache carries none, so a ref cannot be resolved there.`,
+    }
+  }
+
+  const base = revParse(root, ref)
+  if (base === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `Ref ${ref} resolves to no commit in ${root}. Pass a commit this tree carries.`,
+    }
+  }
+
+  const result = execaSync(
+    'git',
+    [
+      '-C',
+      root,
+      'log',
+      '--name-only',
+      '--no-renames',
+      '--format=%H',
+      `${base}..${head}`,
+      '--',
+      SHIPPED_SKILLS,
+    ],
+    { reject: false, env: gitEnv(), extendEnv: false },
+  )
+
+  if (result.exitCode !== 0) {
+    return {
+      kind: 'unreadable',
+      reason: `Reading history between ${ref} and HEAD failed: ${result.stderr || result.stdout}`,
+    }
+  }
+
+  return {
+    kind: 'measured',
+    base,
+    head,
+    moved: parseMovedBodies(result.stdout),
+  }
+}
+
+/**
+ * The commit a ref names, or `undefined` when the tree carries no repository or
+ * no such ref. `^{commit}` is what turns a tag or a tree into the commit behind
+ * it, so a caller never compares a ref against an object of another type.
+ */
+function revParse(root: string, ref: string): string | undefined {
+  const result = execaSync(
+    'git',
+    ['-C', root, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`],
+    { reject: false, env: gitEnv(), extendEnv: false },
+  )
+
+  return result.exitCode === 0 ? result.stdout.trim() : undefined
+}

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/claude.ts

@@ -21,6 +21,7 @@ import {
   type SkillFinding,
   type SkillsAudit,
 } from '@/claude/skills-audit'
+import { type DriftReport, readDrift } from '@/claude/skills-drift'
 import { listSkills } from '@/claude/skills-list'
 import {
   planSettings,
@@ -67,6 +68,10 @@ interface SkillsAuditOptions {
   readonly requirementsOnly?: boolean
 }
 
+interface SkillsDriftOptions {
+  readonly json?: boolean
+}
+
 const SEEDED_FILES: readonly string[] = [
   'ARCHITECTURE.md',
   'REQUIREMENTS.md',
@@ -157,15 +162,15 @@ export function register(program: Command): void {
 
   const skills = claude
     .command('skills')
-    .description('Plugin skill catalog (list, audit)')
-    .argument('[subcommand]', "One of 'list' or 'audit'")
+    .description('Plugin skill catalog (list, audit, drift)')
+    .argument('[subcommand]', "One of 'list', 'audit', or 'drift'")
     .helpOption('-h, --help', 'Show this help message')
     .action((subcommand: string | undefined) => {
       intro('aitk claude')
       logError(
         subcommand === undefined
-          ? "Missing subcommand. Use 'list' or 'audit'."
-          : `Unknown subcommand: ${subcommand}. Use 'list' or 'audit'.`,
+          ? "Missing subcommand. Use 'list', 'audit', or 'drift'."
+          : `Unknown subcommand: ${subcommand}. Use 'list', 'audit', or 'drift'.`,
       )
       outro()
       process.exitCode = 1
@@ -225,6 +230,34 @@ export function register(program: Command): void {
     .action(async (path: string | undefined, opts: SkillsAuditOptions) => {
       process.exitCode = await runSkillsAudit(path, opts)
     })
+
+  skills
+    .command('drift')
+    .description('Name the shipped skill bodies rewritten since a given ref')
+    .argument('<ref>', 'The commit a session started from')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  history was read, whether or not a body moved',
+        '  1  the question could not be answered, with the reason on stderr',
+        '',
+        'A moved body means the file changed, not that a session holds a stale',
+        'copy. Passing a ref older than the oldest load over-reports, which is',
+        'the safe direction. Confirm a name by reading the body.',
+        '',
+        'Examples:',
+        '  aitk claude skills drift HEAD~20',
+        '  aitk claude skills drift 02d7b265 --json',
+        '',
+      ].join('\n'),
+    )
+    .action((ref: string, opts: SkillsDriftOptions) => {
+      process.exitCode = runSkillsDrift(ref, opts)
+    })
 }
 
 function succeed(message: string): number {
@@ -467,6 +500,75 @@ function runSkillsList(opts: SkillsListOptions): number {
   return 0
 }
 
+/**
+ * Measures the cwd for the same reason the audit does, and takes the ref as a
+ * required argument with no default. `HEAD` would be the only defensible one and
+ * it answers every run with nothing moved, which is the silence this reports
+ * against.
+ */
+function runSkillsDrift(ref: string, opts: SkillsDriftOptions): number {
+  const root = process.cwd()
+  const report = readDrift(root, ref)
+
+  if (report.kind === 'measured') {
+    intro('aitk claude skills drift')
+    reportDrift(report, ref)
+    outro()
+  } else {
+    frameError(report.reason)
+  }
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        report.kind === 'measured'
+          ? {
+              root,
+              ref,
+              base: report.base,
+              head: report.head,
+              moved: report.moved,
+            }
+          : { root, ref, unreadable: report.reason },
+      )}\n`,
+    )
+  }
+
+  return report.kind === 'measured' ? 0 : 1
+}
+
+/**
+ * States the bound on every run, including the run that names nothing. A report
+ * listing only what moved reads as a verdict on what a session holds, and the
+ * command has no access to that.
+ */
+function reportDrift(
+  report: Extract<DriftReport, { kind: 'measured' }>,
+  ref: string,
+): void {
+  logStep('Range')
+  logInfo(`${ref} to HEAD, resolved as ${report.base}..${report.head}.`)
+  logInfo(
+    'A body here changed on disk. Whether a session still holds the old one is what reading it settles.',
+  )
+
+  logStep('Moved bodies')
+  if (report.moved.length === 0) {
+    logInfo('No shipped body changed in this range.')
+    return
+  }
+
+  const count = report.moved.length
+  logWarn(
+    `${count} skill ${count === 1 ? 'body' : 'bodies'} rewritten since ${ref}`,
+  )
+  pipeOutput(
+    report.moved
+      .map((moved) => `${moved.name}  ${moved.commit.slice(0, 8)}`)
+      .join('\n'),
+  )
+}
+
 /**
  * Measures the tree at the cwd rather than the toolkit root the catalog reads,
  * so a linked worktree audits its own branch instead of reporting on `main`. A

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 }
+}