@erclx/aitk 3.46.0 → 3.47.1

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/gov/superseded.ts

@@ -15,11 +15,33 @@ import { listRepositoryFiles } from '@/git-files'
  */
 export const SUPERSEDED_MARKER = 'aitk-allow-superseded'
 
+/**
+ * What matched at one column.
+ *
+ * `literal` is the superseded value itself. The other three are the stem
+ * followed by a glob, by an angle-bracket placeholder, or by nothing that
+ * continues a name, which are the three forms this corpus writes a family in.
+ * A literal comparison reaches none of them, which is why a rename running the
+ * verb once per name reported clean over seven stale citations.
+ */
+export type SupersededMatch = 'literal' | 'glob' | 'placeholder' | 'prefix'
+
 export interface SupersededHit {
   readonly file: string
   /** One-based, matching the `file:line` form a reader clicks. */
   readonly line: number
   readonly column: number
+  readonly match: SupersededMatch
+  /**
+   * The nearest heading above the hit in a markdown file, absent elsewhere and
+   * above the first heading.
+   *
+   * A line reads differently under the section holding it. `Use the aitk-*
+   * prefix on an internal skill` is a prohibition under `## Must not` and an
+   * instruction anywhere else, and a reviewer reading the line alone made
+   * exactly that misreading against this tree.
+   */
+  readonly heading: string | undefined
   /**
    * Whether the replacement sits on the same line, outside the superseded
    * occurrences themselves.
@@ -45,11 +67,22 @@ export interface SupersededOptions {
   readonly replacement: string
 }
 
+/**
+ * The segment pair a templated citation is matched on, reported so a run states
+ * the net it cast rather than only what the net caught.
+ */
+export interface SupersededStems {
+  readonly superseded: string
+  readonly replacement: string
+}
+
 export type SupersededReport =
   | {
       readonly kind: 'measured'
       readonly superseded: string
       readonly replacement: string
+      /** Absent when the two values yield no bounded stem to match on. */
+      readonly stems: SupersededStems | undefined
       /** Everything git listed, so the report states its own bound. */
       readonly listed: number
       /** Files opened, which is what the verdict actually covers. */
@@ -68,22 +101,181 @@ export type SupersededReport =
  */
 const PREVIEW_LIMIT = 200
 
+/** The separator a family name is built from across this corpus. */
+const SEGMENT_SEPARATOR = '-'
+
+/**
+ * A character that continues a name, so `aitk-` inside `aitk-cli` is read as
+ * one name rather than as the family prefix written bare.
+ */
+const NAME_CHARACTER = /[A-Za-z0-9]/
+
 /**
- * Whether `replacement` appears on the line somewhere other than inside the
- * superseded occurrences, which is what makes the flag mean anything when one
- * value contains the other.
+ * A character that puts the stem mid-name when it sits directly before it, so
+ * a stem is only read where a name starts.
+ *
+ * The separator is here and not in `NAME_CHARACTER` because it decides one side
+ * only. `aitk-check-toolkit-` is a temp-directory prefix and matched the stem
+ * `toolkit` on four fixtures before this, where `claude/skills/toolkit-*` is a
+ * path and has to keep matching.
+ */
+const SEGMENT_CONTINUATION = /[A-Za-z0-9_-]/
+
+const HEADING = /^#{1,6}\s+\S/
+
+/**
+ * A fence opening or closing a code block, tracked so a shell comment inside
+ * one is not read as the section a hit below it sits under. A `# Install` line
+ * in a bash block is the ordinary shape of that.
+ */
+const FENCE = /^\s*(?:```|~~~)/
+
+/**
+ * The segment the two values differ on, carried with everything they share
+ * ahead of it.
+ *
+ * The shared prefix alone is what this exists against. `aitk-cli` and
+ * `aitk-feedback-file` share `aitk`, so a stem cut there matches every sibling
+ * and reports the whole family on a rename of one folder. Including the
+ * differing segment bounds the net to what actually changed, which leaves
+ * `aitk-cli` to `aitk-shell` matching neither sibling and `toolkit-operator` to
+ * `aitk-operator` matching the family prefix that did move.
+ *
+ * An empty replacement yields nothing. Retiring a value outright leaves no
+ * second value to diverge from, so every stem would run to the first segment
+ * and match the family the retirement never touched.
+ */
+export function deriveStems(
+  options: SupersededOptions,
+): SupersededStems | undefined {
+  if (options.replacement === '') return undefined
+
+  const supersededSegments = options.superseded.split(SEGMENT_SEPARATOR)
+  const replacementSegments = options.replacement.split(SEGMENT_SEPARATOR)
+
+  let index = 0
+  while (
+    index < supersededSegments.length &&
+    index < replacementSegments.length &&
+    supersededSegments[index] === replacementSegments[index]
+  ) {
+    index += 1
+  }
+
+  const superseded = trimSeparators(
+    supersededSegments.slice(0, index + 1).join(SEGMENT_SEPARATOR),
+  )
+  const replacement = trimSeparators(
+    replacementSegments.slice(0, index + 1).join(SEGMENT_SEPARATOR),
+  )
+
+  if (superseded === '' || replacement === '') return undefined
+  if (superseded === replacement) return undefined
+
+  return { superseded, replacement }
+}
+
+function trimSeparators(value: string): string {
+  let end = value.length
+  while (end > 0 && value[end - 1] === SEGMENT_SEPARATOR) end -= 1
+  return value.slice(0, end)
+}
+
+/**
+ * Which templated form sits at `column`, or nothing when the stem there
+ * continues into an ordinary name.
+ *
+ * The character after `<stem>-` decides all three, so one scan reads every
+ * form. A name character means a sibling spelled out, which the literal
+ * comparison already answers for or correctly ignores.
+ */
+function classifyStem(
+  line: string,
+  column: number,
+  stem: string,
+): SupersededMatch | undefined {
+  const before = column === 0 ? '' : line[column - 1]
+  if (before !== '' && SEGMENT_CONTINUATION.test(before)) return undefined
+
+  const after = line[column + stem.length + 1] ?? ''
+  if (after === '*') return 'glob'
+  if (after === '<') return 'placeholder'
+  if (after !== '' && NAME_CHARACTER.test(after)) return undefined
+  return 'prefix'
+}
+
+/**
+ * Whether the value replacing whatever matched appears on the line somewhere
+ * other than inside the matched occurrences, which is what makes the flag mean
+ * anything when one value contains the other.
  *
  * An empty replacement carries nothing, so it answers false rather than the
  * true every line returns from a containment test against the empty string.
  * Retiring a value outright is what passes one, and reporting every finding as
  * carrying its replacement there says the opposite of what happened.
+ *
+ * A templated hit reads the stem pair instead, since the line repairing
+ * `toolkit-*` carries `aitk-*` and never the full name either value spells.
  */
-function carriesReplacement(line: string, options: SupersededOptions): boolean {
-  if (options.replacement === '') return false
-  return line.split(options.superseded).join('').includes(options.replacement)
+function carriesReplacement(
+  line: string,
+  options: SupersededOptions,
+  stems: SupersededStems | undefined,
+  match: SupersededMatch,
+): boolean {
+  if (match === 'literal') {
+    if (options.replacement === '') return false
+    return line.split(options.superseded).join('').includes(options.replacement)
+  }
+
+  if (stems === undefined) return false
+  const matched = `${stems.superseded}${SEGMENT_SEPARATOR}`
+  return line
+    .split(matched)
+    .join('')
+    .includes(`${stems.replacement}${SEGMENT_SEPARATOR}`)
 }
 
-/** Every occurrence of `superseded` in one file's text, exemptions separated. */
+/**
+ * Every column in one line carrying the superseded value or its family stem,
+ * ordered left to right.
+ *
+ * A stem occurrence sharing a column with a literal one is dropped. The stem is
+ * a prefix of the value it derives from whenever only the last segment moved,
+ * so the same text would otherwise report twice under two kinds.
+ */
+function matchLine(
+  line: string,
+  options: SupersededOptions,
+  stems: SupersededStems | undefined,
+): { column: number; match: SupersededMatch }[] {
+  const matches: { column: number; match: SupersededMatch }[] = []
+
+  let column = line.indexOf(options.superseded)
+  while (column !== -1) {
+    matches.push({ column, match: 'literal' })
+    column = line.indexOf(options.superseded, column + 1)
+  }
+
+  if (stems !== undefined) {
+    const pattern = `${stems.superseded}${SEGMENT_SEPARATOR}`
+    let at = line.indexOf(pattern)
+    while (at !== -1) {
+      const form = classifyStem(line, at, stems.superseded)
+      if (form !== undefined && !matches.some((hit) => hit.column === at)) {
+        matches.push({ column: at, match: form })
+      }
+      at = line.indexOf(pattern, at + 1)
+    }
+  }
+
+  return matches.sort((first, second) => first.column - second.column)
+}
+
+/**
+ * Every occurrence of `superseded` or of its family stem in one file's text,
+ * exemptions separated.
+ */
 export function sweepText(
   file: string,
   text: string,
@@ -92,10 +284,19 @@ export function sweepText(
   const lines = text.split('\n')
   const findings: SupersededHit[] = []
   const exempt: SupersededHit[] = []
+  const stems = deriveStems(options)
+  const sectioned = file.endsWith('.md')
+  let heading: string | undefined
+  let fenced = false
 
   for (const [index, line] of lines.entries()) {
-    let column = line.indexOf(options.superseded)
-    if (column === -1) continue
+    if (sectioned) {
+      if (FENCE.test(line)) fenced = !fenced
+      else if (!fenced && HEADING.test(line)) heading = line.trim()
+    }
+
+    const matches = matchLine(line, options, stems)
+    if (matches.length === 0) continue
 
     const muted = isMarked(lines, index, SUPERSEDED_MARKER)
     const bucket = muted ? exempt : findings
@@ -104,17 +305,17 @@ export function sweepText(
       trimmed.length > PREVIEW_LIMIT
         ? `${trimmed.slice(0, PREVIEW_LIMIT)}…`
         : trimmed
-    const alsoReplacement = carriesReplacement(line, options)
 
-    while (column !== -1) {
+    for (const { column, match } of matches) {
       bucket.push({
         file,
         line: index + 1,
         column: column + 1,
-        carriesReplacement: alsoReplacement,
+        match,
+        heading,
+        carriesReplacement: carriesReplacement(line, options, stems, match),
         preview,
       })
-      column = line.indexOf(options.superseded, column + 1)
     }
   }
 
@@ -135,9 +336,15 @@ export function sweepText(
  * what was listed, opened, and skipped are what keep it from reading as a
  * verdict over the whole tree.
  *
+ * Beside the literal comparison it matches the family stem the two values
+ * differ on, so a citation writing the family as a pattern enters the report.
+ * The trade is false positives, bounded at one across a sixteen-folder rename,
+ * which is why this reports rather than gates.
+ *
  * What it cannot see is a prose reference that went stale without carrying the
- * value, such as a declaration citing the wrong standard for the transform. A
- * value sweep closes most of this class and no part of that one.
+ * value, such as a declaration citing the wrong standard for the transform, and
+ * a family written in a form neither the value nor the three stem shapes reach.
+ * A value sweep closes most of this class and no part of either one.
  */
 export async function readSuperseded(
   root: string,
@@ -198,6 +405,7 @@ export async function readSuperseded(
     kind: 'measured',
     superseded: options.superseded,
     replacement: options.replacement,
+    stems: deriveStems(options),
     listed: listed.length,
     files,
     skipped,

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