spexcode 0.5.2 → 0.5.4

package/README.md

@@ -227,7 +227,7 @@ manuals are `spex guide` (the workflow), `spex guide spec`, `spex guide eval`, a
 ## Contributing
 
 [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) gets you from a clone to a first merged change.
-[`docs/AGENT_GUIDE.md`](docs/AGENT_GUIDE.md) has the full mechanics of the node model and the
+[spexcode.net](https://spexcode.net) has the full mechanics of the node model and the
 reflexive plugin system.
 
 ## Credit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",

package/spec-cli/bin/spex.mjs

@@ -53,5 +53,29 @@ function resolveTsxCli() {
   }
 }
 const tsxCli = resolveTsxCli()
-spawn(process.execPath, [tsxCli, cli, ...process.argv.slice(2)], { stdio: 'inherit' })
+const args = process.argv.slice(2)
+const env = { ...process.env }
+// A backend/dashboard is a project or host control plane, never the managed session that happened to start
+// it. Scrub before tsx starts: doing this inside cli.ts is too late because tsx's resident esbuild helper has
+// already inherited the caller. New session launches provide the adapter-registry-derived key manifest; the
+// fallback covers sessions created before that manifest existed.
+if (args[0] === 'serve' || args[0] === 'dashboard') {
+  const identityKeys = (env.SPEXCODE_SESSION_IDENTITY_VARS
+    || 'SPEXCODE_SESSION_ID,CLAUDE_CODE_SESSION_ID,CODEX_THREAD_ID,OPENCODE_SESSION_ID,PI_SESSION_ID')
+    .split(',').map((key) => key.trim()).filter(Boolean)
+  for (const key of identityKeys) delete env[key]
+}
+const inheritedMaintenanceFds = [
+  ...(env.SPEXCODE_MAINTENANCE_BROKER_FDS || '').split(','),
+  env.SPEXCODE_MAINTENANCE_DELEGATE_FD || '',
+].map(Number).filter((fd) => Number.isInteger(fd) && fd >= 3)
+if (inheritedMaintenanceFds.length) {
+  const req = createRequire(join(pkg, 'package.json'))
+  const tsxImport = req.resolve('tsx/esm')
+  const stdio = Array(Math.max(2, ...inheritedMaintenanceFds) + 1).fill('ignore')
+  stdio[0] = stdio[1] = stdio[2] = 'inherit'
+  for (const fd of inheritedMaintenanceFds) stdio[fd] = 'inherit'
+  spawn(process.execPath, ['--import', tsxImport, cli, ...args], { stdio, env })
+    .on('exit', (code) => process.exit(code ?? 0))
+} else spawn(process.execPath, [tsxCli, cli, ...args], { stdio: 'inherit', env })
   .on('exit', (code) => process.exit(code ?? 0))

package/spec-cli/hooks/dispatch.sh

@@ -30,6 +30,11 @@ export SPEXCODE_HARNESS="$harness"
 # source it here too for hp_runtime_dir (the per-project store dir).
 export SPEXCODE_HARNESS_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/harness.sh"
 . "$SPEXCODE_HARNESS_LIB"
+if [ -n "${SPEX:-}" ]; then
+  read -r -a spex_cmd <<< "$SPEX"
+else
+  spex_cmd=("$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/bin/spex.mjs")
+fi
 proj="${CLAUDE_PROJECT_DIR:-$PWD}"
 # the manifest lives in THIS tree's materialize slot of the GLOBAL per-project store (mirrors layout.treeSlotDir),
 # NOT the worktree — and per tree, so a dispatch can only read the manifest of the tree it fires in
@@ -52,7 +57,25 @@ fi
 [ -f "$manifest" ] || exit 0          # no manifest yet (materialize never ran) → nothing to dispatch
 input="$(cat 2>/dev/null || true)"    # capture stdin ONCE; each handler gets its own copy
 err="/tmp/.spex-hook-$$.err"          # per-dispatch (pid-unique) stderr capture; no cross-session race
-trap 'rm -f "$err"' EXIT
+ticket=""
+cleanup() {
+  [ -z "$ticket" ] || "${spex_cmd[@]}" internal maintenance-end "$ticket" "$$" >/dev/null 2>&1 || true
+  rm -f "$err"
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' HUP TERM
+sid="$(hp_session_id "$input")"
+[ -n "$sid" ] || sid=hook-dispatch
+if ! ticket="$("${spex_cmd[@]}" internal maintenance-begin "$$" "$sid" 2>"$err")"; then
+  reason="$(cat "$err" 2>/dev/null)"
+  [ -n "$reason" ] || reason='maintenance_active: hook dispatch was not admitted'
+  escaped="$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+  printf '{"decision":"block","reason":"%s"}' "$escaped"
+  [ "$SPEXCODE_HARNESS" = codex ] && printf '%s\n' "$reason" >&2
+  exit 2
+fi
+export SPEXCODE_MAINTENANCE_PARENT_TICKET="$ticket"
 rc=0
 # manifest line: event<TAB>order<TAB>block<TAB>script  (pre-sorted by event,order,script)
 while IFS=$'\t' read -r ev order block script; do

package/spec-cli/src/anchors.ts

@@ -1,13 +1,15 @@
 import { join } from 'node:path'
 import { createRequire } from 'node:module'
-import { gitA, type DriftIndex, ancestorsOf, inAncestors, ackCoverFor } from './git.js'
+import { git, gitRequiredA, gitObjectFormat, isGitObjectId, batchRevisionOids, batchBlobTexts, combinedDiffOwnedChanges, driftPathWindow, type DiffLineRange, type DriftIndex, type DriftPathEvent } from './git.js'
+
+const RS = '\x1e'
 
 // ---- the anchor vocabulary ([[code-anchor]]) ----
 // A spec's `code:` entry may pin ONE named unit: `path#symbol` (`#Class.method` for a class method).
 // Everything below the entry parse splits into two layers:
 //   - the LANGUAGE SEAM: pure extractors (content, filename) -> Unit[] — no git, no cache, no fs.
 //     Each extension maps to exactly ONE designated extractor; there is NO cross-tier fallback.
-//   - the LANGUAGE-AGNOSTIC ENGINE: file-revision memo (keyed by Git object id), anchor resolution
+//   - the LANGUAGE-AGNOSTIC ENGINE: file-revision memo (keyed by the complete immutable parse input), anchor resolution
 //     (dead/ambiguous), diff-hunk ∩ unit-range intersection over the drift window. It never knows
 //     which language it is measuring.
 
@@ -16,13 +18,14 @@ export type Unit = { name: string; kind: string; start: number; end: number; typ
 export type Extractor = {
   id: string
   claims(ext: string): boolean
-  // true = usable here. A string is WHY it cannot run — lint turns that into an ERROR with the repair
-  // entrypoint (never a silent or degraded pass): the designated extractor either runs or the anchor
-  // is unverifiable.
+  // true = usable here. A string is WHY it cannot run — lint turns that into a visible error and
+  // skips the affected anchors as unverified while continuing the other checks (never a crash or fake pass).
   ready(): true | string
   // PURE function of its arguments (importable by an external benchmark/scorer as-is). Throws when the
   // content cannot be parsed — the caller maps that to a conservative verdict, never a silent skip.
   extract(content: string, filename: string): Unit[]
+  // Every input that can affect extract() must be represented here before its result enters the memo.
+  memoKey: (filename: string) => string
 }
 
 export type CodeEntry = { path: string; anchor: string | null }
@@ -43,6 +46,13 @@ export function parseCodeEntry(raw: string): CodeEntry {
 // this parser never touches fs.
 export type RelationEntry = { path: string; selectors: string[] }
 export type RelationParse = { entries: RelationEntry[]; problems: string[] }
+export function relationClaimsPath(claim: string, file: string): boolean {
+  if (claim === file) return true
+  if (file.startsWith(claim.replace(/\/+$/, '') + '/')) return true
+  if (!claim.includes('*')) return false
+  const pattern = claim.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+  return new RegExp(`^${pattern}$`).test(file)
+}
 export function parseRelation(raws: string[], relation: 'code' | 'related'): RelationParse {
   const order: string[] = []
   const byPath = new Map<string, { bare: boolean; selectors: string[] }>()
@@ -69,17 +79,23 @@ export function parseRelation(raws: string[], relation: 'code' | 'related'): Rel
 }
 
 // ---- extractor: ts-ast (the designated extractor for the JS family) ----
-// Parse-only via the HOST project's own typescript (resolved from the repo root, walking up like any
-// require) — never a bundled copy, so the parse matches what the project itself compiles with. Not
-// resolvable => ready() returns the repair entrypoint and lint ERRORS (no regex fallback for JS).
+// Parse-only via the HOST project's own typescript, so the parse matches what the project itself compiles
+// with. If it cannot resolve, ready() returns a loud unverified verdict and lint skips these anchors
+// without crashing (no bundled compiler, regex fallback, or fake pass for JS).
 const JS_EXTS = new Set(['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'mts', 'cts'])
+const TS_AST_MEMO_SCHEMA = 'ts-ast-memo-v1'
 
 export function tsAstExtractor(root: string): Extractor {
   let ts: any | null | undefined // undefined = unprobed; null = unresolvable
+  let tsModulePath = ''
   let readiness: true | string | undefined
   const probe = () => {
     if (ts !== undefined) return
-    try { ts = createRequire(join(root, 'package.json'))('typescript') } catch { ts = null }
+    try {
+      const require = createRequire(join(root, 'package.json'))
+      tsModulePath = require.resolve('typescript')
+      ts = require('typescript')
+    } catch { ts = null }
   }
   return {
     id: 'ts-ast',
@@ -87,12 +103,12 @@ export function tsAstExtractor(root: string): Extractor {
     ready() {
       if (readiness !== undefined) return readiness
       probe()
-      if (!ts) return (readiness = `typescript is not resolvable from ${root} — anchors on JS-family files need the host project's typescript: run 'npm i -D typescript', or remove the #anchor`)
+      if (!ts) return (readiness = `typescript is not resolvable from the governed repository (${root}) — JS-family anchors were skipped and remain unverified; run 'npm i -D typescript@5', or remove the #anchor`)
       // resolvability is not usability: typescript@7 (the Go rewrite) may resolve yet not expose the JS
-      // compiler API this extractor drives. Probe the ACTUAL surface with a tiny parse — an incompatible
-      // host typescript is a loud error, never a silent pass or downgrade.
+      // compiler API this extractor drives. Probe the ACTUAL surface with a tiny parse. Once a candidate
+      // resolves, incompatibility is loud rather than silently changing parser versions.
       try {
-        const sf = ts.createSourceFile('probe.ts', 'const x = 1', ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+        const sf = ts.createSourceFile('probe.ts', 'const x = 1', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS)
         if (!sf?.statements?.length || sf.parseDiagnostics?.length) throw new Error('probe parse failed')
         readiness = true
       } catch {
@@ -107,7 +123,7 @@ export function tsAstExtractor(root: string): Extractor {
         : /\.(jsx)$/.test(filename) ? ts.ScriptKind.JSX
         : /\.(ts|mts|cts)$/.test(filename) ? ts.ScriptKind.TS
         : ts.ScriptKind.JS
-      const sf = ts.createSourceFile(filename, content, ts.ScriptTarget.Latest, true, kind)
+      const sf = ts.createSourceFile(filename, content, ts.ScriptTarget.Latest, false, kind)
       // parse-only gate: a file that does not parse yields GARBAGE units (a shell script's `x=$(...)`
       // parses as a const) — throw so the caller renders an honest "cannot parse" verdict instead.
       if (sf.parseDiagnostics?.length) throw new Error(`${filename} does not parse as ${ts.ScriptKind[kind]} (${sf.parseDiagnostics.length} syntax error(s))`)
@@ -139,6 +155,11 @@ export function tsAstExtractor(root: string): Extractor {
       }
       return units
     },
+    memoKey(filename) {
+      probe()
+      const host = ts ? `${tsModulePath}\0${ts.version ?? 'unknown'}` : `unresolved\0${root}`
+      return `${TS_AST_MEMO_SCHEMA}\0${host}\0target:Latest\0parents:false\0${filename}`
+    },
   }
 }
 
@@ -284,6 +305,19 @@ export function heuristicExtractor(spec: LangSpec): Extractor {
       }
       return units
     },
+    memoKey(filename) {
+      const regex = (r: RegExp | undefined) => r ? `${r.source}/${r.flags}` : null
+      return JSON.stringify({
+        schema: 'heuristic-memo-v1', filename, id: spec.id, extensions: spec.extensions,
+        decls: spec.decls.map((d) => ({
+          re: regex(d.re), kind: d.kind, typeOnly: !!d.typeOnly, classOpener: !!d.classOpener,
+          declList: !!d.declList, scopeOpener: !!d.scopeOpener, memberOf: d.memberOf ?? null,
+        })),
+        member: spec.member ? { re: regex(spec.member.re), blacklist: regex(spec.member.blacklist) } : null,
+        indentScopes: spec.indentScopes ? { decorator: regex(spec.indentScopes.decorator) } : null,
+        boundary: regex(spec.boundary),
+      })
+    },
   }
 }
 
@@ -355,21 +389,41 @@ export function resolveAnchor(units: Unit[], symbol: string): AnchorResolution {
   return { ok: hits[0] }
 }
 
+// The one selector/range intersection used by historical commits and a pinned worktree overlay.
+export function selectorsHitRanges(units: readonly Unit[], symbols: readonly string[], ranges: readonly [number, number][]): string[] {
+  return symbols.filter((symbol) => {
+    const matching = units.filter((unit) => unit.name === symbol)
+    return matching.length > 0 && ranges.some(([start, end]) => matching.some((unit) => start <= unit.end && unit.start <= end))
+  })
+}
+
+// Ordinary zero-context ranges. The side chooses the immutable image whose units the caller resolved.
+export function diffHunkRanges(patch: string, side: 'old' | 'new' = 'new'): [number, number][] {
+  const ranges: [number, number][] = []
+  for (const match of patch.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
+    const offset = side === 'old' ? 1 : 3
+    const start = +match[offset]
+    const count = match[offset + 1] === undefined ? 1 : +match[offset + 1]
+    if (count > 0) ranges.push([start, start + count - 1])
+  }
+  return ranges
+}
+
 // ---- the historical hit engine (language-agnostic; batch short-lived git, no resident process) ----
 
-// units of a file AS OF a commit, memoized by (Git object id, extractor id). File content identified by
-// an object id is immutable, so the memo never invalidates; distinct file revisions in a window are few.
+// units of a file AS OF a commit, memoized by the complete immutable parse identity. File content identified
+// by an object id is immutable, but the extractor also consumes filename and host/config identity; distinct
+// file revisions in a window are few.
 // 'absent' = no file at that commit; 'unparseable' = the extractor rejected that revision's content.
 type FileRevisionUnits = { units: Unit[] } | { absent: true } | { unparseable: string }
 const fileRevisionUnitMemo = new Map<string, FileRevisionUnits>()
 const MEMO_MAX = 4096
-async function unitsAtFileRevision(root: string, commit: string, path: string, x: Extractor): Promise<FileRevisionUnits> {
-  const oid = (await gitA(['-C', root, 'rev-parse', `${commit}:${path}`])).trim()
+async function unitsAtFileRevision(commit: string, path: string, x: Extractor, objectFormat: string, oid: string | null, text?: string): Promise<FileRevisionUnits> {
   if (!oid) return { absent: true }
-  const key = `${oid}\0${x.id}`
+  const key = `${objectFormat}\0${oid}\0${x.memoKey(path)}`
   const hit = fileRevisionUnitMemo.get(key)
   if (hit) return hit
-  const text = await gitA(['-C', root, 'cat-file', 'blob', oid]) // dead-words-ok: git plumbing — 'blob' is Git's object type, not product vocabulary
+  if (text === undefined) throw new Error(`git cat-file --batch omitted object ${oid} for ${commit}:${path}`)
   let result: FileRevisionUnits
   try { result = { units: x.extract(text, path) } } catch (e: any) { result = { unparseable: e?.message ?? String(e) } }
   if (fileRevisionUnitMemo.size >= MEMO_MAX) fileRevisionUnitMemo.clear()
@@ -377,57 +431,137 @@ async function unitsAtFileRevision(root: string, commit: string, path: string, x
   return result
 }
 
-// post-image line ranges of one commit's diff to one file (`@@ -a,b +c,d @@`, --unified=0). d>0 → lines
-// c..c+d-1 changed; d==0 (pure deletion) → the point line after which content vanished. Immutable per
-// (commit, file), memoized.
-const hunkMemo = new Map<string, [number, number][]>()
-async function hunksAt(root: string, commit: string, path: string): Promise<[number, number][]> {
-  const key = `${commit}\0${path}`
+// Changed line ranges on both sides of one commit's diff. Ordinary commits have one parent image. Merges
+// retain one before-image per parent and only all-parent authored rows; an owned line never widens to an
+// adjacent inherited line merely because Git placed both in one `@@@` hunk.
+type HunkRanges = { after: DiffLineRange[]; before: DiffLineRange[][] }
+const hunkMemo = new Map<string, HunkRanges>()
+async function hunksAt(root: string, event: DriftPathEvent): Promise<HunkRanges> {
+  const paths = [...new Set([event.historicalPath, ...event.parents.map((parent) => parent.historicalPath)])]
+  const key = `${event.commit}\0${paths.join('\x1e')}`
   const hit = hunkMemo.get(key)
   if (hit) return hit
-  const out = await gitA(['-C', root, '-c', 'core.quotePath=false', 'show', '--unified=0', '--format=', commit, '--', path])
-  const ranges: [number, number][] = []
-  for (const m of out.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm)) {
-    const c = +m[1], d = m[2] === undefined ? 1 : +m[2]
-    ranges.push(d > 0 ? [c, c + d - 1] : [Math.max(1, c), Math.max(1, c)])
+  const merge = event.parents.length > 1
+  const out = await gitRequiredA(['-C', root, '-c', 'core.quotePath=false', 'show', '--cc', '--combined-all-paths', '--unified=0', '-M', '--format=', event.commit,
+    ...(merge ? [] : ['--', ...paths])],
+    `cannot derive anchor hunks for ${event.commit}:${event.historicalPath}`)
+  let ranges: HunkRanges = { after: [], before: [[]] }
+  if (/^@@@/m.test(out)) {
+    const owned = combinedDiffOwnedChanges(out).get(event.historicalPath)
+    if (!owned) throw new Error(`combined diff for ${event.commit} did not expose owned ranges for '${event.historicalPath}'`)
+    ranges = owned
+  } else {
+    for (const m of out.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
+      const oldStart = +m[1], oldCount = m[2] === undefined ? 1 : +m[2]
+      const newStart = +m[3], newCount = m[4] === undefined ? 1 : +m[4]
+      if (oldCount > 0) ranges.before[0].push([oldStart, oldStart + oldCount - 1])
+      if (newCount > 0) ranges.after.push([newStart, newStart + newCount - 1])
+    }
   }
   if (hunkMemo.size >= MEMO_MAX) hunkMemo.clear()
   hunkMemo.set(key, ranges)
   return ranges
 }
 
+// Ordinary commits whose two images keep one path share a single query. Renames and merges retain distinct
+// image paths, so they stay on hunksAt's exact event-shaped query.
+async function hunksAtMany(root: string, commits: string[], path: string): Promise<Map<string, HunkRanges>> {
+  const result = new Map<string, HunkRanges>()
+  const ordinary = [...new Set(commits)]
+  if (!ordinary.length) return result
+  const out = await gitRequiredA(['-C', root, '-c', 'core.quotePath=false', 'log', '--no-walk', '--no-merges', '--patch', '--unified=0', '-M',
+    `--format=${RS}%H`, ...ordinary, '--', path], `cannot derive anchor hunks for ${path}`)
+  for (const rec of out.split(RS)) {
+    const normalized = rec.replace(/^\n/, '')
+    if (!normalized) continue
+    const newline = normalized.indexOf('\n')
+    const hash = (newline < 0 ? normalized : normalized.slice(0, newline)).trim()
+    if (!isGitObjectId(root, hash)) throw new Error(`anchor hunk query returned malformed object id '${hash || 'empty'}'`)
+    const patch = newline < 0 ? '' : normalized.slice(newline + 1)
+    const ranges: HunkRanges = { after: [], before: [[]] }
+    for (const m of patch.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
+      const oldStart = +m[1], oldCount = m[2] === undefined ? 1 : +m[2]
+      const newStart = +m[3], newCount = m[4] === undefined ? 1 : +m[4]
+      if (oldCount > 0) ranges.before[0].push([oldStart, oldStart + oldCount - 1])
+      if (newCount > 0) ranges.after.push([newStart, newStart + newCount - 1])
+    }
+    result.set(hash, ranges)
+  }
+  return result
+}
+
 // the drift window of an anchored file: every commit to `path` not reachable from the spec's version
 // and not covered by a valid Spec-OK ack — the SAME set driftFor counts, exposed as commits so the
-// anchor engine can probe each one. (fileCommits comes from a --name-only walk, which lists no files
-// for merge commits — the window is non-merge by construction.)
-export function windowCommits(idx: DriftIndex, sinceHash: string, path: string): string[] {
+// anchor engine can probe each one. Ordinary file commits and merge-authored dense-combined paths are
+// indexed separately so clean merge transport is never charged twice.
+export function windowEvents(idx: DriftIndex, sinceHash: string, path: string, nodeId?: string): DriftPathEvent[] {
   if (!sinceHash) return []
-  const base = ancestorsOf(idx, sinceHash)
-  if (!base) return []
-  const cover = ackCoverFor(idx, sinceHash)
-  return (idx.fileCommits.get(path) ?? []).filter((h) => !inAncestors(idx, base, h) && !cover.some((a) => inAncestors(idx, a, h)))
+  return driftPathWindow(idx, sinceHash, path, nodeId) ?? []
 }
 
-// which window commits TOUCHED any of the anchored units: the commit's --unified=0 hunks intersect a
-// unit's line range extracted from the file AS IT EXISTED AT THAT COMMIT (never from HEAD — units later
-// renamed or moved still attribute correctly). Several selectors are OR — a commit appears ONCE, with
-// `selectors` naming exactly which units its hunks intersected (so diagnostics can attribute the hit).
-// A version whose content the extractor cannot parse is a CONSERVATIVE hit for every selector
-// (`unparseable` set) — over-warn, never silently skip.
+// Which window commits touched an anchored unit. Added lines intersect the result-image unit; deleted lines
+// intersect the parent-image unit. A merge owns a deletion only when every parent-side range belongs to the
+// selector. This is why events retain their immutable post/preimage paths instead of resolving every blob
+// through the current filename. Several selectors are OR'd and one commit still produces one hit row.
+// An historical image the designated extractor cannot parse is a conservative hit (`unparseable`).
 export type AnchorHit = { commit: string; selectors: string[]; unparseable?: string }
-export async function anchorHitCommits(root: string, win: string[], path: string, symbols: string[], x: Extractor): Promise<AnchorHit[]> {
-  const hits: AnchorHit[] = []
-  for (const c of win) {
-    const at = await unitsAtFileRevision(root, c, path, x)
-    if ('absent' in at) continue // file not in that commit's tree — nothing of the anchor to touch
-    if ('unparseable' in at) { hits.push({ commit: c, selectors: [...symbols], unparseable: at.unparseable }); continue }
-    const bySym = symbols
-      .map((sym) => ({ sym, ranges: at.units.filter((u) => u.name === sym) }))
-      .filter((s) => s.ranges.length) // a unit absent under this name at that commit can't be touched
-    if (!bySym.length) continue
-    const hunks = await hunksAt(root, c, path)
-    const touched = bySym.filter((s) => hunks.some(([a, b]) => s.ranges.some((u) => a <= u.end && u.start <= b))).map((s) => s.sym)
-    if (touched.length) hits.push({ commit: c, selectors: touched })
+export async function anchorHitCommits(root: string, win: DriftPathEvent[], symbols: string[], regs: Extractor[]): Promise<AnchorHit[]> {
+  const hits = new Map<string, { selectors: Set<string>; unparseable?: string }>()
+  const objectFormat = gitObjectFormat(root)
+  type Revision = { commit: string; path: string }
+  const revisionKey = ({ commit, path }: Revision) => `${commit}\0${path}`
+  const revisions = new Map<string, Revision>()
+  for (const event of win) {
+    const refs = [{ commit: event.commit, path: event.historicalPath }, ...event.parents.map(({ commit, historicalPath }) => ({ commit, path: historicalPath }))]
+    for (const ref of refs) revisions.set(revisionKey(ref), ref)
+  }
+  const refs = [...revisions.values()]
+  const oids = batchRevisionOids(root, refs.map(({ commit, path }) => `${commit}:${path}`))
+  const blobs = batchBlobTexts(root, oids.filter((oid): oid is string => !!oid))
+  const units = new Map<string, FileRevisionUnits>()
+  for (let index = 0; index < refs.length; index++) {
+    const ref = refs[index], oid = oids[index]
+    const x = extractorFor(regs, extOf(ref.path))
+    const ready = x?.ready()
+    if (!x || ready !== true) {
+      units.set(revisionKey(ref), { unparseable: !x ? `no designated extractor for ${ref.path}` : String(ready) })
+      continue
+    }
+    units.set(revisionKey(ref), await unitsAtFileRevision(ref.commit, ref.path, x, objectFormat, oid, oid ? blobs.get(oid) : undefined))
+  }
+  const byPath = new Map<string, string[]>()
+  for (const event of win) {
+    if (event.parents.length > 1 || event.parents.some((parent) => parent.historicalPath !== event.historicalPath)) continue
+    const commits = byPath.get(event.historicalPath) ?? []
+    commits.push(event.commit)
+    byPath.set(event.historicalPath, commits)
+  }
+  const ordinaryHunks = new Map<string, Map<string, HunkRanges>>()
+  for (const [path, commits] of byPath) ordinaryHunks.set(path, await hunksAtMany(root, commits, path))
+  const intersects = (ranges: DiffLineRange[], candidates: Unit[]) =>
+    ranges.some(([start, end]) => candidates.some((unit) => start <= unit.end && unit.start <= end))
+  for (const event of win) {
+    const after = units.get(revisionKey({ commit: event.commit, path: event.historicalPath }))!
+    const before = event.parents.map(({ commit, historicalPath }) => units.get(revisionKey({ commit, path: historicalPath }))!)
+    const ranges = ordinaryHunks.get(event.historicalPath)?.get(event.commit)
+      ?? await hunksAt(root, event)
+    if (event.parents.length && ranges.before.length !== before.length)
+      throw new Error(`anchor diff for ${event.commit}:${event.historicalPath} has ${ranges.before.length} parent ranges for ${before.length} parents`)
+    const hit = hits.get(event.commit) ?? { selectors: new Set<string>() }
+    const broken = [after, ...before].find((image) => 'unparseable' in image)
+    if (broken && 'unparseable' in broken) {
+      for (const symbol of symbols) hit.selectors.add(symbol)
+      hit.unparseable = broken.unparseable
+    } else {
+      for (const symbol of symbols) {
+        const afterUnits = 'units' in after ? after.units.filter((unit) => unit.name === symbol) : []
+        const authoredAfter = intersects(ranges.after, afterUnits)
+        const authoredBefore = before.length > 0 && before.every((image, parent) =>
+          'units' in image && intersects(ranges.before[parent], image.units.filter((unit) => unit.name === symbol)))
+        if (authoredAfter || authoredBefore) hit.selectors.add(symbol)
+      }
+    }
+    if (hit.selectors.size) hits.set(event.commit, hit)
   }
-  return hits
+  return [...hits].map(([commit, hit]) => ({ commit, selectors: [...hit.selectors], ...(hit.unparseable ? { unparseable: hit.unparseable } : {}) }))
 }

package/spec-cli/src/attach.ts

@@ -8,6 +8,7 @@
 import { spawnSync } from 'node:child_process'
 import { networkInterfaces } from 'node:os'
 import { alive, apiBase, TMUX_SOCK } from './sessions.js'
+import { runSessionOperation } from './session-maintenance.js'
 
 const AGENT_ALTERNATIVES = 'read the pane with `spex session show <SEL> --capture`, drive it with `session send` (plain text first; `--keys` only as a last resort)'
 
@@ -33,18 +34,20 @@ The tmux session lives on THAT machine — a terminal can't be attached over HTT
 // foreground takeover of the session's real tmux window; returns only via detach (C-b d) or the session
 // ending. Interactive and blocking by design — a caller without a terminal (an agent inside its turn, a
 // pipe) is refused up front and pointed at the remote-capable verbs instead of tmux's bare "not a terminal".
-export async function attachSession(id: string): Promise<never> {
+export async function attachSession(id: string): Promise<number> {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     console.error(`spex session attach: attach is INTERACTIVE and needs a terminal — it blocks until you detach.
 An agent must not run it inside a turn (it freezes you); ${AGENT_ALTERNATIVES}.`)
     process.exit(2)
   }
-  if (!(await alive(id))) {
-    console.error(`spex session attach: ${id} is offline — no live tmux session to attach.
+  return runSessionOperation({ op: 'attach', sessionId: id }, async () => {
+    if (!(await alive(id))) {
+      console.error(`spex session attach: ${id} is offline — no live tmux session to attach.
 Bring it back with \`spex session resume ${id}\`, or read its record with \`spex session show ${id}\`.`)
-    process.exit(1)
-  }
-  console.log(`attaching to ${id} — detach with C-b d (the session keeps running)`)
-  const r = spawnSync('tmux', ['-u', '-L', TMUX_SOCK, 'attach-session', '-t', id], { stdio: 'inherit' })
-  process.exit(r.status ?? 1)
+      return 1
+    }
+    console.log(`attaching to ${id} — detach with C-b d (the session keeps running)`)
+    const r = spawnSync('tmux', ['-u', '-L', TMUX_SOCK, 'attach-session', '-t', id], { stdio: 'inherit' })
+    return r.status ?? 1
+  })
 }

package/spec-cli/src/claude-headless.ts

@@ -1,11 +1,13 @@
-import { appendFileSync, mkdirSync, rmSync } from 'node:fs'
-import { createConnection, createServer, type Server, type Socket } from 'node:net'
+import { rmSync } from 'node:fs'
+import { createServer, type Server, type Socket } from 'node:net'
 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { DispatchResult, HarnessDeliveryRecord } from './harness.js'
+import { controlRequest, withTimeout } from './headless-controller.js'
+import { shQuote } from './sh.js'
 
 type ControlRequest = { type: 'deliver'; text: string; mode: 'steer' | 'wake' } | { type: 'interrupt' }
 type ClaudeHeadlessDeliveryRecord = HarnessDeliveryRecord & { status?: string }
@@ -32,7 +34,6 @@ const RESULT_EXIT_GRACE_MS = 500
 const TERM_EXIT_GRACE_MS = 500
 const KILL_EXIT_GRACE_MS = 2_000
 
-const shQuote = (s: string) => `'${s.replace(/'/g, `'\''`)}'`
 const userEvent = (text: string) => JSON.stringify({
   type: 'user',
   message: { role: 'user', content: [{ type: 'text', text }] },
@@ -44,70 +45,31 @@ export function claudeHeadlessLaunchCommand(id: string, runtimeDir: string, clau
   return [shQuote(SPEX), 'internal', 'claude-headless-run', shQuote(id), shQuote(runtimeDir), shQuote(claudeCmd), '--'].join(' ')
 }
 
-function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => reject(new Error(message)), ms)
-    promise.then(
-      (value) => { clearTimeout(timer); resolve(value) },
-      (error) => { clearTimeout(timer); reject(error) },
-    )
-  })
-}
-
-function controlRequest(id: string, request: ControlRequest): Promise<DispatchResult> {
-  return new Promise((resolve) => {
-    const socket = createConnection(claudeHeadlessSock(id))
-    let buffer = ''
-    let settled = false
-    const finish = (result: DispatchResult) => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      socket.destroy()
-      resolve(result)
-    }
-    const timer = setTimeout(() => finish({ ok: false, error: `claude-headless control timed out for session ${id}` }), CONTROL_TIMEOUT_MS)
-    socket.setEncoding('utf8')
-    socket.on('connect', () => socket.write(`${JSON.stringify(request)}\n`))
-    socket.on('data', (chunk) => {
-      buffer += chunk
-      const nl = buffer.indexOf('\n')
-      if (nl < 0) return
-      try {
-        const response = JSON.parse(buffer.slice(0, nl)) as DispatchResult
-        finish(response.ok ? { ok: true } : { ok: false, error: response.error || 'claude-headless control rejected the request' })
-      } catch (error) {
-        finish({ ok: false, error: `claude-headless returned an invalid control response: ${(error as Error).message}` })
-      }
-    })
-    socket.on('error', (error) => finish({ ok: false, error: `claude-headless controller unreachable for session ${id}: ${error.message}` }))
-    socket.on('close', () => finish({ ok: false, error: `claude-headless controller closed before confirming session ${id}` }))
-  })
-}
-
 export const deliverViaClaudeHeadless = (rec: ClaudeHeadlessDeliveryRecord, text: string) =>
-  controlRequest(rec.session, { type: 'deliver', text, mode: rec.status === 'active' ? 'steer' : 'wake' })
+  controlRequest(claudeHeadlessSock(rec.session), { type: 'deliver', text, mode: rec.status === 'active' ? 'steer' : 'wake' }, {
+    name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'claude-headless control rejected the request',
+  })
 
 export const interruptClaudeHeadless = (rec: HarnessDeliveryRecord) =>
-  controlRequest(rec.session, { type: 'interrupt' })
+  controlRequest(claudeHeadlessSock(rec.session), { type: 'interrupt' }, {
+    name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'claude-headless control rejected the request',
+  })
 
 export class ClaudeHeadlessController {
   private server: Server | null = null
   private child: ChildTurn | null = null
   private controlQueue: Promise<void> = Promise.resolve()
   private closing = false
-  private readonly messagesPath: string
   private readonly socketPath: string
 
   constructor(
     private readonly id: string,
-    runtimeDir: string,
+    _runtimeDir: string,
     private readonly claudeCmd: string,
     private readonly cwd = process.cwd(),
   ) {
-    const dir = join(runtimeDir, 'sessions', id)
-    mkdirSync(dir, { recursive: true })
-    this.messagesPath = join(dir, 'messages.ndjson')
     this.socketPath = claudeHeadlessSock(id)
   }
 
@@ -246,7 +208,6 @@ export class ClaudeHeadlessController {
         const line = stdoutBuffer.slice(0, nl)
         stdoutBuffer = stdoutBuffer.slice(nl + 1)
         const nativeLine = `${line}\n`
-        appendFileSync(this.messagesPath, nativeLine)
         globalThis.process.stdout.write(nativeLine)
         turn.sawFirstEvent()
         this.observeEvent(turn, line)