spexcode 0.5.8 → 0.5.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "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",
@@ -36,11 +36,13 @@
     "prepack": "node scripts/sync-init-plugins.mjs --check && node scripts/prepack.mjs"
   },
   "dependencies": {
+    "tsx": "^4.19.2"
+  },
+  "optionalDependencies": {
     "@hono/node-server": "^1.13.7",
     "@hono/node-ws": "^1.0.4",
     "hono": "^4.6.14",
-    "node-pty": "1.2.0-beta.14",
-    "tsx": "^4.19.2"
+    "node-pty": "1.2.0-beta.14"
   },
   "devDependencies": {
     "@types/node": "^20.16.0",

package/spec-cli/bin/spex.mjs

@@ -65,17 +65,5 @@ if (args[0] === 'serve' || args[0] === 'dashboard') {
     .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 })
+spawn(process.execPath, [tsxCli, cli, ...args], { stdio: 'inherit', env })
   .on('exit', (code) => process.exit(code ?? 0))

package/spec-cli/hooks/compat/mark-active-0.5.2-eef1.fixture

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# @@@ mark-active - the SINGLE freshness hook, wired to BOTH UserPromptSubmit and PreToolUse. It branches
+# on ONE structured signal read straight from the hook payload (stdin JSON), so the state is HARD — never
+# text-sniffed from the TUI:
+#   the agent is pausing to ask the HUMAN (hp_is_ask) → status: asking, with the question text as the note
+#                                  (the deterministic capture of a question).
+#   any other tool, or a prompt submit → the agent is working → status: active (drop a now-stale proposal/note).
+# WHAT counts as "asking" is the [[harness-adapter]]'s call (Claude: the AskUserQuestion tool; Codex: the
+# request_user_input tool) — read via hp_is_ask, so this hook never names a harness tool.
+# Fires BEFORE the tool runs, so a `spex session done` declaration (itself a tool) lands AFTER this and wins;
+# the next real tool flips back to active, forcing a fresh Stop-gate declaration. Pure shell (no node/tsx) so
+# it stays cheap on every tool call — it value-replaces status/proposal/note in session.json with sed, never jq.
+# @@@ global store - state lives NOT in the worktree but in the per-session GLOBAL record session.json, keyed
+# by the harness session_id, grouped per-project (see hp_store_dir). GATED on `governed`: a user-self-launched
+# (non-governed) session has no board to feed, so this no-ops on it. cwd = the session worktree.
+. "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+payload=$(cat 2>/dev/null)
+# an IN-PROCESS SUBAGENT's tool call (Claude's Task tool) fires the parent's hooks with the PARENT's
+# session_id — flipping here let a supervising parent's own subagents erase its declared park/ask within
+# seconds and race the stop-gate into "undeclared stop" (issue #60). A subagent working is not the parent
+# agent ACTING, so its calls never touch the record; the parent's own next tool call still flips. The
+# discriminator is the payload's own top-level agent_id stamp (hp_is_subagent) — deterministic, never a
+# timing window.
+[ -n "$(hp_is_subagent "$payload")" ] && exit 0
+sid=$(hp_session_id "$payload"); [ -n "$sid" ] || exit 0
+sdir=$(hp_store_dir "$sid") || exit 0
+rec="$sdir/session.json"
+# board-lifecycle gate: only a GOVERNED (dashboard-launched) session has a board state to maintain.
+grep -q '"governed"[[:space:]]*:[[:space:]]*true' "$rec" 2>/dev/null || exit 0
+
+jget() { sed -n "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$rec" 2>/dev/null | head -1; }
+
+if [ -n "$(hp_is_ask "$payload")" ]; then
+  status=asking
+  note=$(hp_ask_note "$payload")   # first question's text → the note (best-effort)
+else
+  status=active
+  note=
+fi
+
+# cheap path: already active with nothing stale to clear → no-op (the common every-tool case).
+[ "$status" = active ] && [ "$(jget status)" = active ] && [ -z "$(jget proposal)" ] && [ -z "$(jget note)" ] && exit 0
+
+# value-replace status + clear proposal + (re)set note, in place. The record is written one-field-per-line
+# with these keys ALWAYS present (sessions.ts writeRecord), so each is a single value substitution — no key
+# add/remove, no JSON parser. Escape \ / & in the note for the sed REPLACEMENT (the note never contains ").
+note_esc=$(printf '%s' "$note" | sed 's/[\\/&]/\\&/g')
+tmp=$(mktemp) || exit 0
+sed -e "s/\(\"status\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"$status\"/" \
+    -e "s/\(\"proposal\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"\"/" \
+    -e "s/\(\"note\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"$note_esc\"/" \
+    "$rec" > "$tmp" && mv "$tmp" "$rec"
+exit 0

package/spec-cli/hooks/compat/mark-active-sed-v0.fixture

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# @@@ mark-active - the SINGLE freshness hook, wired to BOTH UserPromptSubmit and PreToolUse. It branches
+# on ONE structured signal read straight from the hook payload (stdin JSON), so the state is HARD — never
+# text-sniffed from the TUI:
+#   the agent is pausing to ask the HUMAN (hp_is_ask) → status: asking, with the question text as the note
+#                                  (the deterministic capture of a question).
+#   any other tool, or a prompt submit → the agent is working → status: active (drop a now-stale proposal/note).
+# WHAT counts as "asking" is the [[harness-adapter]]'s call (Claude: the AskUserQuestion tool; Codex: the
+# request_user_input tool) — read via hp_is_ask, so this hook never names a harness tool.
+# Fires BEFORE the tool runs, so a `spex session done` declaration (itself a tool) lands AFTER this and wins;
+# the next real tool flips back to active, forcing a fresh Stop-gate declaration. Pure shell (no node/tsx) so
+# it stays cheap on every tool call — it value-replaces status/proposal/note in session.json with sed, never jq.
+# @@@ global store - state lives NOT in the worktree but in the per-session GLOBAL record session.json, keyed
+# by the harness session_id, grouped per-project (see hp_store_dir). GATED on `governed`: a user-self-launched
+# (non-governed) session has no board to feed, so this no-ops on it. cwd = the session worktree.
+. "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+payload=$(cat 2>/dev/null)
+sid=$(hp_session_id "$payload"); [ -n "$sid" ] || exit 0
+sdir=$(hp_store_dir "$sid") || exit 0
+rec="$sdir/session.json"
+# board-lifecycle gate: only a GOVERNED (dashboard-launched) session has a board state to maintain.
+grep -q '"governed"[[:space:]]*:[[:space:]]*true' "$rec" 2>/dev/null || exit 0
+
+jget() { sed -n "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$rec" 2>/dev/null | head -1; }
+
+if [ -n "$(hp_is_ask "$payload")" ]; then
+  status=asking
+  note=$(hp_ask_note "$payload")   # first question's text → the note (best-effort)
+else
+  status=active
+  note=
+fi
+
+# cheap path: already active with nothing stale to clear → no-op (the common every-tool case).
+[ "$status" = active ] && [ "$(jget status)" = active ] && [ -z "$(jget proposal)" ] && [ -z "$(jget note)" ] && exit 0
+
+# value-replace status + clear proposal + (re)set note, in place. The record is written one-field-per-line
+# with these keys ALWAYS present (sessions.ts writeRecord), so each is a single value substitution — no key
+# add/remove, no JSON parser. Escape \ / & in the note for the sed REPLACEMENT (the note never contains ").
+note_esc=$(printf '%s' "$note" | sed 's/[\\/&]/\\&/g')
+tmp=$(mktemp) || exit 0
+sed -e "s/\(\"status\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"$status\"/" \
+    -e "s/\(\"proposal\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"\"/" \
+    -e "s/\(\"note\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"$note_esc\"/" \
+    "$rec" > "$tmp" && mv "$tmp" "$rec"
+exit 0

package/spec-cli/hooks/dispatch.sh

@@ -28,12 +28,14 @@ event="${1:?usage: dispatch.sh <harness> <Event>}"
 export SPEXCODE_HARNESS="$harness"
 # the harness.sh path (the adapter's shell mirror) — sibling of this script; hook handlers source it, and we
 # 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"
+hook_root="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+tool_root="$(cd "$hook_root/.." && pwd)"
+export SPEXCODE_HARNESS_LIB="$hook_root/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")
+  spex_cmd=("$tool_root/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),
@@ -67,30 +69,24 @@ 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
-ticket=""
-cleanup() {
-  [ -z "$ticket" ] || "${spex_cmd[@]}" internal maintenance-end "$ticket" "$$" >/dev/null 2>&1 || true
-  rm -f "$err"
-}
+cleanup() { 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
   [ "$ev" = "$event" ] || continue
-  out="$(printf '%s' "$input" | bash "$proj/$script" 2>"$err")"; code=$?
+  handler="$proj/$script"
+  # A seeded core hook is tracked project source, so package replacement cannot safely overwrite it. These
+  # byte-exact default revisions compose an ask note into JSON with sed; route only them to the package
+  # implementation. `cmp` makes a user-modified hook ineligible without a platform-specific hash utility.
+  if [ "$script" = '.spec/project/.plugins/core/mark-active/mark-active.sh' ] &&
+    { cmp -s "$handler" "$hook_root/compat/mark-active-sed-v0.fixture" ||
+      cmp -s "$handler" "$hook_root/compat/mark-active-0.5.2-eef1.fixture"; }; then
+    handler="$tool_root/templates/spec/project/.plugins/core/mark-active/mark-active.sh"
+  fi
+  out="$(printf '%s' "$input" | bash "$handler" 2>"$err")"; code=$?
   [ -n "$out" ] && printf '%s' "$out"
   if [ "$block" = "true" ] && { [ "$code" = "2" ] || printf '%s' "$out" | grep -q '"decision"[[:space:]]*:[[:space:]]*"block"'; }; then
     cat "$err" >&2

package/spec-cli/src/anchors.ts

@@ -382,6 +382,22 @@ export const extOf = (path: string): string => {
 
 // ---- anchor resolution (language-agnostic) ----
 export type AnchorResolution = { ok: Unit } | { dead: true } | { ambiguous: number }
+// @@@ ONE classification for "does this selector resolve here" - the gate (reading the candidate TIP) and the
+// freshness probe (reading the WORKING TREE) both have to answer it, and each used to branch on
+// dead/ambiguous itself. Two copies of a verdict rule drift, and these two already had: the gate warns on a
+// type-only unit, the probe never noticed one. The TEXT each reads stays its own business — a gate must judge
+// the tree it is gating, never a dirty worktree — but the VERDICT is decided once, here, so a new outcome
+// cannot reach one caller and silently miss the other.
+export type SelectorVerdict = { selector: string } & ({ ok: Unit } | { dead: true } | { ambiguous: number })
+export function resolveSelectors(units: Unit[], selectors: readonly string[]): SelectorVerdict[] {
+  return selectors.map((selector) => {
+    const r = resolveAnchor(units, selector)
+    if ('dead' in r) return { selector, dead: true as const }
+    if ('ambiguous' in r) return { selector, ambiguous: r.ambiguous }
+    return { selector, ok: r.ok }
+  })
+}
+
 export function resolveAnchor(units: Unit[], symbol: string): AnchorResolution {
   const hits = units.filter((u) => u.name === symbol)
   if (!hits.length) return { dead: true }
@@ -418,9 +434,10 @@ export function diffHunkRanges(patch: string, side: 'old' | 'new' = 'new'): [num
 type FileRevisionUnits = { units: Unit[] } | { absent: true } | { unparseable: string }
 const fileRevisionUnitMemo = new Map<string, FileRevisionUnits>()
 const MEMO_MAX = 4096
+const fileRevisionMemoKey = (objectFormat: string, oid: string, x: Extractor, path: string) => `${objectFormat}\0${oid}\0${x.memoKey(path)}`
 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 = `${objectFormat}\0${oid}\0${x.memoKey(path)}`
+  const key = fileRevisionMemoKey(objectFormat, oid, x, path)
   const hit = fileRevisionUnitMemo.get(key)
   if (hit) return hit
   if (text === undefined) throw new Error(`git cat-file --batch omitted object ${oid} for ${commit}:${path}`)
@@ -435,14 +452,50 @@ async function unitsAtFileRevision(commit: string, path: string, x: Extractor, o
 // 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[][] }
+// @@@ RANGE_SEMANTICS - hunk ranges must not depend on ambient Git state, because a range that moves with
+// config or attributes is neither a sound anchor verdict nor a reusable fact. Outside the commit, three
+// classes decide them: presentation (`.gitattributes` `-diff` prints `Binary files … differ` with no `@@` at
+// all — measured: one hunk bare, ZERO under `src/x.py -diff`, so an attribute edit silently disabled an
+// anchored contract's drift; a textconv or external driver replaces the text compared), the ALGORITHM and
+// its heuristics (`diff.algorithm`, `diff.indentHeuristic` — both repo config), and hunk COALESCING
+// (`diff.interHunkContext`). All are pinned here, on the two readers this node owns.
+//
+// The algorithm's VALUE is a product choice, not a formality, because the algorithms genuinely disagree:
+// on `c a c a` -> `c c a a a`, myers authors new lines 4-5 and deletes old line 2, while histogram authors
+// new lines 2-3 and deletes old line 3 — so a unit on line 3 is a HIT under histogram and a MISS under
+// myers, on one commit. histogram is pinned because it aligns the change with the unit that actually moved,
+// which for a BLOCKING gate is the conservative direction; myers (Git's default) would silently miss that
+// drift. So this pin is not merely determinism: it settles which reading a verdict means.
+// `--no-color` is not cosmetic here: under an ambient `color.ui=always` Git prefixes every `@@` with an
+// ANSI escape, so a `/^@@/` parse finds NO hunks and every anchored path reads as "nothing changed" — a
+// silent zero-drift verdict for the whole corpus, and one that would then be memoized. `-M -l0` pins rename
+// detection with no candidate limit, matching the identity stream this engine's events come from, so a large
+// rename set cannot quietly change which pairs are compared.
+const RANGE_SEMANTICS = [
+  '--text', '--no-textconv', '--no-ext-diff', '--no-color',
+  '--diff-algorithm=histogram', '--no-indent-heuristic', '--inter-hunk-context=0',
+  '-M', '-l0',
+] as const
 const hunkMemo = new Map<string, HunkRanges>()
-async function hunksAt(root: string, event: DriftPathEvent): Promise<HunkRanges> {
+// @@@ the reusable fact is a diff of ORDERED IMAGES, not of a commit id - a commit id is not immutable
+// interpretation: `refs/replace` can swap the object, and a graft or an unshallow can change its parents, so
+// one (commit,path) can name two different diffs inside one process. The inputs that actually decide the
+// hunks are the result image and each parent image, in order, each identified by its resolved blob oid and
+// historical path. Keying on those makes the key move exactly when an input does, and the oids are already
+// resolved by this read's one `cat-file --batch-check`, so completeness costs no extra child and no new state.
+const ABSENT_IMAGE = '-'
+const hunkMemoKey = (images: string[]) => images.join('\0')
+function rememberHunks(key: string, ranges: HunkRanges): HunkRanges {
+  if (hunkMemo.size >= MEMO_MAX) hunkMemo.clear()
+  hunkMemo.set(key, ranges)
+  return ranges
+}
+async function hunksAt(root: string, event: DriftPathEvent, key: string): 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 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,
+  const out = await gitRequiredA(['-C', root, '-c', 'core.quotePath=false', 'show', '--cc', '--combined-all-paths', '--unified=0', ...RANGE_SEMANTICS, '--format=', event.commit,
     ...(merge ? [] : ['--', ...paths])],
     `cannot derive anchor hunks for ${event.commit}:${event.historicalPath}`)
   let ranges: HunkRanges = { after: [], before: [[]] }
@@ -458,18 +511,35 @@ async function hunksAt(root: string, event: DriftPathEvent): Promise<HunkRanges>
       if (newCount > 0) ranges.after.push([newStart, newStart + newCount - 1])
     }
   }
-  if (hunkMemo.size >= MEMO_MAX) hunkMemo.clear()
-  hunkMemo.set(key, ranges)
-  return ranges
+  return rememberHunks(key, 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>> {
+// image paths, so they stay on hunksAt's exact event-shaped query. Commits ride argv here, so a build-wide
+// batch is split to stay clear of the kernel's exec argument limit; the records are order-independent.
+//
+// @@@ the demand set is the MISSES - a hunk is reusable by the identity of the IMAGES it diffed, never by the
+// commit id (see hunkMemoKey): under that identity, plus this seam's pinned interpretation, the fact cannot be
+// reinterpreted inside one process, so the batch may ask git only for what it has not read. Asking for the
+// whole window again is what made a repeated read cost the CORPUS instead of the movement: a re-lint after one
+// trunk commit or one dirty edit re-forked one `log --patch` per anchored path (22 here) to re-derive
+// byte-identical answers.
+const HUNK_COMMIT_CHUNK = 400
+async function hunksAtMany(root: string, path: string, entries: Map<string, string>): Promise<Map<string, HunkRanges>> {
   const result = new Map<string, HunkRanges>()
-  const ordinary = [...new Set(commits)]
+  const ordinary: string[] = []
+  for (const [commit, key] of entries) {
+    const hit = hunkMemo.get(key)
+    if (hit) result.set(commit, hit)
+    else ordinary.push(commit)
+  }
   if (!ordinary.length) return result
-  const out = await gitRequiredA(['-C', root, '-c', 'core.quotePath=false', 'log', '--no-walk', '--no-merges', '--patch', '--unified=0', '-M',
+  for (let cursor = 0; cursor < ordinary.length; cursor += HUNK_COMMIT_CHUNK)
+    await hunkRecordsInto(root, ordinary.slice(cursor, cursor + HUNK_COMMIT_CHUNK), path, entries, result)
+  return result
+}
+async function hunkRecordsInto(root: string, ordinary: string[], path: string, keys: Map<string, string>, result: Map<string, HunkRanges>): Promise<void> {
+  const out = await gitRequiredA(['-C', root, '-c', 'core.quotePath=false', 'log', '--no-walk', '--no-merges', '--patch', '--unified=0', ...RANGE_SEMANTICS,
     `--format=${RS}%H`, ...ordinary, '--', path], `cannot derive anchor hunks for ${path}`)
   for (const rec of out.split(RS)) {
     const normalized = rec.replace(/^\n/, '')
@@ -485,9 +555,9 @@ async function hunksAtMany(root: string, commits: string[], path: string): Promi
       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)
+    const key = keys.get(hash)
+    result.set(hash, key === undefined ? ranges : rememberHunks(key, ranges))
   }
-  return result
 }
 
 // the drift window of an anchored file: every commit to `path` not reachable from the spec's version
@@ -510,67 +580,126 @@ type AnchorRevision = { commit: string; path: string }
 const anchorRevisionKey = ({ commit, path }: AnchorRevision) => `${commit}\0${path}`
 
 // One lint can judge several selectors with overlapping windows. Their Git images and ordinary hunks are
-// immutable facts, so the batch owns them once and each query keeps its own selector verdict.
-export async function anchorHitQueries(root: string, queries: AnchorHitQuery[], regs: Extractor[]): Promise<AnchorHit[][]> {
+// reusable under the identity of those images, so the batch owns them once and each query keeps its own
+// selector verdict.
+async function runAnchorQueries(root: string, queries: AnchorHitQuery[], regs: Extractor[], stopAtFirstHit: boolean): Promise<AnchorHit[][]> {
   if (!queries.length) return []
   const objectFormat = gitObjectFormat(root)
   const revisions = new Map<string, AnchorRevision>()
-  const ordinaryByPath = new Map<string, Set<string>>()
+  const ordinaryEvents: { path: string; commit: string; event: DriftPathEvent }[] = []
   for (const { win } of queries) 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(anchorRevisionKey(ref), ref)
     if (event.parents.length > 1 || event.parents.some((parent) => parent.historicalPath !== event.historicalPath)) continue
-    const commits = ordinaryByPath.get(event.historicalPath) ?? new Set<string>()
-    commits.add(event.commit)
-    ordinaryByPath.set(event.historicalPath, commits)
+    ordinaryEvents.push({ path: event.historicalPath, commit: event.commit, event })
   }
   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 oids = await batchRevisionOids(root, refs.map(({ commit, path }) => `${commit}:${path}`))
+  // Every image this read will diff is now resolved, so the reusable hunk fact can be named by the identity
+  // that actually decides it: the result image and each parent image, in order, oid + historical path.
+  const oidByRef = new Map<string, string | null>()
+  for (let index = 0; index < refs.length; index++) oidByRef.set(anchorRevisionKey(refs[index]), oids[index])
+  const imageOf = (commit: string, path: string) => `${oidByRef.get(anchorRevisionKey({ commit, path })) ?? ABSENT_IMAGE}:${path}`
+  const imageIdentity = (event: DriftPathEvent) => hunkMemoKey([
+    imageOf(event.commit, event.historicalPath),
+    ...event.parents.map(({ commit, historicalPath }) => imageOf(commit, historicalPath)),
+  ])
+  const ordinaryByPath = new Map<string, Map<string, string>>()
+  for (const { path, commit, event } of ordinaryEvents) {
+    const entries = ordinaryByPath.get(path) ?? new Map<string, string>()
+    entries.set(commit, imageIdentity(event))
+    ordinaryByPath.set(path, entries)
+  }
+  const ordinaryHunks = new Map<string, Map<string, HunkRanges>>()
+  for (const [path, entries] of ordinaryByPath) ordinaryHunks.set(path, await hunksAtMany(root, path, entries))
+  // The image's own memo answers before any bytes move, so the read asks git only for the revisions this
+  // process has not parsed yet — the retention half of the same rule the hunk demand set follows.
   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(anchorRevisionKey(ref), { unparseable: !x ? `no designated extractor for ${ref.path}` : String(ready) })
-      continue
+  const primeUnits = async (keys: Set<string>): Promise<void> => {
+    const pending: { key: string; ref: AnchorRevision; oid: string; x: Extractor }[] = []
+    const wanted = new Set<string>()
+    for (const key of keys) {
+      if (units.has(key)) continue
+      const ref = revisions.get(key)!, oid = oidByRef.get(key) ?? null
+      const x = extractorFor(regs, extOf(ref.path))
+      const ready = x?.ready()
+      if (!x || ready !== true) {
+        units.set(key, { unparseable: !x ? `no designated extractor for ${ref.path}` : String(ready) })
+        continue
+      }
+      if (!oid) { units.set(key, { absent: true }); continue }
+      const hit = fileRevisionUnitMemo.get(fileRevisionMemoKey(objectFormat, oid, x, ref.path))
+      if (hit) { units.set(key, hit); continue }
+      pending.push({ key, ref, oid, x }); wanted.add(oid)
     }
-    units.set(anchorRevisionKey(ref), await unitsAtFileRevision(ref.commit, ref.path, x, objectFormat, oid, oid ? blobs.get(oid) : undefined))
+    if (!pending.length) return
+    const blobs = await batchBlobTexts(root, [...wanted])
+    for (const { key, ref, oid, x } of pending)
+      units.set(key, await unitsAtFileRevision(ref.commit, ref.path, x, objectFormat, oid, blobs.get(oid)))
   }
-  const ordinaryHunks = new Map<string, Map<string, HunkRanges>>()
-  for (const [path, commits] of ordinaryByPath) 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))
-  const results: AnchorHit[][] = []
-  for (const { win, symbols } of queries) {
-    const hits = new Map<string, { selectors: Set<string>; unparseable?: string }>()
-    for (const event of win) {
-      const after = units.get(anchorRevisionKey({ commit: event.commit, path: event.historicalPath }))!
-      const before = event.parents.map(({ commit, historicalPath }) => units.get(anchorRevisionKey({ 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)
+  // @@@ the scan advances in DOUBLING corpus-wide rounds - an existence read may stop at its window's first
+  // hit, but which event that is cannot be known before the images are parsed, so the demand set has to be
+  // discovered rather than declared. Each round still asks the WHOLE unsettled corpus at once (never one
+  // reading at a time, which is what would re-fork the batch per unit), and doubling bounds the rounds by hit
+  // DEPTH, not by how many readings are asked. An enumeration read takes its whole remaining window in one
+  // slice, so it keeps the single-round shape it has always had.
+  const runs = queries.map(() => ({ hits: new Map<string, { selectors: Set<string>; unparseable?: string }>(), cursor: 0, settled: false }))
+  for (let chunk = 1; ; chunk *= 2) {
+    const slices: { run: typeof runs[number]; symbols: string[]; events: DriftPathEvent[] }[] = []
+    for (let index = 0; index < queries.length; index++) {
+      const run = runs[index], { win, symbols } = queries[index]
+      if (run.settled || run.cursor >= win.length) continue
+      slices.push({ run, symbols, events: win.slice(run.cursor, run.cursor + (stopAtFirstHit ? chunk : win.length - run.cursor)) })
+    }
+    if (!slices.length) break
+    const keys = new Set<string>()
+    for (const { events } of slices) for (const event of events) {
+      keys.add(anchorRevisionKey({ commit: event.commit, path: event.historicalPath }))
+      for (const parent of event.parents) keys.add(anchorRevisionKey({ commit: parent.commit, path: parent.historicalPath }))
+    }
+    await primeUnits(keys)
+    for (const { run, symbols, events } of slices) {
+      for (const event of events) {
+        run.cursor++
+        const after = units.get(anchorRevisionKey({ commit: event.commit, path: event.historicalPath }))!
+        const before = event.parents.map(({ commit, historicalPath }) => units.get(anchorRevisionKey({ commit, path: historicalPath }))!)
+        const ranges = ordinaryHunks.get(event.historicalPath)?.get(event.commit)
+          ?? await hunksAt(root, event, imageIdentity(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 = run.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) run.hits.set(event.commit, hit)
+        if (stopAtFirstHit && run.hits.size) { run.settled = true; break }
       }
-      if (hit.selectors.size) hits.set(event.commit, hit)
     }
-    results.push([...hits].map(([commit, hit]) => ({ commit, selectors: [...hit.selectors], ...(hit.unparseable ? { unparseable: hit.unparseable } : {}) })))
   }
-  return results
+  return runs.map((run) => [...run.hits].map(([commit, hit]) => ({ commit, selectors: [...hit.selectors], ...(hit.unparseable ? { unparseable: hit.unparseable } : {}) })))
+}
+
+// The two consumers ask DIFFERENT questions of this engine, so they enter through different doors rather
+// than through one call with a mode flag. Enumeration must scan every window event because its answer IS the
+// per-commit, per-selector list; existence is discharged by the first hit, and scanning past it computes rows
+// nobody reads.
+export async function anchorHitQueries(root: string, queries: AnchorHitQuery[], regs: Extractor[]): Promise<AnchorHit[][]> {
+  return runAnchorQueries(root, queries, regs, false)
+}
+export async function anchorHitExists(root: string, queries: AnchorHitQuery[], regs: Extractor[]): Promise<boolean[]> {
+  return (await runAnchorQueries(root, queries, regs, true)).map((hits) => hits.length > 0)
 }
 export async function anchorHitCommits(root: string, win: DriftPathEvent[], symbols: string[], regs: Extractor[]): Promise<AnchorHit[]> {
   return (await anchorHitQueries(root, [{ win, symbols }], regs))[0]

package/spec-cli/src/attach.ts

@@ -1,14 +1,6 @@
-// @@@ session attach - the HUMAN escape hatch into a worker: every session is just a tmux session on the
-// backend's private socket, and the most direct way to see or rescue one is to sit in it. This verb is the
-// sanctioned foreground `tmux attach` — no programmatic exception-handling ambition, the user fixes it by
-// being there. It is deliberately the ONE session verb that does NOT route through the backend
-// ([[remote-client]]'s exception): a terminal cannot be brokered over HTTP, and attaching a tmux CLIENT to
-// the same server is tmux's native multi-client support, not a second actor on the socket. That makes it
-// LOCAL-only by nature — the guards below fail loud (never degrade) when the premise doesn't hold.
 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)'
 
@@ -40,14 +32,12 @@ export async function attachSession(id: string): Promise<number> {
 An agent must not run it inside a turn (it freezes you); ${AGENT_ALTERNATIVES}.`)
     process.exit(2)
   }
-  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.
+  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}\`.`)
-      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
-  })
+    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
 }