spexcode 0.6.0 → 0.6.1

package/spec-cli/src/git.ts

@@ -1,7 +1,7 @@
 import { execFileSync, execFile, spawn } from 'node:child_process'
 import { AsyncLocalStorage } from 'node:async_hooks'
-import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, mkdirSync, rmSync, renameSync, openSync, closeSync } from 'node:fs'
-import { join, isAbsolute, resolve } from 'node:path'
+import { readFileSync, readdirSync, statSync, existsSync, writeFileSync, mkdirSync, rmSync, renameSync, openSync, closeSync, accessSync, constants } from 'node:fs'
+import { join, isAbsolute, resolve, delimiter } from 'node:path'
 import { createHash, randomBytes } from 'node:crypto'
 import { projectRuntimeRoot } from './project-store.js'
 import { rootSlots, touchRoot as touchRootLru } from './root-lru.js'
@@ -15,6 +15,24 @@ const US = '\x1f', RS = '\x1e'
 // than materializing one process per worktree/eval. Calls outside that build context remain unconstrained.
 const GIT_TIMEOUT_MS = Number(process.env.SPEXCODE_GIT_TIMEOUT_MS || 120000)
 export const BOARD_GIT_CONCURRENCY = 4
+const gitByPath = new Map<string, string>()
+
+export function gitBinary(env: NodeJS.ProcessEnv = process.env): string {
+  const path = env.PATH || ''
+  const known = gitByPath.get(path)
+  if (known) {
+    try { accessSync(known, constants.X_OK); return known } catch {}
+  }
+  for (const dir of path.split(delimiter)) {
+    const candidate = resolve(dir || '.', 'git')
+    try {
+      accessSync(candidate, constants.X_OK)
+      gitByPath.set(path, candidate)
+      return candidate
+    } catch {}
+  }
+  throw new Error('git executable not found on PATH')
+}
 type GitPermitPool = { acquire: (signal: AbortSignal) => Promise<() => void> }
 type GitBuildContext = { signal: AbortSignal; permits: GitPermitPool }
 const gitBuild = new AsyncLocalStorage<GitBuildContext>()
@@ -115,7 +133,7 @@ export function git(args: string[]): string {
   const env = { ...process.env }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
   try {
-    return execFileSync('git', withBuildLimits(args), { encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'], timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL' })
+    return execFileSync(gitBinary(env), withBuildLimits(args), { encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'], timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL' })
   } catch (e: any) { warnIfTimedOut(e, args); throw e }
 }
 
@@ -123,7 +141,7 @@ function gitBuffer(args: string[], input?: string): Buffer {
   const env = { ...process.env }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
   try {
-    return execFileSync('git', withBuildLimits(args), {
+    return execFileSync(gitBinary(env), withBuildLimits(args), {
       input,
       env,
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -267,7 +285,7 @@ const GIT_MAX_BUFFER = 1 << 24
 function execGit(args: string[], env: NodeJS.ProcessEnv, signal?: AbortSignal, maxBuffer = GIT_MAX_BUFFER, input?: string): Promise<GitExec> {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) { reject(gitAbortError()); return }
-    const child = spawn('git', args, { env, detached: true, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] })
+    const child = spawn(gitBinary(env), args, { env, detached: true, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] })
     const stdout: Buffer[] = [], stderr: Buffer[] = []
     let stdoutBytes = 0, stderrBytes = 0, aborted = false, timedOut = false, overflow = false
     let spawnError: Error | null = null
@@ -338,7 +356,7 @@ async function execGitForCaller(args: string[], env: NodeJS.ProcessEnv, maxBuffe
 function execGitStream(args: string[], env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<GitExec> {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) { reject(gitAbortError()); return }
-    const child = spawn('git', args, { env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] })
+    const child = spawn(gitBinary(env), args, { env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] })
     const stdout: Buffer[] = [], stderr: Buffer[] = []
     let settled = false, aborted = false, timedOut = false
     const killTree = () => {
@@ -826,8 +844,12 @@ async function identityRawEventStream(root: string, tip: string, request: EventS
   return value as IdentityRawRecord[]
 }
 export type GitTryFailure = 'exit' | 'spawn' | 'timeout'
-export async function gitTry(args: string[], options: { indexFile?: string } = {}): Promise<{ ok: boolean; stdout: string; stderr: string; failure?: GitTryFailure }> {
+export async function gitTry(args: string[], options: { indexFile?: string; extraEnv?: Record<string, string | undefined> } = {}): Promise<{ ok: boolean; stdout: string; stderr: string; failure?: GitTryFailure }> {
   const env = { ...process.env }
+  for (const [key, value] of Object.entries(options.extraEnv ?? {})) {
+    if (value === undefined) delete env[key]
+    else env[key] = value
+  }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
   if (options.indexFile) env.GIT_INDEX_FILE = options.indexFile
   const context = inheritedContext()
@@ -2091,7 +2113,7 @@ export function mergeConflicts(wtPath: string, mainRef = 'main'): Promise<boolea
   return new Promise((resolve) => {
     const env = { ...process.env }
     delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
-    execFile('git', ['-C', wtPath, 'merge-tree', '--write-tree', '--no-messages', mainRef, 'HEAD'],
+    execFile(gitBinary(env), ['-C', wtPath, 'merge-tree', '--write-tree', '--no-messages', mainRef, 'HEAD'],
       { encoding: 'utf8', env, maxBuffer: 1 << 24 },
       // execFile sets err.code to the numeric EXIT code on a non-zero exit (1 = conflicts), or a string
       // errno (e.g. 'ENOENT') if git can't be spawned — only the exit-1 case is a real conflict verdict.

package/spec-cli/src/graphStream.ts

@@ -1,9 +1,9 @@
 import { streamSSE } from 'hono/streaming'
 import type { Context } from 'hono'
 import { watch, mkdirSync, readdirSync, readFileSync, type FSWatcher } from 'node:fs'
-import { join, dirname, relative, resolve } from 'node:path'
-import { sessionsRoot, gitCommonDir } from './layout.js'
-import { hotSignature, warmSignature, listSessions } from './sessions.js'
+import { join, dirname, relative, resolve, basename } from 'node:path'
+import { sessionsRoot, gitCommonDir, sessionBranchIndex, mainBranch } from './layout.js'
+import { hotSignature, warmSignature, listSessions, pendingSessionCreateWorktreePaths } from './sessions.js'
 import { getBoard, getBoardForSessionRefresh, invalidateBoard, patrolBoard } from './graphCache.js'
 import { unitize, tagOf, diffUnits, type Units } from './graphDelta.js'
 import {
@@ -217,6 +217,16 @@ export const addPendingGraphChange = (pending: PendingGraphChanges, scope: Scope
   sessions: pending.sessions || scope === 'sessions',
 })
 
+// Git creates the registry entry before the session transaction publishes its durable record. A registry
+// event for that private candidate must not start a full board build while the `git worktree add` child is
+// still running; the create route flushes the deferred event after publication (or cleanup).
+export function isSessionCreateCandidateRegistryEvent(relativePath: string, candidatePaths: Iterable<string>): boolean {
+  const entry = relativePath.split(/[\\/]+/).filter(Boolean)[0] ?? ''
+  if (!entry) return false
+  for (const path of candidatePaths) if (basename(resolve(path)) === entry) return true
+  return false
+}
+
 // under SPEXCODE_BOARD_DEBUG=1, every broadcast logs its changed unit keys + trigger tags + build ms.
 const DEBUG = process.env.SPEXCODE_BOARD_DEBUG === '1'
 function traceLatency(stage: 'sessions-signal' | 'session-projection-complete' | 'broadcast', detail: Record<string, unknown> = {}): void {
@@ -466,7 +476,7 @@ function ensureWatcher(root: string): void {
     root,
     source: 'store',
     scope: 'sessions',
-    onInput: () => fireChanged('sessions'),
+    onInput: () => { dropBranchIndex(); fireChanged('sessions') },   // a created/renamed session may own a new branch
     onFailure: (error) => {
       if (storeWatcher === registry) storeWatcher = null
       noteSourceFailure('store', error)
@@ -492,9 +502,34 @@ type RegistryGroup = {
 let refsWatchers: RegistryGroup | null = null
 const REFS_OBSERVER = 'graph:refs'
 
+// @@@ the moved ref NAMES its scope - the watcher has always known which ref moved and threw it away, so
+// every ref movement anywhere invalidated every session's evaluation. On a host carrying dozens of branches
+// and a bot that commits continuously that means nothing is ever warm: observed on z-code as an input
+// generation of 1208 against a last-known 254. A session's fingerprint reads exactly three refs — its own
+// tip, the base tip, and their merge-base — so a ref that is neither cannot move it. `packed-refs` and
+// `HEAD` stay broad on purpose: a packed update rewrites many refs behind ONE event, so it names nothing.
+// the index is read from the session store, so it is only ever stale when that store moved — and the store
+// has its own watcher, which drops it. A ref burst therefore costs one map lookup, not 76 record reads.
+let branchIndexMemo: Map<string, string> | null = null
+function branchIndex(): Map<string, string> {
+  return (branchIndexMemo ??= sessionBranchIndex())
+}
+function dropBranchIndex(): void { branchIndexMemo = null }
+
+export function evalTargetForRef(ref: string | undefined, base: string, branches: Map<string, string>): EvalTarget | undefined {
+  if (ref === undefined) return 'all'          // an unnamed movement must assume the worst
+  const rel = ref.replace(/\\/g, '/')
+  if (!rel.startsWith('heads/')) return undefined   // tags and remotes feed no session fingerprint
+  const branch = rel.slice('heads/'.length)
+  if (!branch) return 'all'
+  if (branch === base) return 'all'            // every merge-base may have moved
+  const id = branches.get(branch)
+  return id ? { id } : undefined               // a branch no session owns moves no session's evaluation
+}
+
 export function watchSessionEvalRefs(
   common: string,
-  onInput: () => void,
+  onInput: (ref?: string) => void,
   onFailure: (error: Error) => void,
 ): RegistryGroup {
   let attached: TreeWatcherRegistry[] = []
@@ -517,7 +552,7 @@ export function watchSessionEvalRefs(
     root: join(common, 'refs'),
     source: 'refs',
     scope: 'full',
-    onInput: () => onInput(),
+    onInput: (_event, rel) => onInput(rel),
     onFailure: fail,
   })
   attached.push(refs)
@@ -528,7 +563,7 @@ export function watchSessionEvalRefs(
     source: 'refs-common',
     scope: 'full',
     recursive: false,
-    onInput: (_event, file) => { if (file === 'packed-refs' || file === 'HEAD') onInput() },
+    onInput: (_event, file) => { if (file === 'packed-refs' || file === 'HEAD') onInput() },   // names nothing -> 'all'
     onFailure: fail,
   })
   attached.push(commonFiles)
@@ -553,7 +588,7 @@ function ensureRefsWatcher(common = activeCommonRoot): void {
   }
   if (!mayAttach('refs')) return
   try {
-    refsWatchers = watchSessionEvalRefs(common, () => fireChanged('full', 'all'), refsWatcherFailed)
+    refsWatchers = watchSessionEvalRefs(common, (ref) => fireChanged('full', evalTargetForRef(ref, mainBranch(), branchIndex())), refsWatcherFailed)
     noteSourceHealthy('refs')
     if (releaseSessionEvalProjectionObserver(REFS_OBSERVER)) fireChanged('full')
   } catch (error) {
@@ -745,10 +780,37 @@ function reconcileWorktrees(forceSessionId?: string): Promise<void> {
   return flight
 }
 const WORKTREE_REGISTRY_OBSERVER = 'graph:worktree-registry'
+let deferredRegistryChange = false
+let deferredRegistryTimer: ReturnType<typeof setTimeout> | null = null
+
+function flushDeferredRegistryChange(): void {
+  if (!deferredRegistryChange) return
+  deferredRegistryChange = false
+  if (deferredRegistryTimer) { clearTimeout(deferredRegistryTimer); deferredRegistryTimer = null }
+  void reconcileWorktrees()
+  fireChanged('full', 'all')
+}
+
+// A crashed or disconnected create request must not leave the registry event deferred forever. The normal
+// route flush is immediate; this bounded fallback preserves the watcher contract if the process never reaches
+// its response boundary.
+function deferRegistryChange(): void {
+  deferredRegistryChange = true
+  if (deferredRegistryTimer) return
+  deferredRegistryTimer = setTimeout(() => {
+    deferredRegistryTimer = null
+    flushDeferredRegistryChange()
+  }, 10_000)
+  deferredRegistryTimer.unref?.()
+}
+
+export function flushDeferredWorktreeRegistryChange(): void {
+  flushDeferredRegistryChange()
+}
 
 export function watchSessionEvalRegistry(
   dir: string,
-  onInput: () => void,
+  onInput: (event: 'rename' | 'change', relativePath: string) => void,
   onFailure: (error: Error) => void,
 ): TreeWatcherRegistry {
   let ready = false
@@ -758,7 +820,7 @@ export function watchSessionEvalRegistry(
     source: 'worktree-registry',
     scope: 'full',
     recursive: false,
-    onInput: () => onInput(),
+    onInput: (_event, relativePath) => onInput(_event, relativePath),
     onFailure: (error) => {
       if (ready) onFailure(error)
       else attachError = error
@@ -807,7 +869,11 @@ async function ensureWorktreeRegistry(forceSessionId?: string): Promise<void> {
     catch (error) { console.error(`spec-cli: graph watcher 'worktree-registry' could not create ${dir}: ${error instanceof Error ? error.message : String(error)}`) }
     // a registry add/remove is itself a 'full' change (a new/gone worktree reshapes the overlay); also
     // reconcile the per-worktree `.spec` watchers on every registry event.
-    registryWatcher = watchSessionEvalRegistry(dir, () => {
+    registryWatcher = watchSessionEvalRegistry(dir, (_event, relativePath) => {
+      if (isSessionCreateCandidateRegistryEvent(relativePath, pendingSessionCreateWorktreePaths())) {
+        deferRegistryChange()
+        return
+      }
       void reconcileWorktrees()
       fireChanged('full', 'all')
     }, registryWatcherFailed)
@@ -841,6 +907,8 @@ export async function ensureBoardFileWatchers(forceSessionId?: string): Promise<
 export function closeBoardFileWatchers(): void {
   watcherEra++
   if (repairTimer) { clearTimeout(repairTimer); repairTimer = null }
+  if (deferredRegistryTimer) { clearTimeout(deferredRegistryTimer); deferredRegistryTimer = null }
+  deferredRegistryChange = false
   heldSources.clear()
   repairStep = 0
   repairing = false

package/spec-cli/src/harness.ts

@@ -18,6 +18,7 @@ import { git } from './git.js'
 import { shQuote } from './sh.js'
 import { detachedRuntimeGenerationToken, migrateLegacyDetachedRuntimeReceipt, processStartToken, verifyDetachedRuntime, type VerifiedDetachedRuntime } from './process-identity.js'
 import { codexGenerationEndpoints, codexGenerationSocketPath, currentCodexGeneration, legacyCodexGenerationEndpoint, readCodexGenerationLedger, resolveCodexGenerationForSession, type CodexGenerationEndpoint } from './codex-runtime-generations.js'
+import { writeFileIfChanged } from './file-write.js'
 
 // @@@ harness-adapter - the ONE seam between SpexCode and the coding-agent harness (Claude Code, Codex, …).
 // Every harness-specific fact lives behind THIS interface with one implementation per harness; product code
@@ -702,10 +703,12 @@ export function codexLaunchCommand(id: string, codexCmd = 'codex', serverCmd?: s
     // thread/start bypass, so the worktree's hooks stay untrusted and NO lifecycle hooks fire.
     `export SPEXCODE_CODEX_CMD=${shQuote(codexCmd)}`,
     // The runtime command is the single generation-ledger boundary. A new turn receives canonical `current`;
-    // resume resolves its existing session/thread binding and therefore cannot jump an old conversation to a
-    // replacement root. It prints only shell assignments for the exact proven endpoint.
+    // resume resolves its existing session/thread binding, so a LIVE root never has its conversation moved to a
+    // replacement. Both spellings carry the server command because either may be the launch that has to start a
+    // root: after a host restart the bound generation is a corpse, and resume rebuilds one to load the same
+    // on-disk rollout. It prints only shell assignments for the exact proven endpoint.
     'if [ "$1" = "--resume" ]; then',
-    `  eval "$( ${SPEX} internal codex-generation-session "$dir" "$SPEXCODE_SESSION_ID" "$2" )" || exit 1`,
+    `  eval "$( ${SPEX} internal codex-generation-session "$dir" "$SPEXCODE_SESSION_ID" "$2" ${shQuote(server)} )" || exit 1`,
     'else',
     `  eval "$( ${SPEX} internal codex-generation-current "$dir" ${shQuote(server)} )" || exit 1`,
     'fi',
@@ -1797,17 +1800,16 @@ async function deliverViaCodexAppServer(rec: HarnessDeliveryRecord, text: string
 // idempotent replace of the content between sentinels; the user's own content above/below is preserved. The
 // comment STYLE is a parameter so ONE primitive serves every managed file — HTML for the md contracts
 // (CLAUDE.md/AGENTS.md), `#` for .gitignore — instead of a per-file-type writer. Default = HTML (the md case).
-export function writeManagedBlock(file: string, body: string, comment: readonly [string, string] = ['<!-- ', ' -->']): void {
+export function writeManagedBlock(file: string, body: string, comment: readonly [string, string] = ['<!-- ', ' -->']): boolean {
   const [open, close] = comment
   const START = `${open}spexcode:start${close}`
   const END = `${open}spexcode:end${close}`
   const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
   const block = `${START}\n${body}\n${END}`
-  let cur = existsSync(file) ? readFileSync(file, 'utf8') : ''
+  const cur = existsSync(file) ? readFileSync(file, 'utf8') : ''
   const re = new RegExp(`${esc(START)}[\\s\\S]*?${esc(END)}`)
-  if (re.test(cur)) cur = cur.replace(re, block)
-  else cur = cur.trim() ? `${cur.replace(/\n*$/, '')}\n\n${block}\n` : `${block}\n`
-  writeFileSync(file, cur)
+  const next = re.test(cur) ? cur.replace(re, block) : cur.trim() ? `${cur.replace(/\n*$/, '')}\n\n${block}\n` : `${block}\n`
+  return writeFileIfChanged(file, next)
 }
 
 // the INVERSE of writeManagedBlock: strip the spexcode sentinel block (with the blank space around it),
@@ -1916,7 +1918,7 @@ export function writeCodexTrust(proj: string, events: readonly string[], cmdFor:
   const blk = `# spexcode:trust:${proj} (managed — do not edit)\n${lines.join('\n')}\n# spexcode:trust:end:${proj}`
   const cleaned = stripCodexTrustFor(existsSync(file) ? readFileSync(file, 'utf8') : '', proj, hooksJson)
   if (!existsSync(home)) mkdirSync(home, { recursive: true })
-  writeFileSync(file, cleaned ? `${cleaned}\n\n${blk}\n` : `${blk}\n`)
+  writeFileIfChanged(file, cleaned ? `${cleaned}\n\n${blk}\n` : `${blk}\n`)
   return file
 }
 

package/spec-cli/src/help.ts

@@ -44,8 +44,8 @@ session to that node. --prompt-file <path>|- carries a long prompt without shell
     ls: ['spex session ls [SEL…] [--status a,b] [--all] [--json]',
       'One-shot table of living sessions. Shelved sessions ([[archive]]) are hidden; --all includes them, and naming one explicitly always shows it.', ['selector']],
     resources: ['spex session resources [--json]', 'Read-only host/process ownership, budgets, shared refs, and findings.'],
-    watch: ['spex session watch [SEL…] [--as NAME] [--idle] [--interval N=1]',
-      'Streams lifecycle transitions and blocks until killed; `session wait` is the one-shot alternative.', ['selector']],
+    watch: [['spex session watch <SEL…>', 'spex session watch list', 'spex session watch cancel <SEL…>', 'spex session watch stream [SEL…] [--as NAME] [--idle] [--interval N=1]'],
+      'With a governed caller, watch registers durable send-backed state delivery and exits. list/cancel manage those relations. Without a governed caller it names the background `session wait` fallback. stream is the human-only continuous log view and blocks until killed.', ['selector']],
     wait: ['spex session wait [SEL…] [--timeout S=1200] [--interval S=1] [--idle]',
       `EDGE-TRIGGERED wait: follows the selected sessions' logs AND your own log, and exits 0 on
 the FIRST thing worth waking for — a followed session TRANSITIONING from a non-actionable
@@ -79,7 +79,7 @@ you are running in, mid-turn. Your own ending is a declaration: \`done --propose
     done: ['spex session done --propose merge|nothing|close [--note T]',
       '`merge` declares review: committed work ready for human review, and it is the ONLY declaration that offers a clickable merge. `nothing` declares done: committed work, but no merge proposal. `close` declares close-pending: PROPOSE discarding this worktree — the human closes it. This declaration is how a session ends itself; never run `session close` on your own id.'],
     park: ['spex session park --note <what-you-await>',
-      'Declare parked only when a real background task will wake your own session. It self-resumes; waiting for a human is asking, not parked.'],
+      'Declare parked only when a managed watch delivery or real background task will wake your own session. It self-resumes; waiting for a human is asking, not parked.'],
     ask: ['spex session ask --note <your-question>',
       'Declare asking when the session needs a human reply or direction. It resumes only when the human replies; a background wake-up is parked instead.'],
     attach: ['spex session attach <SEL>', `Attaches the current terminal to the worker's tmux (detach: C-b d) and blocks until detached.
@@ -273,7 +273,7 @@ edit the spec instead — same commit as the code.`,
     see: 'spex eval ls --session <SEL> (the session’s measured loss) · spex help eval',
   },
   eval: {
-    line: 'eval <verb>           the measurement system: add · ls · scenario ls/write · matrix · lint · ok · retract · clean',
+    line: 'eval <verb>           the measurement system: add · ls · scenario ls/write · lint · ok · retract · clean',
     body: `Usage: spex eval add [<node>|.] [--scenario <name>] (--pass|--fail) [--note <text>]
                     [--image <png> …repeatable] [--result <path|->] [--video <webm|mp4>] [--timeline <json>]
        spex eval ls [<node>|.] [--json]                a node's eval timeline, newest first
@@ -281,7 +281,6 @@ edit the spec instead — same commit as the code.`,
        spex eval ls --session <SEL> --export [--open | --out <path>]
        spex eval scenario ls [<node>|.] [--unmeasured] [--json]   declared scenarios; JSON = canonical index
        spex eval scenario write --mutation <json> < eval.md       propose one canonical metadata mutation
-       spex eval matrix <launcher> [--node <id>] [--rows k1,k2]   the harness live-behavior matrix
        spex eval lint [--changed]                      measurement-layer findings (advisory, always exit 0)
        spex eval ok <node> [--scenario <name>]         the HUMAN sign-off on the scenario's latest measurement
        spex eval retract [<node>|.] [--scenario <name>] [--last | --ts <iso>] [--note <why>]
@@ -305,12 +304,6 @@ scenario write — the fixed-tree declaration writer for an external measurement
 eval.md, --mutation is one closed JSON insert/delete request for one scenario's test metadata, and stdout is only
 the proposed eval.md bytes. It reads no worktree or runner and fails without stdout on malformed or ambiguous input.
 
-matrix — run the eight-row harness live-behavior matrix against a REAL dispatched session of the named
-launcher (the harness-adapter acceptance rule, defined once in spec-eval/src/matrix.ts): it syncs the
-rows into the \`<harness>-harness\` node's eval.md scenarios, drives one worker through undeclared-stop ·
-pretooluse-block · ask-note · deliver-steer · resume · liveness · commit-gate · close-residue, and files
-a per-row measurement with its evidence transcript. A new harness needs only its launcher + spec node.
-
 lint — the measurement layer's findings: malformed eval.md (eval-schema) · unmeasured (eval-missing) ·
 stale (eval-drift) · orphaned remark tracks (eval-dangling) · governed source with no eval.md
 (eval-coverage — the same name and shape as spec lint's coverage, one rule per layer) · over-owned
@@ -439,10 +432,12 @@ export function commandHelp(name: string, verb?: string): string | null {
   return `${header}${e.body}${e.see ? `\n\nsee also: ${e.see}` : ''}\n\nmap: spex help · skills: spex guide`
 }
 
-export function sessionLaunchReceipt(id: string): string {
+export function sessionLaunchReceipt(id: string, managedWatch = false): string {
   return `spex: launched session ${id}
   current result: the session JSON is on stdout now; \`spex session ls ${id}\` is the later one-shot snapshot
-  next lifecycle change: background \`spex session wait ${id}\` (edge-triggered; exits on the next non-actionable→actionable transition); \`spex session watch ${id}\` streams and NEVER EXITS
+  next lifecycle change: ${managedWatch
+    ? `managed watch registered — this parent receives ${id}'s state changes through its normal send queue; \`spex session watch cancel ${id}\` ends it`
+    : `background \`spex session wait ${id}\` (edge-triggered; exits on the next non-actionable→actionable transition); \`spex session watch ${id}\` registers send-backed delivery when the caller is governed`}; \`spex session watch stream ${id}\` NEVER EXITS
   response channel: \`spex session send ${id} "<msg>"\`; \`send --keys\` is an UNSTABLE LAST RESORT after a plain send cannot land`
 }
 

package/spec-cli/src/index.ts

@@ -15,7 +15,7 @@ import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { summarizeLoopIn } from './mentions.js'
 import { resolveLayout, mainBranch } from './layout.js'
 import { getBoardJson } from './graphCache.js'
-import { boardStream, closeBoardFileWatchers, ensureBoardFileWatchers, notifyBoardChanged } from './graphStream.js'
+import { boardStream, closeBoardFileWatchers, ensureBoardFileWatchers, notifyBoardChanged, flushDeferredWorktreeRegistryChange } from './graphStream.js'
 import { gitA, gitTry, repoRoot } from './git.js'
 import { cockpitReview } from './cockpit.js'
 import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, quarantineCorruptRecord, restoreQuarantinedRecord, archiveSession, resumeSession, mergeSession, captureSessionResult, sessionPrompt, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, superviseTurnFailures, superviseDelivery, SessionRecordUnusable, TMUX_SOCK } from './sessions.js'
@@ -455,12 +455,19 @@ app.post('/api/sessions', async (c) => {
   try {
     const body = await c.req.json().catch(() => null)
     const result = await sessionCreateRequest(body, { requestKey, signal: controller.signal })
+    // The durable row is now public. Nudge the cheap session projection explicitly so a dashboard does not
+    // wait for the best-effort store watcher; any held candidate worktree event remains a separate full claim.
+    if (result.status === 201) notifyBoardChanged('sessions')
+    // A candidate registry event is intentionally held while Git creates the private worktree. Once the
+    // transaction has published or cleaned up its record, release the one deferred full refresh.
+    flushDeferredWorktreeRegistryChange()
     if (result.status === 201) {
       c.header('Idempotency-Key', requestKey)
       return c.json(result.session, 201)
     }
     return c.json({ error: result.error, ...(result.code ? { code: result.code } : {}), ...(result.phase ? { phase: result.phase } : {}) }, result.status as any)
   } finally {
+    flushDeferredWorktreeRegistryChange()
     rawSignal.removeEventListener('abort', cancelFromRequest)
     outgoing?.off('close', cancel)
   }

package/spec-cli/src/init.ts

@@ -1,29 +1,20 @@
 import { existsSync, mkdirSync, copyFileSync, readFileSync, readdirSync, renameSync, rmSync, statSync, chmodSync, writeFileSync } from 'node:fs'
-import { createHash } from 'node:crypto'
 import { join, resolve, relative, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { readConfig, readJsonConfig } from './layout.js'
 import { resolveHarnessTargets, parseHarnessFlag, NATIVE_HARNESS_IDS } from './harness-select.js'
+import { gitBinary } from './git.js'
 
 // this file lives at <pkgRoot>/src/init.ts, so `..` is the package root — the same derivation the
 // launch paths use, never a hardcoded repo path (so a relocated/installed package still finds its data).
 const pkgRoot = fileURLToPath(new URL('..', import.meta.url))
 const TEMPLATES = join(pkgRoot, 'templates')
 const MANAGED_HOOK_HEADER = '# spexcode-managed-hook-v1'
-const LEGACY_MANAGED_HOOKS: Record<string, Set<string>> = {
-  'pre-commit': new Set(['fc33a6ff2b444fa47210a2594b6a714613d9c62fd8ec77a9a13aec81143de8a7']),
-  'prepare-commit-msg': new Set(['08b26ad8ffb305a64b7cddc868231854c84d539b8e5e9324702bd2c293044183']),
-}
-
-function hookDigest(path: string): string {
-  return createHash('sha256').update(readFileSync(path)).digest('hex')
-}
 
-function isManagedHook(path: string, name: string): boolean {
+function isManagedHook(path: string): boolean {
   const source = readFileSync(path, 'utf8')
   return source.split('\n').slice(0, 4).includes(MANAGED_HOOK_HEADER)
-    || LEGACY_MANAGED_HOOKS[name]?.has(createHash('sha256').update(source).digest('hex')) === true
 }
 
 function replaceHook(source: string, dest: string): void {
@@ -71,7 +62,7 @@ function copyTreeNoClobber(srcDir: string, destDir: string, base: string): strin
 // hooks/ (shared across all worktrees). Returns null (with a loud reason) when <dir> isn't a git repo.
 function resolveHooksDir(dir: string): string | null {
   try {
-    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    const common = execFileSync(gitBinary(process.env), ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'], // swallow git's own "fatal: not a git repository" — our warning is the signal
     }).trim()
@@ -86,8 +77,8 @@ function resolveHooksDir(dir: string): string | null {
 // turn that feature branch into trunk).
 function adoptionMainBranch(dir: string): string {
   try {
-    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8' }).trim()
-    const branch = execFileSync('git', ['-C', dirname(common), 'symbolic-ref', '--short', 'HEAD'], { encoding: 'utf8' }).trim()
+    const common = execFileSync(gitBinary(process.env), ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8' }).trim()
+    const branch = execFileSync(gitBinary(process.env), ['-C', dirname(common), 'symbolic-ref', '--short', 'HEAD'], { encoding: 'utf8' }).trim()
     if (branch) return branch
   } catch { /* render the one product-level repair below */ }
   const error = new Error('cannot determine the source-of-truth branch at adoption — check out the trunk in the root checkout, or set "mainBranch" in spexcode.json before re-running `spex init`')
@@ -113,7 +104,7 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
   // NOT `git init` for them: creating a repo is a side effect beyond init's remit (a subdir, a dir not
   // meant as a repo root), and `git init` is one deliberate command.
   try {
-    execFileSync('git', ['-C', targetDir, 'rev-parse', '--is-inside-work-tree'], { stdio: ['ignore', 'ignore', 'ignore'] })
+    execFileSync(gitBinary(process.env), ['-C', targetDir, 'rev-parse', '--is-inside-work-tree'], { stdio: ['ignore', 'ignore', 'ignore'] })
   } catch {
     console.error(`spex init: ${targetDir} is not a git repository. SpexCode is git-backed (git is the version database; the hooks live in .git). Run \`git init\` there first, then \`spex init\`.`)
     process.exit(1)
@@ -210,8 +201,8 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
       const source = join(hooksSrc, e.name)
       const dest = join(hooksDir, e.name)
       if (existsSync(dest)) {
-        if (hookDigest(dest) === hookDigest(source)) continue
-        if (isManagedHook(dest, e.name)) {
+        if (readFileSync(dest).equals(readFileSync(source))) continue
+        if (isManagedHook(dest)) {
           replaceHook(source, dest)
           refreshed.push(e.name)
         } else {

package/spec-cli/src/layout.ts

@@ -170,10 +170,28 @@ export function readUploadPolicy(root: string): UploadPolicy {
 // the shared git common dir (env-stripped git() so a hook's exported GIT_DIR can't misdirect it). Memoized:
 // it's a process constant, but mainBranch()/mainRoot() resolve it per call (~60 git rev-parse forks per board build without the cache).
 let commonDirCache: string | null = null
+const commonDirsByPath = new Map<string, string>()
+const topsByPath = new Map<string, string>()
 export function gitCommonDir(): string {
   if (commonDirCache === null) commonDirCache = git(['rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
   return commonDirCache
 }
+function commonDirFor(proj: string): string {
+  const key = resolve(proj)
+  const known = commonDirsByPath.get(key)
+  if (known) return known
+  const common = git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
+  commonDirsByPath.set(key, common)
+  return common
+}
+function topFor(proj: string): string {
+  const key = resolve(proj)
+  const known = topsByPath.get(key)
+  if (known) return known
+  const top = git(['-C', proj, 'rev-parse', '--show-toplevel']).trim()
+  topsByPath.set(key, top)
+  return top
+}
 
 export function mainBranch(): string {
   let checkout: string
@@ -186,9 +204,7 @@ export function mainBranch(): string {
 // `.codex` (codex-rs hooks_config_folder override), NOT the worktree's, so the codex hooks shim + trust
 // materialize here while AGENTS.md/skills stay per-worktree — see [[harness-adapter]] (harness.ts).
 export function mainCheckout(proj?: string): string {
-  const gcd = proj
-    ? git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
-    : gitCommonDir()
+  const gcd = proj ? commonDirFor(proj) : gitCommonDir()
   return dirname(gcd)
 }
 
@@ -222,9 +238,7 @@ export function mainRoot(proj?: string): string {
 // proj-aware for `spex init <dir>` / materialize(proj); cwd-based default for the hooks/board. The shell
 // hooks mirror this as hp_runtime_dir.
 export function runtimeRoot(proj?: string): string {
-  const gcd = proj
-    ? git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
-    : gitCommonDir()
+  const gcd = proj ? commonDirFor(proj) : gitCommonDir()
   return projectRuntimeRoot(gcd)
 }
 // the per-WORKTREE materialize slot — <runtime>/trees/<enc(worktree-toplevel)> — holding the materialize
@@ -236,7 +250,7 @@ export function runtimeRoot(proj?: string): string {
 // land on the same slot from the same tree, and only from the same tree. Throws when `wt` is not a live
 // git tree (fail loud); a best-effort caller (the close-time GC) wraps it.
 export function treeSlotDir(wt: string): string {
-  const top = git(['-C', wt, 'rev-parse', '--show-toplevel']).trim()
+  const top = topFor(wt)
   return join(runtimeRoot(wt), 'trees', encodeProject(top || wt))
 }
 // this project's per-session records dir, one session's dir, its structured record, and a sibling artifact —
@@ -448,6 +462,20 @@ export function listSessionIds(): string[] {
   return ents.filter((d) => d.isDirectory()).map((d) => d.name)
 }
 
+// @@@ branch -> session, so a moved ref can DERIVE its invalidation scope - a session's evaluation depends
+// on its own branch tip, the base branch tip and their merge-base; no other ref participates. Without this
+// map a ref watcher knows only that "something under refs/ moved" and the honest fallback is to invalidate
+// every session ([[taste]] 19). One record read per session, and only when the session store itself moved.
+export function sessionBranchIndex(): Map<string, string> {
+  const index = new Map<string, string>()
+  for (const id of listSessionIds()) {
+    let branch: unknown
+    try { branch = readRawRecord(id)?.branch } catch { continue }   // a corrupt record narrows nothing
+    if (typeof branch === 'string' && branch) index.set(branch, id)
+  }
+  return index
+}
+
 // memo the overlay (4 git diffs/worktree, all .spec-scoped) keyed on fork-point merge-base + HEAD + spec
 // sig + MAIN'S TIP ([[worktree-linker]]): the main-tip component is what lets a merge landing identical
 // content dissolve a worktree's now-moot ops — the recompute it triggers is cheap because every diff is