spexcode 0.5.9 → 0.6.1

package/spec-cli/src/delivery-queue.ts

@@ -0,0 +1,107 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'
+import { join } from 'node:path'
+import { runtimeRoot, sessionArtifactPath, sessionStoreDir } from './layout.js'
+
+// @@@ delivery-queue - what a session still OWES its agent. The log ([[session-timeline]]) is the record and
+// grows forever; this is the debt and is consumed, so it lives in its own small file whose resting state is
+// EMPTY. Nothing here reads the log: an entry carries the text it will hand over, so history could be trimmed
+// or archived without changing what is owed. A session that predates this mechanism owes nothing, because a
+// queue is only ever filled by an enqueue — which is why no backlog migration exists.
+
+export type PendingMessage = { mid: string; text: string; from: string | null }
+
+const queuePath = (id: string): string => sessionArtifactPath(id, 'pending.json')
+
+// @@@ its own lock, deliberately NOT the record lock - the drain holds this across the adapter insert, which
+// is what makes "claim" real: two processes draining the same session cannot both hand over one message. The
+// record lock could never span that call — a native turn runs lifecycle hooks that re-enter the record writer,
+// and holding it there deadlocks the adapter's own confirmation. Nothing in the delivery path takes this one,
+// so spanning the insert costs no contention. PID liveness reclaims a lock whose holder died mid-insert.
+const lockRoot = (): string => join(runtimeRoot(), '.delivery-locks')
+const lockPath = (id: string): string => join(lockRoot(), `${id}.lock`)
+
+const pause = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
+
+async function acquire(id: string, timeoutMs: number): Promise<(() => void) | null> {
+  mkdirSync(lockRoot(), { recursive: true })
+  const path = lockPath(id), deadline = Date.now() + timeoutMs
+  for (;;) {
+    try {
+      const fd = openSync(path, 'wx')
+      writeSync(fd, String(process.pid))
+      closeSync(fd)
+      return () => { try { unlinkSync(path) } catch { /* a liveness reclaim already removed it */ } }
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e
+      let owner = 0
+      try { owner = Number(readFileSync(path, 'utf8').trim()) || 0 } catch { /* race with creator/releaser */ }
+      if (owner && owner !== process.pid) {
+        try { process.kill(owner, 0) } catch { try { unlinkSync(path) } catch { /* race */ }; continue }
+      }
+      // A drain is never urgent enough to fight for: whoever holds the lock is delivering these same messages,
+      // and the retry sweep will come back. Declining is not a lost message.
+      if (Date.now() >= deadline) return null
+      await pause(25)
+    }
+  }
+}
+
+function read(id: string): PendingMessage[] {
+  try {
+    const raw = JSON.parse(readFileSync(queuePath(id), 'utf8')) as unknown
+    if (!Array.isArray(raw)) return []
+    return raw.filter((m): m is PendingMessage =>
+      !!m && typeof m === 'object'
+      && typeof (m as PendingMessage).mid === 'string'
+      && typeof (m as PendingMessage).text === 'string')
+  } catch { return [] }   // absent, empty, or unparseable all mean the honest thing: nothing owed
+}
+
+// Written whole and atomically; an empty queue is REMOVED rather than left as `[]`, so "is anything owed?" is
+// one existsSync on the sweep's hot path.
+function write(id: string, msgs: PendingMessage[]): void {
+  const path = queuePath(id)
+  if (!msgs.length) { try { unlinkSync(path) } catch { /* already gone */ } ; return }
+  mkdirSync(sessionStoreDir(id), { recursive: true })
+  const tmp = `${path}.${process.pid}.tmp`
+  writeFileSync(tmp, JSON.stringify(msgs, null, 2) + '\n')
+  renameSync(tmp, path)
+}
+
+// The enqueue rides the timeline append ([[dispatch]]): the caller holds the session's RECORD lock across
+// both, and the record is written first, so a crash between them leaves a message visible but undelivered —
+// never delivered but unrecorded.
+export function enqueue(id: string, msg: PendingMessage): void {
+  write(id, [...read(id), msg])
+}
+
+export const pendingMessages = (id: string): PendingMessage[] => read(id)
+
+export const owesDelivery = (id: string): boolean => existsSync(queuePath(id))
+
+// Hand over what is owed, in order, exactly once. `insert` reports whether the adapter took the message: only
+// then is the entry dropped. A refusal ENDS the pass with that entry still queued and everything behind it
+// still behind it — order is a property of a conversation, so a message is never skipped to deliver a later
+// one. Returns how many were handed over and how many are still owed.
+export async function drain(
+  id: string,
+  insert: (msg: PendingMessage) => Promise<boolean>,
+  timeoutMs = 5_000,
+): Promise<{ delivered: number; remaining: number }> {
+  const release = await acquire(id, timeoutMs)
+  if (!release) return { delivered: 0, remaining: read(id).length }
+  let delivered = 0
+  try {
+    for (;;) {
+      const queued = read(id)
+      if (!queued.length) return { delivered, remaining: 0 }
+      let ok = false
+      try { ok = await insert(queued[0]) } catch { ok = false }
+      if (!ok) return { delivered, remaining: queued.length }
+      // Re-read before removing: a send that landed while this pass ran appended to the tail, and rewriting a
+      // stale snapshot minus the head would silently drop it.
+      write(id, read(id).filter((m) => m.mid !== queued[0].mid))
+      delivered++
+    }
+  } finally { release() }
+}

package/spec-cli/src/doctor.ts

@@ -7,6 +7,7 @@ import { loadSystemConfig, loadSkillConfig, loadSpecs } from './specs.js'
 import { runtimeRoot, treeSlotDir, envSessionId, readAliasedRawRecord, mainCheckout, readJsonConfig } from './layout.js'
 import { loadConfig } from './lint.js'
 import { trackedSourceFiles } from './source-files.js'
+import { gitBinary } from './git.js'
 
 // this file lives at <pkgRoot>/src/self.ts, so `..` is the package root — the same derivation init.ts/
 // materialize.ts use (never a hardcoded repo path), so the git-hook template lookup survives a relocated install.
@@ -14,7 +15,7 @@ const PKG_ROOT = fileURLToPath(new URL('..', import.meta.url))
 
 // run a git query in `dir`, swallowing git's own stderr — a non-repo returns null (the absence IS the signal).
 function git(dir: string, args: string[]): string | null {
-  try { return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() }
+  try { return execFileSync(gitBinary(process.env), ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() }
   catch { return null }
 }
 function repoRoot(dir: string): string | null { return git(dir, ['rev-parse', '--show-toplevel']) }

package/spec-cli/src/file-write.ts

@@ -0,0 +1,22 @@
+import { copyFileSync, readFileSync, writeFileSync } from 'node:fs'
+
+export function writeFileIfChanged(path: string, content: string | Uint8Array): boolean {
+  const next = Buffer.from(content)
+  try {
+    if (readFileSync(path).equals(next)) return false
+  } catch (error: any) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+  writeFileSync(path, content)
+  return true
+}
+
+export function copyFileIfChanged(source: string, target: string): boolean {
+  try {
+    if (readFileSync(target).equals(readFileSync(source))) return false
+  } catch (error: any) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+  copyFileSync(source, target)
+  return true
+}

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
@@ -282,7 +283,7 @@ export interface Harness {
   // write one idempotent rendezvous reply; Codex uses JSON-RPC on the same app-server WebSocket the
   // visible TUI uses — it reads the thread live and either `turn/steer`s the message INTO an in-progress turn
   // (mid-turn, not queued for after the agent stops) or `turn/start`s a fresh turn when the thread is idle.
-  // `ok=false` leaves the durable timeline line for the turn-boundary reader.
+  // `ok=false` leaves the message OWED on the session's delivery queue, for a later pass to hand over.
   deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>
   // Observe native turn failures that this harness does not expose as a lifecycle hook. The adapter owns the
   // transport subscription; sessions owns observer reconciliation and the active-only lifecycle CAS.
@@ -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,10 +44,10 @@ 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 inbox, and exits 0 on
+      `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
 status into an actionable one (stdout = the observed path, e.g. working→review; read the LAST
 token as the status reached), or a message arriving for you (stdout = message). The arrival
@@ -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,10 +15,10 @@ 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, SessionRecordUnusable, TMUX_SOCK } from './sessions.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'
 import { readTimeline } from './session-timeline.js'
 import { defaultHarness, HARNESSES, dashboardLauncherList, launcherDefault } from './harness.js'
 import { evalTimeline, readBlobByHash } from '../../spec-eval/src/evaltab.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)
   }
@@ -700,6 +707,7 @@ injectWebSocket(server)
 superviseBridges()   // restore visible helpers after failure; their viewer subscriptions survive replacement
 superviseQueue()     // launch queued sessions as slots free (catches agent-authored proposals/crashes the server never sees directly)
 superviseTurnFailures() // reconcile adapter-owned native failure subscriptions across backend replacement
+superviseDelivery()  // hand over messages an earlier pass could not ([[delivery-queue]]): the retry half of dispatch
 console.log(`spec-cli serving .spec (from git) on http://localhost:${port}`)
 
 let graphWatchersClosed = false