@erclx/aitk 3.46.0 → 3.47.0

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

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

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

@@ -82,7 +82,9 @@ The session also records nothing of what it learns. Both other callers of memory
 - Check a candidate branch is unclaimed by an existing worktree or a live session before dispatching a background worker for it, since the measured failure this closes is a worker colliding with someone else's work already sitting in the row
 - Dispatch only a candidate whose file set is disjoint from every track in flight, compared at the file path rather than a folder above it, since a count knows nothing about what two workers write
 - Hold a candidate whose sets are disjoint when a stated reason serializes it, and write that reason on the hold, since disjointness is necessary and not sufficient
-- Name each self-dispatched worker with the `orchestrator-` prefix, since that is what separates one from an operator's own launch in a session listing
+- Name each self-dispatched worker with the `worker-` prefix, since that is the role the name marks and no controlling session has ever carried it
+- Pass `-n` explicitly on every self-dispatch, since a launch that omits it leaves the client to derive a name and the fallback is a fragment of the session's own identifier
+- Carry the dispatcher's `sessionId` in the launch prompt, since a worker owed two messages has no property on the roster that resolves a controller and a name goes stale inside the window it builds in
 - Report each self-dispatch and the row it fired against loudly enough to follow, since a person no longer watches the launch step happen
 - Stop dispatching once `## Run now` is empty or every row in it reads claimed, rather than waking again to fire on a board nobody is clearing
 

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

@@ -54,15 +54,31 @@ Name `<model>` on the launch, and pick it against the task rather than copying w
 ## Dispatch
 
 ```bash
-claude --bg --model <model> -n "orchestrator-<slug>" "Run /aitk:claude-worktree <type>/<slug>, then /aitk:claude-autoship <plan>"
+claude --bg --model <model> -n "worker-<slug>" "Run /aitk:claude-worktree <type>/<slug>, then /aitk:claude-autoship <plan>. Your controller is the session whose sessionId is <dispatcher-id>. Resolve its current name from that id at the moment you send, and never resolve an addressee by name prefix. Message it when the pull request opens, carrying the number, the branch, the head sha, the CI state, and every point you departed from the plan on, and message it again if you stop on a question."
 ```
 
-`--bg, --background` starts the session as a background agent and returns immediately, `-n, --name` sets the display name that tells a self-dispatched worker from an operator's own launch in `aitk sessions list`, and `--model` overrides the inheritance the section above measured. Keep the `orchestrator-` prefix. It outlives the count it was introduced for, since the roster read still needs a way to separate the two kinds of launch.
+`--bg, --background` starts the session as a background agent and returns immediately, `-n, --name` sets the display name that tells a self-dispatched worker from an operator's own launch in `aitk sessions list`, and `--model` overrides the inheritance the section above measured. Pass `-n` on every dispatch rather than letting the client derive one. A launch that omits it leaves the session named for a fragment of its own identifier, which is both its address on the send channel and the whole of what the operator sees for it in agent view.
+
+The prefix reads `worker-` because that is the role it marks. It read `orchestrator-` until 2026-08-31, and no controlling session ever carried it, so a worker filtering the roster for that string found a sibling or itself on every row. Nothing matches the prefix programmatically, which is what kept the rename down to three strings.
+
+Read `<dispatcher-id>` with `aitk sessions list --self --json` and interpolate the `sessionId` that row carries. Carry the id rather than the name. A name is derived from whatever the session turned out to be doing, and across the 181 records stamping both fields, nine were renamed after launch at a median of 5.4 minutes and a maximum of 509. Three landed more than ten minutes in, which is inside the window a worker announces its pull request in, so a name written into the prompt is aimed at a send that happens after it goes stale.
+
+Where the installed CLI answers `--self` with an unknown option, that flag is newer than the release the target holds. Read the `sessionId` from the record the client writes for this session under its configuration directory, and say which route answered so the reader knows whether the id was read or inferred.
 
 The worktree call comes first and carries the branch as its argument, which is tier 0 of `claude-worktree` Step 2 and the only tier a caller can reach. `claude-autoship` Step 0 then finds the session already in a linked worktree and continues, which is a path it already documents. The autoship call carries `<plan>`, the same file this runbook already read to derive the branch, so its Step 1 takes it as the caller-supplied plan rather than re-deriving one from the slug the worker's branch happens to carry.
 
 Naming the branch in prose instead was tried and closes nothing, because no tier of that ladder reads the prompt. A worker launched onto `main` cannot match tier 1, a board carrying more than one plan puts tier 2 out of reach, and tier 3 tells it to ask a person who is not there. Four workers took the right branch that way, by inference rather than by contract, which is the same judgment both live disagreements came from.
 
+### What the brief may carry
+
+The prompt carries pointers and standing context, and stops there. The branch and the plan stay arguments, because a skill resolves an argument through a documented ladder and reads no prose at all. What the prose reaches is the worker's judgment, so it holds only what a session has to weigh:
+
+- Name the addressee and what it is owed, which the two message clauses above already do.
+- Carry standing context this session holds that a cold one cannot derive, such as a constraint settled in conversation that never reached the plan.
+- Leave out anything scope-shaped. A file list, a naming convention, or a check to run belongs in the plan, where the review reads it back against the diff.
+
+The last bullet is the one under pressure, since the dispatch that first proved unattended work possible sent a prompt naming the task file, the likely files, the conventions, and the check to run. It shipped in 874 seconds and touched four files its task never named. Scope that arrives as prose is scope nothing verifies afterward.
+
 Report the dispatch as loudly as the human-launch line it replaces: name the branch, the model, the task, and the session name, so a person reading the transcript can follow what fired without watching it happen.
 
 ## Fall back to the human

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

@@ -41,10 +41,47 @@ nothing else.
 - Send a block out as a message before it becomes an interactive prompt. A session already waiting on input never reaches the tool round that drains an inbound message, so a relayed answer arrives under the open question and changes nothing.
 - Send nothing on progress. A worker reporting progress rebuilds, on this side of the channel, the poll the announcement retired on the other.
 
-Address the session the launch named. Fall back to `aitk sessions list --json`
-and the `orchestrator-` prefix when the launch named nobody, which is what an
-operator's own launch looks like, and say the addressee was inferred so the
-reader can correct it.
+Address the session the launch named. It names a `sessionId` rather than a name,
+so read `aitk sessions list --json`, find the row carrying that id, and send to
+the `name` on it. Resolve that name at the moment of sending rather than at
+launch, since a name is derived from what a session turned out to be doing and
+has gone stale inside the hour that a build takes.
+
+Check that name against the agent listing before sending it. A name is not
+unique, and the roster carries no field that separates two live sessions holding
+one, so the resolution can end on a string that reaches the wrong session. Send
+the name bare where the listing shows one row under it. Where it shows more than
+one, complete the address with the `[ref]` that listing prints beside each row
+rather than sending to the name alone, which lands on whichever row the channel
+resolves first. Two sessions differing only by a trailing ` (3)` is the shape
+this meets in practice, and one of them being a controller is what makes the
+wrong pick silent.
+
+Ask the operator when the launch named nobody and a person is there to answer.
+Put the candidate rows to them through the structured question surface, so they
+pick a row rather than recalling a name. The ask halts the build, and the halt
+is the cheaper error: a worker that cannot reach its controller has nothing
+useful to do with the message it owes, where sending to the wrong session
+reports success and loses it. A halt is only as visible as whatever watches for
+one, so say what you are waiting on in the same turn you stop, and expect a
+controller running no stall detector to find the question only when it next
+looks.
+
+Infer only where no operator is present. Read `aitk sessions list --json` and
+take the sessions holding no feature branch as the candidates, since a
+controlling session holds none. Say the addressee was inferred so the reader can
+correct it. Never filter that roster by name prefix: every self-dispatched
+worker is named `worker-<slug>`, so a prefix scan returns a sibling or this
+session itself, which is the defect that sent messages owed to a controller
+somewhere else.
+
+Report a resolution that returns nothing rather than falling back to a guess.
+The roster and the send channel enumerate different populations in both
+directions, measured at one moment: a live background session sat on the roster
+that the agent listing did not carry, and nine sessions were addressable there
+with no roster row at all. Those nine were driving through Remote Control, which
+writes no local process record, so a controller working from a phone is exactly
+the case this read answers nothing for.
 
 ## Refusing is part of the job
 

package/docs/agents/index.md

@@ -30,7 +30,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
 - [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
+- [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, and what each session surface can see
 - [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
 - [Citation reach](skills-reach.md): Reporting the skill bodies that cite a path no target project receives, which corpus the verb reads, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
 - [Standard success criteria](standards-audit.md): Reading the corpus against the Success criterion gate, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets

package/docs/agents/sessions.md

@@ -1,6 +1,6 @@
 ---
 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
+description: Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, and what each session surface can see
 ---
 
 # Sessions
@@ -14,6 +14,7 @@ aitk sessions list
 aitk sessions list --json
 aitk sessions list --branch feat/parser --json
 aitk sessions list --branch chore/agents --repository ../caret --json
+aitk sessions list --self --json
 ```
 
 | Option                | Behavior                                              |
@@ -21,10 +22,11 @@ aitk sessions list --branch chore/agents --repository ../caret --json
 | `--json`              | Add a machine-readable record on stdout               |
 | `--branch <name>`     | Report the sessions holding this branch               |
 | `--repository <path>` | Answer about this project rather than the working one |
+| `--self`              | Report the caller's own row                           |
 
 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`.
+Exit codes: `0` the roster was read, `1` refused. The refusal carries a `reason` of `no-registry`, `no-repository`, `no-self-identity`, or `no-self-row`.
 
 An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `reason` rather than the exit when a skill consumes this.
 
@@ -52,6 +54,29 @@ The ref read covers the local head and the remote-tracking ref, which means it s
 
 Two flags say which reading came up short. `sessionsReadable` is `false` when the session roster could not be read, and `refsReadable` is `false` when the ref read failed. Either one leaves `claimed` covering the readings around it alone, so a `false` there is a report that ran short of evidence rather than a report that the branch is clear. They stay separate fields because a caller told the roster failed goes and looks at the roster, and folding both into one flag would send it to the wrong place.
 
+## Which row is the caller
+
+`--self` narrows the report to the row belonging to the session making the call. A dispatcher reads it to learn the `sessionId` it carries into a launch, because the roster returns every field on every row and marks none of them as the caller.
+
+Three identifier namespaces reach a session and two of them join to a row. Four variables spell them:
+
+- `CLAUDE_CODE_SESSION_ID` holds the roster's own `sessionId`, and is read first because it survives a rename.
+- `CLAUDE_PID` holds the caller's process id, which every row already carries as `pid`.
+- `CLAUDE_CODE_MESSAGING_SOCKET` spells that same pid in its basename. It is read last, since the spelling is a client convention rather than a published interface and a client that moves the socket drops this rung alone.
+- `CLAUDE_CODE_HOST_SESSION_ID` is never read. It carries a `local_`-prefixed value from the harness namespace that matches no row, and it is the variable a reader searching the environment for a session id finds first.
+
+The read refuses rather than returning an empty roster, on the same ground as `no-registry`. A `no-self-identity` refusal means the environment stated none of the three, which is a client identifying its sessions some other way. A `no-self-row` refusal means it stated one and no live row carries it, which is what a session running outside a local process gets.
+
+## What each surface can see
+
+The roster this verb reads and the channel a session sends messages on enumerate different populations, and neither contains the other. Read at one moment, `aitk sessions list` returned 6 rows against the 13 peers plus caller the agent listing reported. The roster held a background session at confirmed confidence on two reads a minute apart that the listing never carried, so a live session sat here with no way to reach it. Nine Remote Control sessions ran the other way, reachable there with no row here at all, since they leave no local process for the registry to record.
+
+That bounds what a carried identifier buys. Resolving a `sessionId` to a name here can produce a name the send channel rejects, and `--self` answers nothing for a controller driving from Remote Control, which is the operator working from their phone rather than an edge case. A caller that cannot resolve an addressee reports the failed resolution instead of falling back to a guess.
+
+The `name` field is what both surfaces agree on, and that agreement is what makes the resolution work. `SendMessage` takes a name and carries no identifier parameter, so the carry runs id to name to send rather than sending an id anywhere.
+
+Agreement is not uniqueness, and the last hop is where that bites. Two live sessions can hold one name, the roster carries no field that separates them, and a send to the bare name reaches whichever the channel resolves first. The agent listing prints a ref beside each row and the roster does not, so a name resolving to more than one live row is completed from that listing rather than from anything this verb returns.
+
 ## Why the verb exists
 
 A session listing reports a name, a kind, a status, and how long each session has been running. None of those names a branch. Resolving a branch to a session therefore meant ordering the roster by start time and matching it against the order the worktrees were created, which is an inference that fails whenever two sessions start inside the same minute.

package/package.json

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

package/src/commands/sessions.ts

@@ -2,10 +2,13 @@ import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { checkClaim, type ClaimReport } from '@/sessions/claim'
 import {
+  callerIdentity,
   repositoryOf,
   type ResolvedSession,
   resolveSessions,
+  type SelfReport,
   type SessionReport,
+  selfOf,
 } from '@/sessions/resolve'
 import {
   intro,
@@ -21,6 +24,7 @@ interface ListCommandOptions {
   readonly json?: boolean
   readonly branch?: string
   readonly repository?: string
+  readonly self?: boolean
 }
 
 const REASONS: Record<string, string> = {
@@ -52,6 +56,10 @@ export function register(program: Command): void {
       '--repository <path>',
       'Answer about this project rather than the working one',
     )
+    .option(
+      '--self',
+      "Report the caller's own row, and refuse where the roster holds none",
+    )
     .addHelpText(
       'after',
       [
@@ -93,6 +101,19 @@ export function register(program: Command): void {
         'The match can return more than one session. Read the count rather than',
         'the first row, since two sessions can hold one branch.',
         '',
+        "--self narrows the report to the caller's own row, which is what a",
+        'dispatcher reads to learn the sessionId it carries into a launch. It',
+        'joins on CLAUDE_CODE_SESSION_ID first, falls back to CLAUDE_PID, and',
+        'falls back again to the pid the messaging socket path spells. It never',
+        'reads CLAUDE_CODE_HOST_SESSION_ID, which holds a value from another',
+        'namespace that matches no row.',
+        '',
+        'It refuses with reason "no-self-identity" when the environment states',
+        'none of the three, and "no-self-row" when it states one and no live',
+        'row carries it. The second is the ordinary answer for a session',
+        'driving from Remote Control, which is addressable on the message',
+        'channel and holds no local process record for the roster to report.',
+        '',
         '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.',
@@ -108,6 +129,7 @@ export function register(program: Command): void {
         '  aitk sessions list --json',
         '  aitk sessions list --branch feat/parser --json',
         '  aitk sessions list --branch chore/agents --repository ../caret --json',
+        '  aitk sessions list --self --json',
         '',
       ].join('\n'),
     )
@@ -136,6 +158,34 @@ async function runList(opts: ListCommandOptions): Promise<number> {
     return 1
   }
 
+  // The roster read returns every row and marks none of them as the caller, so
+  // the join runs here, ahead of any scope. Resolving it after the branch
+  // filter would answer "no row" for a caller whose row was merely filtered
+  // out, which is a different failure wearing the same reason.
+  const own = opts.self ? selfOf(report.sessions, callerIdentity()) : null
+
+  if (own?.kind === 'unresolved') {
+    intro('aitk sessions list')
+    logStep('Refused')
+    logWarn(selfRefusal(own))
+    outro()
+
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({
+          dir: report.dir,
+          reason:
+            own.reason === 'no-identity' ? 'no-self-identity' : 'no-self-row',
+          sessions: [],
+        })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  const pool = own === null ? report.sessions : [own.session]
+
   // 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.
@@ -164,11 +214,11 @@ async function runList(opts: ListCommandOptions): Promise<number> {
   }
 
   const shown = opts.branch
-    ? report.sessions.filter(
+    ? pool.filter(
         (session) =>
           session.branch === opts.branch && session.repository === repository,
       )
-    : report.sessions
+    : pool
 
   const claim = opts.branch
     ? await checkClaim(opts.branch, { cwd: at, resolve: async () => report })
@@ -176,7 +226,7 @@ async function runList(opts: ListCommandOptions): Promise<number> {
 
   intro('aitk sessions list')
   reportConfidence(report)
-  reportSessions(shown, opts.branch, repository)
+  reportSessions(shown, opts.branch, repository, own !== null)
   if (claim) reportClaim(claim)
   outro()
 
@@ -200,6 +250,22 @@ async function runList(opts: ListCommandOptions): Promise<number> {
   return 0
 }
 
+/**
+ * Separates a client that states no identity from a roster holding no row for
+ * one it does state, since the two send a reader to different places.
+ */
+function selfRefusal(own: Extract<SelfReport, { kind: 'unresolved' }>): string {
+  if (own.reason === 'no-identity') {
+    return 'Nothing in the environment identifies this session, so --self has nothing to match against. A client setting none of CLAUDE_CODE_SESSION_ID, CLAUDE_PID, or CLAUDE_CODE_MESSAGING_SOCKET cannot be located on the roster at all.'
+  }
+
+  const held =
+    own.identity.sessionId ??
+    (own.identity.pid === null ? 'nothing' : `pid ${own.identity.pid}`)
+
+  return `The environment identifies this session as ${held}, and no live row carries it. The roster holds local process records alone, so a session driving through Remote Control never appears here, and a record whose session has ended is dropped ahead of the match.`
+}
+
 /**
  * States how liveness was decided on every run, including the run that decided
  * it the strong way.
@@ -239,6 +305,7 @@ function reportSessions(
   sessions: readonly ResolvedSession[],
   branch: string | undefined,
   repository: string | null,
+  scoped: boolean,
 ): void {
   logStep('Sessions')
 
@@ -248,11 +315,21 @@ function reportSessions(
     )
   }
 
+  // An empty result under --self says nothing about the roster, since the pool
+  // was narrowed to one row before the branch filter ran. Reporting the wider
+  // answer there would claim a reading this run never took.
   if (sessions.length === 0) {
+    if (branch) {
+      logInfo(
+        scoped
+          ? `This session does not hold ${branch}.`
+          : `No live session in this repository holds ${branch}.`,
+      )
+      return
+    }
+
     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.',
+      'No live session. Every record in the registry belongs to a session that has ended.',
     )
     return
   }

package/src/process/harness.ts

@@ -0,0 +1,167 @@
+import { spawnSync } from 'node:child_process'
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { PROJECT_ROOT } from '@/project-root'
+import { stateDir } from '@/targets/registry'
+
+const CLI = join(PROJECT_ROOT, 'src/cli.ts')
+
+/** No case has ever needed longer, and a blocked verb should fail fast. */
+const DEFAULT_TIMEOUT_MS = 10_000
+
+export interface ProcessRun {
+  readonly status: number | null
+  readonly stdout: string
+  readonly stderr: string
+  readonly json: unknown
+}
+
+export interface RunCliOptions {
+  readonly cwd: string
+  readonly env?: NodeJS.ProcessEnv
+  readonly timeoutMs?: number
+}
+
+/**
+ * Thrown when a case reaches past its declared temporary directory into this
+ * machine's real toolkit state. `stateDir()` in `src/targets/registry.ts`
+ * holds both the target registry `gov install` and `gov sync` record into and
+ * the sandbox tree `aitk sandbox` provisions into, so a case that inherits the
+ * real `HOME` unmodified writes into whichever of the two a verb touches, and
+ * nothing but this check would ever say so.
+ */
+export class ContainmentViolation extends Error {}
+
+/**
+ * Compares two snapshots of this machine's real toolkit state directory and
+ * reports whether a spawn changed it. A pure comparison over the two reads
+ * rather than the read itself, so the detection logic is testable without
+ * touching the filesystem or spawning anything.
+ */
+export function detectStateLeak(
+  before: string | undefined,
+  after: string | undefined,
+): boolean {
+  return before !== after
+}
+
+/**
+ * A sorted `path:size` listing of every file under this machine's real
+ * `stateDir()`, walked recursively rather than read one level deep, so a
+ * write nested inside an existing folder, such as a file the sandbox tree
+ * already holds, shows up the same as a new top-level entry. Reading a single
+ * known file, such as the target registry alone, would miss every sibling
+ * `stateDir()` grows, which is what left the sandbox tree unwatched.
+ */
+export function snapshotStateDir(): string {
+  const root = stateDir()
+  const rows: string[] = []
+
+  function walk(dir: string): void {
+    let names: string[]
+    try {
+      names = readdirSync(dir)
+    } catch {
+      return
+    }
+
+    for (const name of names.sort()) {
+      const full = join(dir, name)
+      let info: ReturnType<typeof statSync>
+      try {
+        info = statSync(full)
+      } catch {
+        continue
+      }
+      if (info.isDirectory()) walk(full)
+      else rows.push(`${full}:${info.size}`)
+    }
+  }
+
+  walk(root)
+  return rows.join('\n')
+}
+
+/**
+ * Spawns the real entry point rather than calling a command's action function
+ * in-process, so a case answers whether a verb is registered, whether it
+ * exits the way its own contract states, and whether its `--json` record
+ * parses off stdout alone, none of which an in-process call can misreport.
+ *
+ * A git hook exports `GIT_DIR`, which would resolve a fixture's git-aware
+ * reads against this checkout instead of the temporary directory a case
+ * builds, so every spawn drops the `GIT_` prefix before adding the headless
+ * flag every case needs to avoid a picker blocking on stdin.
+ *
+ * `AITK_STATE_DIR` and `AITK_SANDBOX_DIR` get the same treatment as `GIT_DIR`,
+ * each pointed at a folder under the case's own `cwd` rather than dropped,
+ * since dropping either alone would still resolve through the inherited
+ * `HOME` to this machine's real `~/.local/state/aitk`. `stateDir()` and
+ * `sandboxTree()` resolve the same three ways and share that parent, so both
+ * overrides move together. A case explicitly passing its own value through
+ * `options.env` still wins, matching `AITK_NON_INTERACTIVE` below.
+ *
+ * The `stateDir()` snapshot before and after the spawn is what actually
+ * catches an escape past that redirection, since a default can be wrong in a
+ * way a case never asserts on its own, and it is what `AITK_SANDBOX_DIR`
+ * rides for free: the sandbox tree already sits under `stateDir()`, so
+ * walking the whole directory catches a leak there with no override of its
+ * own to add. `ContainmentViolation` fails loud rather than leaving a dead
+ * row for a reviewer to find on a real machine.
+ */
+export function runCli(
+  args: readonly string[],
+  options: RunCliOptions,
+): ProcessRun {
+  const inherited = Object.fromEntries(
+    Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')),
+  )
+
+  const before = snapshotStateDir()
+
+  const result = spawnSync('bun', [CLI, ...args], {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    env: {
+      ...inherited,
+      AITK_NON_INTERACTIVE: '1',
+      AITK_STATE_DIR: join(options.cwd, '.aitk-state'),
+      AITK_SANDBOX_DIR: join(options.cwd, '.aitk-state', 'sandbox'),
+      ...options.env,
+    },
+  })
+
+  const after = snapshotStateDir()
+  if (detectStateLeak(before, after)) {
+    throw new ContainmentViolation(
+      `A case wrote into this machine's real toolkit state at ${stateDir()}. ` +
+        'Every process-tier case must stay inside the directory it declared.',
+    )
+  }
+
+  return {
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    json: parseJson(result.stdout),
+  }
+}
+
+/**
+ * Data goes to stdout and framing to stderr, so a harness reading `--json`
+ * off the merged output would assert against a record no verb ever wrote. A
+ * command that emits no JSON, or fails before it gets there, leaves the
+ * field `undefined` rather than throwing, so a case asserting the exit code
+ * of a refusal is not also forced to guard a parse.
+ */
+function parseJson(stdout: string): unknown {
+  const trimmed = stdout.trim()
+  if (trimmed === '') return undefined
+
+  try {
+    return JSON.parse(trimmed)
+  } catch {
+    return undefined
+  }
+}

package/src/sessions/resolve.ts

@@ -1,3 +1,4 @@
+import { basename } from 'node:path'
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
 import {
@@ -186,3 +187,105 @@ export async function resolveSessions(
 
   return { kind: 'resolved', dir: registry.dir, confidence, sessions }
 }
+
+/** The environment slice the caller's own identity is read from. */
+export type Env = Record<string, string | undefined>
+
+/** Why the caller's own row could not be named, rather than an empty result. */
+export type SelfUnresolved = 'no-identity' | 'no-row'
+
+/**
+ * What the environment offers about the session making the call.
+ *
+ * Both fields are candidates rather than a pair, since a client sets them
+ * independently and a caller can arrive carrying either one alone.
+ */
+export interface SelfIdentity {
+  readonly sessionId: string | null
+  readonly pid: number | null
+}
+
+export type SelfReport =
+  | { readonly kind: 'self'; readonly session: ResolvedSession }
+  | {
+      readonly kind: 'unresolved'
+      readonly reason: SelfUnresolved
+      readonly identity: SelfIdentity
+    }
+
+/**
+ * A positive integer, which is what separates a pid from a socket named for
+ * something else. Signal zero addresses the caller's own process group, so a
+ * zero would match a row rather than failing to.
+ */
+function pidOf(value: string | undefined): number | null {
+  if (value === undefined) return null
+  const pid = Number(value.trim())
+  return Number.isInteger(pid) && pid > 0 ? pid : null
+}
+
+/**
+ * Reads whatever the environment states about the calling session.
+ *
+ * Three identifier namespaces are in play and only two of them join to a
+ * roster row. `CLAUDE_CODE_SESSION_ID` is the roster's own `sessionId` and is
+ * read first because it survives a rename, where the name a session carries is
+ * derived from what it turned out to be doing and rotates while a build runs.
+ * `CLAUDE_CODE_HOST_SESSION_ID` is deliberately never read: it holds a
+ * `local_`-prefixed value from the harness namespace that matches no row, and
+ * it is the variable a reader searching the environment for a session id finds
+ * first.
+ *
+ * The socket path is the last rung because its basename is the caller's pid by
+ * a client convention rather than a published interface, so a client that
+ * moves it drops this rung while leaving the two above it standing.
+ */
+export function callerIdentity(env: Env = process.env): SelfIdentity {
+  const stated = env.CLAUDE_CODE_SESSION_ID?.trim()
+  const socket = env.CLAUDE_CODE_MESSAGING_SOCKET
+
+  return {
+    sessionId: stated !== undefined && stated.length > 0 ? stated : null,
+    pid:
+      pidOf(env.CLAUDE_PID) ??
+      pidOf(
+        socket === undefined
+          ? undefined
+          : basename(socket).replace(/\.sock$/, ''),
+      ),
+  }
+}
+
+/**
+ * Names which row of a roster belongs to the caller.
+ *
+ * The read that already returns every field marks none of them as the caller,
+ * so this performs the join rather than adding a source. An identity the
+ * environment does not carry and an identity no row matches are separated,
+ * because the first is a client that states nothing and the second is a
+ * session the roster cannot see. A session driving from Remote Control is the
+ * measured instance of the second: it is addressable on the message channel
+ * and holds no local process record for the roster to report.
+ */
+export function selfOf(
+  sessions: readonly ResolvedSession[],
+  identity: SelfIdentity,
+): SelfReport {
+  if (identity.sessionId === null && identity.pid === null) {
+    return { kind: 'unresolved', reason: 'no-identity', identity }
+  }
+
+  const byId =
+    identity.sessionId === null
+      ? undefined
+      : sessions.find((session) => session.sessionId === identity.sessionId)
+  const byPid =
+    identity.pid === null
+      ? undefined
+      : sessions.find((session) => session.pid === identity.pid)
+  const match = byId ?? byPid
+
+  return match === undefined
+    ? { kind: 'unresolved', reason: 'no-row', identity }
+    : { kind: 'self', session: match }
+}