spexcode 0.6.1 → 0.6.2

package/spec-cli/src/layout.ts

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync, readdirSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { git, repoRoot, gitA, headSha, worktreeSpecSig, worktreeSpecDelta, type NodeOp } from './git.js'
+import { git, repoRoot, gitA, gitAbortError, currentGitBuildAbortSignal, gitInterpretationIdentity, headSha, worktreeSpecSig, worktreeSpecDelta, worktreeSpecDeltas, withGitAbortSignal, type NodeOp } from './git.js'
 import { guardWorktree } from './resilience.js'
 import { HARNESSES, type HarnessId } from './harness.js'
 import { encodeProject, projectRuntimeRoot, spexcodeHome } from './project-store.js'
@@ -276,6 +276,7 @@ export type RawRecord = {
   launch_cmd?: string // the RESOLVED base launcher command PINNED at creation, so a resume replays the EXACT launcher (and its config-dir env) that made the conversation, never a since-changed default ([[launcher-select]] resume-launcher-pin); absent → old record, fall back to the launcher name / ambient
   create_request_id?: string // SHA-256 digest of the create Idempotency-Key; the raw key is never persisted
   create_payload_hash?: string // normalized create payload bound to create_request_id
+  base?: string // the exact fork point pinned at creation; absent/empty → the auto-detected source-of-truth branch
   launch_readiness_pending?: '' | RawLaunchReadinessPending
 }
 
@@ -445,6 +446,10 @@ export function readAliasedRawRecord(id: string): RawRecord | null {
 export function readAliasedRecordEntry(id: string): RecordEntry {
   const direct = readRecordEntry(id)
   if (direct.kind !== 'absent') return direct
+  // @@@ absence splits in two, and only one half is an alias question - an id owning a store dir is already
+  // one of ours (the sentinel-only agent above), so its emptiness is settled; searching would let an unrelated
+  // record answer under a live session's own name, and costs a whole-store re-parse per 1s supervisor tick.
+  if (existsSync(sessionStoreDir(id))) return { kind: 'absent' }
   for (const sid of listSessionIds()) {
     const r = readRawRecord(sid)
     if (r && r.harness_session_id && r.harness_session_id === id) return { kind: 'ok', raw: r }
@@ -476,35 +481,99 @@ export function sessionBranchIndex(): Map<string, string> {
   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
-// .spec-scoped.
+// Retain only completed per-worktree overlays. Interpretation + main tip + HEAD + working signature completely
+// determine the merge-base and projection; a landed main tip therefore dissolves now-moot ops on the next read.
 const deltaCache = new Map<string, { key: string; ops: NodeOp[] }>()
 const safeHead = (p: string): string => { try { return headSha(p) } catch { return '' } }
-const safeMergeBase = async (wtPath: string, mainRef: string): Promise<string> => {
-  try { return (await gitA(['-C', wtPath, 'merge-base', mainRef, 'HEAD'])).trim() } catch { return '' }
-}
 let layoutHeadWarned = false
-async function cachedDelta(wtPath: string, mainRef: string, mainSha: string): Promise<NodeOp[]> {
-  const wtHead = safeHead(wtPath)
-  const base = await safeMergeBase(wtPath, mainRef)
-  // fail loud, never stale: if the merge-base, HEAD, or main tip can't be read the key is untrustworthy —
-  // bypass the cache and recompute (warn once) rather than risk serving a delta keyed on an empty sha
-  // across a real change.
-  if (!base || !wtHead || !mainSha) {
-    if (!layoutHeadWarned) { layoutHeadWarned = true; console.warn('spec-cli: layout overlay cache bypassed (unreadable merge-base/HEAD/main tip), recomputing every read') }
-    return worktreeSpecDelta(wtPath, mainRef)
+type LayoutDeltaOutcome = { ops: NodeOp[] } | { error: unknown }
+type LayoutDeltaFlight = {
+  promise: Promise<Map<string, LayoutDeltaOutcome>>
+  controller: AbortController
+  waiters: Set<symbol>
+  settled: boolean
+}
+const layoutDeltaFlights = new Map<string, LayoutDeltaFlight>()
+
+// One exact public layout generation owns the cold overlay computation. The map is only an in-flight join:
+// the entry is deleted at settlement and deltaCache remains the sole retained result state.
+async function layoutDeltas(paths: string[], main: string, mainRef: string, mainSha: string): Promise<Map<string, LayoutDeltaOutcome>> {
+  const snapshots = paths.map((path) => ({ path, head: safeHead(path), sig: worktreeSpecSig(path) }))
+  const interpretation = gitInterpretationIdentity(main)
+  const flightKey = JSON.stringify([interpretation, mainRef, mainSha, snapshots.map(({ path, head, sig }) => [path, head, sig]).sort((a, b) => a[0].localeCompare(b[0]))])
+  let flight = layoutDeltaFlights.get(flightKey)
+  if (flight?.controller.signal.aborted) {
+    layoutDeltaFlights.delete(flightKey)
+    flight = undefined
+  }
+  if (!flight) {
+    const controller = new AbortController()
+    const entry: LayoutDeltaFlight = { promise: Promise.resolve(new Map()), controller, waiters: new Set(), settled: false }
+    entry.promise = withGitAbortSignal(controller.signal, async () => {
+    const outcomes = new Map<string, LayoutDeltaOutcome>()
+    const misses: typeof snapshots = []
+    for (const snapshot of snapshots) {
+      const key = `${interpretation}\0${mainSha}\0${snapshot.head}\0${snapshot.sig}`
+      const hit = snapshot.head && mainSha ? deltaCache.get(snapshot.path) : null
+      if (hit?.key === key) outcomes.set(snapshot.path, { ops: hit.ops })
+      else misses.push(snapshot)
+    }
+
+    const valid = misses.filter(({ head }) => !!head && !!mainSha)
+    const batched = await worktreeSpecDeltas(main, mainSha, valid.map(({ path, head }) => ({ path, head })), interpretation)
+    for (const snapshot of valid) {
+      const outcome = batched.get(snapshot.path) ?? { error: new Error(`layout overlay batch omitted ${snapshot.path}`) }
+      if ('error' in outcome) outcomes.set(snapshot.path, outcome)
+      else {
+        const key = `${interpretation}\0${mainSha}\0${snapshot.head}\0${snapshot.sig}`
+        deltaCache.set(snapshot.path, { key, ops: outcome.ops })
+        outcomes.set(snapshot.path, { ops: outcome.ops })
+      }
+    }
+
+    await Promise.all(misses.filter(({ head }) => !head || !mainSha).map(async (snapshot) => {
+      if (!existsSync(snapshot.path)) {
+        outcomes.set(snapshot.path, { error: new Error(`worktree ${snapshot.path} is absent`) })
+        return
+      }
+      if (!layoutHeadWarned) {
+        layoutHeadWarned = true
+        console.warn('spec-cli: layout overlay cache bypassed (unreadable HEAD/main tip), recomputing every read')
+      }
+      try { outcomes.set(snapshot.path, { ops: await worktreeSpecDelta(snapshot.path, mainRef) }) }
+      catch (error) { outcomes.set(snapshot.path, { error }) }
+    }))
+    return outcomes
+    }).finally(() => {
+      entry.settled = true
+      if (layoutDeltaFlights.get(flightKey) === entry) layoutDeltaFlights.delete(flightKey)
+    })
+    layoutDeltaFlights.set(flightKey, entry)
+    flight = entry
+  }
+
+  const token = Symbol(flightKey)
+  const callerSignal = currentGitBuildAbortSignal()
+  flight.waiters.add(token)
+  let onAbort: (() => void) | null = null
+  try {
+    if (!callerSignal) return await flight.promise
+    if (callerSignal.aborted) throw gitAbortError()
+    return await Promise.race([
+      flight.promise,
+      new Promise<Map<string, LayoutDeltaOutcome>>((_, reject) => {
+        onAbort = () => reject(gitAbortError())
+        callerSignal.addEventListener('abort', onAbort, { once: true })
+      }),
+    ])
+  } finally {
+    if (onAbort) callerSignal?.removeEventListener('abort', onAbort)
+    flight.waiters.delete(token)
+    if (!flight.settled && flight.waiters.size === 0) flight.controller.abort()
   }
-  const key = `${base}\0${wtHead}\0${mainSha}\0${worktreeSpecSig(wtPath)}`
-  const hit = deltaCache.get(wtPath)
-  if (hit && hit.key === key) return hit.ops
-  const ops = await worktreeSpecDelta(wtPath, mainRef, base)
-  deltaCache.set(wtPath, { key, ops })
-  return ops
 }
 
-export async function resolveLayout(): Promise<Layout> {
+export async function resolveLayout(options: { activeSessionIds?: readonly string[] } = {}): Promise<Layout> {
   const root = repoRoot()
   const main = dirname(gitCommonDir())   // the main checkout — same answer from main OR any linked worktree
   const cfg = readConfig(main)
@@ -524,22 +593,36 @@ export async function resolveLayout(): Promise<Layout> {
   const publicEntries = listSessionIds().map((id) => readPublicRecordEntry(id))
     .filter((entry) => entry.kind === 'corrupt' ? entry.governed !== false : entry.kind === 'ok' && entry.raw.governed)
   const records = publicEntries.flatMap((entry) => entry.kind === 'ok' ? [entry] : [])
+  const projectedActive = options.activeSessionIds ? new Set(options.activeSessionIds) : null
+  const isActive = (record: RawRecord): boolean => projectedActive
+    ? projectedActive.has(record.session_id)
+    : !record.archived
   // main's tip, resolved ONCE per board read — a component of every worktree's overlay cache key
   // ([[worktree-linker]]: landed content must dissolve the ops it made moot).
   const mainSha = await (async () => {
     try { return (await gitA(['-C', main, 'rev-parse', '--verify', `${mainRef}^{commit}`])).trim() } catch { return '' }
   })()
+  const activePaths = records.filter(({ raw }) => isActive(raw)).map(({ raw }) => raw.worktree_path)
+  const deltas = await layoutDeltas(activePaths, main, mainRef, mainSha)
   const rows = await Promise.all(records.map(({ raw: r, liveness }) => {
     const node = r.node ?? (r.branch && r.branch.startsWith(convention.branchPrefix) ? r.branch.slice(convention.branchPrefix.length) : null)
     const base: Worktree = { path: r.worktree_path, branch: r.branch, node, session: r.session_id, status: r.status, isMain: false, ...(liveness ? { liveness } : {}), ops: [] }
-    // @@@ archived rows cost nothing - a shelved session ([[archive]]) keeps its row (the record is the
-    // existence truth) but skips the per-worktree spec-delta entirely: that git-history probe is the board's
-    // dominant per-row cost, and shelving is exactly the human saying "stop spending attention here". So the
-    // price of a retained archive is one enumerated record, NOT a git walk per poll.
-    if (r.archived) return Promise.resolve(base)
+    // @@@ projected shelves cost nothing - a cold archived session ([[archive]]) keeps its record but leaves
+    // the working-set projection and skips the per-worktree spec delta. An archived runtime hazard is still
+    // projected active by listSessions, so it deliberately retains the same ops in both full and splice builds.
+    if (!isActive(r)) return Promise.resolve(base)
     return guardWorktree<Worktree>(r.worktree_path,
-      async (): Promise<Worktree> => ({ ...base, ops: await cachedDelta(r.worktree_path, mainRef, mainSha) }),
-      (): Worktree => ({ ...base, ops: deltaCache.get(r.worktree_path)?.ops ?? [] }))
+      (): Worktree => {
+        const outcome = deltas.get(r.worktree_path)
+        if (!outcome) throw new Error(`layout overlay missing ${r.worktree_path}`)
+        if ('error' in outcome) throw outcome.error
+        return { ...base, ops: outcome.ops }
+      },
+      (): Worktree => {
+        const cached = deltaCache.get(r.worktree_path)
+        if (!cached) throw new Error(`layout overlay failed before ${r.worktree_path} had a last-known result`)
+        return { ...base, ops: cached.ops }
+      })
   }))
   const corruptRows: Worktree[] = publicEntries.flatMap((entry) => entry.kind === 'corrupt'
     ? [{ path: '', branch: null, node: null, session: entry.sessionId, status: 'corrupt', liveness: 'unknown', isMain: false, ops: [] }]
@@ -549,9 +632,9 @@ export async function resolveLayout(): Promise<Layout> {
   const mainRow: Worktree = { path: main, branch: base, node: null, session: null, status: null, isMain: true, ops: [] }
   const worktrees = [mainRow, ...sessionWorktrees]
   // drop cache entries for worktrees that may no longer hold one — closed sessions (gone from the store) AND
-  // newly-archived ones (which no longer compute a delta), so archiving SELF-EVICTS its cached ops instead of
+  // newly-cold archived ones (which no longer compute a delta), so archiving SELF-EVICTS its cached ops instead of
   // stranding them in a map nothing prunes.
-  const live = new Set(records.filter(({ raw }) => !raw.archived).map(({ raw }) => raw.worktree_path))
+  const live = new Set(records.filter(({ raw }) => isActive(raw)).map(({ raw }) => raw.worktree_path))
   for (const k of [...deltaCache.keys()]) if (!live.has(k)) deltaCache.delete(k)
   return { main: convention.main || main || root, convention, worktrees }
 }

package/spec-cli/src/lint.ts

@@ -1,12 +1,20 @@
 import { readFileSync, existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { repoRoot, git, sourceIndexes, rowsFor, treeFilePaths, treeFileText, type DriftPathEvent } from './git.js'
+import { repoRoot, git, sourceIndexes, rowsFor, treeFilePaths, treeFileText, withEventLedgerBuild, type DriftPathEvent } from './git.js'
 import { loadSpecs, parseFrontmatter } from './specs.js'
 import { readJsonConfig } from './layout.js'
 import { extractors, extractorFor, extOf, parseCodeEntry, relationClaimsPath, resolveAnchor, resolveSelectors, windowEvents, anchorHitQueries } from './anchors.js'
 import { DEFAULT_TEST_GLOBS, sourcePolicyDescription, trackedSourceFiles } from './source-files.js'
 
 export type Finding = { level: 'error' | 'warn'; rule: string; spec?: string; file?: string; msg: string }
+export const SPEC_LINT_REPORT_PROJECTION = 'spex.spec-lint.report'
+export const SPEC_LINT_REPORT_SCHEMA_VERSION = 1
+export type SpecLintReport = {
+  projection: typeof SPEC_LINT_REPORT_PROJECTION
+  schemaVersion: typeof SPEC_LINT_REPORT_SCHEMA_VERSION
+  sourceFiles: string[]
+  findings: Finding[]
+}
 
 export type LintConfig = {
   governedRoots: string[]       // dirs whose tracked source files must each be governed by a spec. '.' = whole project.
@@ -69,6 +77,7 @@ export function normalizeConfig(cfg: LintConfig): LintConfig {
 }
 
 export type SpecLintOptions = { tip?: string }
+type SpecLintRun = { sourceFiles: string[]; findings: Finding[] }
 
 function untrackedAdoptionFiles(root: string): string[] {
   if (git(['-C', root, 'rev-parse', '--is-inside-work-tree']).trim() !== 'true') return []
@@ -126,6 +135,24 @@ export async function pendingTouchesGoverned(root: string, tip: string): Promise
 }
 
 export async function specLint(root = repoRoot(), regs = extractors(root), options: SpecLintOptions = {}): Promise<Finding[]> {
+  return (await specLintRun(root, regs, options)).findings
+}
+
+export async function specLintReport(root = repoRoot(), regs = extractors(root), options: SpecLintOptions = {}): Promise<SpecLintReport> {
+  const run = await specLintRun(root, regs, options)
+  return {
+    projection: SPEC_LINT_REPORT_PROJECTION,
+    schemaVersion: SPEC_LINT_REPORT_SCHEMA_VERSION,
+    sourceFiles: run.sourceFiles,
+    findings: run.findings,
+  }
+}
+
+function specLintRun(root: string, regs: ReturnType<typeof extractors>, options: SpecLintOptions): Promise<SpecLintRun> {
+  return withEventLedgerBuild(root, () => specLintInLedger(root, regs, options))
+}
+
+async function specLintInLedger(root: string, regs: ReturnType<typeof extractors>, options: SpecLintOptions): Promise<SpecLintRun> {
   const tip = options.tip ?? 'HEAD'
   const pending = tip !== 'HEAD'
   const changed = pending ? pendingChangedPaths(root, tip) : []
@@ -145,11 +172,14 @@ export async function specLint(root = repoRoot(), regs = extractors(root), optio
   if (untracked.length) {
     const shown = untracked.slice(0, 6)
     const suffix = untracked.length > shown.length ? ` (+${untracked.length - shown.length} more)` : ''
-    return [{
-      level: 'error',
-      rule: 'integrity',
-      msg: `project source of truth is untracked: ${shown.join(', ')}${suffix} — add it with \`git add .spec spexcode.json\` and commit it; generated harness files such as .codex/, .claude/, and AGENTS.md are machine-local`,
-    }]
+    return {
+      sourceFiles: [],
+      findings: [{
+        level: 'error',
+        rule: 'integrity',
+        msg: `project source of truth is untracked: ${shown.join(', ')}${suffix} — add it with \`git add .spec spexcode.json\` and commit it; generated harness files such as .codex/, .claude/, and AGENTS.md are machine-local`,
+      }],
+    }
   }
   const governed = trackedSourceFiles(root, cfg.governedRoots, cfg, tip)
   const [hidx, didx] = await sourceIndexes(root, tip)
@@ -436,7 +466,7 @@ export async function specLint(root = repoRoot(), regs = extractors(root), optio
     out.push({ level: 'warn', rule: 'related-drift', msg: `${rd.length} related file(s) across ${byNode.size} node(s) drifted ahead of their spec (SOFT — a dependency shifted, worth a glance; never blocks, no ack, no eval staleness). Most: ${worst}` })
   }
 
-  return out
+  return { sourceFiles: governed.slice().sort(), findings: out }
 }
 
 export const DRIFT_GUIDANCE = `DRIFT — a governed file has moved ahead of its spec. A CHECKPOINT, not a chore: find WHERE the truth

package/spec-cli/src/materialize.ts

@@ -85,14 +85,19 @@ function publishSelection(path: string, body: string): void {
   renameSync(prepared, path)
 }
 
-const SENTINEL_RE = /\n*<!-- spexcode:start -->[\s\S]*?<!-- spexcode:end -->\n*/
-export function stripSpexcodeBlock(text: string): string {
-  const m = SENTINEL_RE.exec(text)
+function managedBlockPattern(comment: readonly [string, string]): RegExp {
+  const [open, close] = comment
+  const escape = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`\\n*${escape(`${open}spexcode:start${close}`)}[\\s\\S]*?${escape(`${open}spexcode:end${close}`)}\\n*`)
+}
+export function stripSpexcodeBlock(text: string, comment: readonly [string, string] = ['<!-- ', ' -->']): string {
+  const sentinel = managedBlockPattern(comment)
+  const m = sentinel.exec(text)
   if (!m) return text
   // mirror removeManagedBlock exactly: our block + its surrounding blanks collapse to one '\n', and only a
   // block sitting at the TOP of the file drops the leading newline (a host file beginning with its own
   // blank lines keeps them — clean(smudge(x)) == x).
-  const replaced = text.replace(SENTINEL_RE, '\n')
+  const replaced = text.replace(sentinel, '\n')
   return m.index === 0 ? replaced.replace(/^\n+/, '') : replaced
 }
 function hostContentOf(file: string): string {
@@ -387,7 +392,7 @@ export function materialize(proj = process.cwd()): MaterializeResult {
     .map((p) => relative(proj, p)).filter((p) => !p.startsWith('..'))
   const ignoreFile = join(proj, '.gitignore')
   const ignoreTracked = isTrackedHere(ignoreFile)
-  const ignoreHost = existsSync(ignoreFile) ? readFileSync(ignoreFile, 'utf8') : ''
+  const ignoreHost = existsSync(ignoreFile) ? stripSpexcodeBlock(readFileSync(ignoreFile, 'utf8'), ['# ', '']) : ''
   if (!ignoreTracked && !ignoreHost.trim()) localEntries.push('.gitignore')
   const ignoreBody = entries(localEntries)
   if (writeManagedBlock(ignoreFile, ignoreBody, ['# ', ''])) changedMaterialized.add(ignoreFile)

package/spec-cli/src/plugin-harness.ts

@@ -4,29 +4,29 @@ import { fileURLToPath } from 'node:url'
 import { copyFileIfChanged, writeFileIfChanged } from './file-write.js'
 
 // @@@ plugin-harness - the PLUGIN BUNDLE emitter: materialize the whole SpexCode system into ONE self-contained
-// Claude-plugin bundle dropped into the host-agent-scanned folder [[harness-select]] resolved (e.g. `.zcode` /
+// Claude-plugin bundle dropped into the host-agent-scanned folder [[harness-select]] resolved (e.g. `.adopter-a` /
 // `.claude` → <folder>/plugins/spexcode/). It is the plugin-target counterpart of the native per-harness
 // write [[harness-adapter]] does — chosen INSTEAD of the natives (plugin exclusivity), so [[harness-delivery]]'s
 // materialize prunes every native first, then emits this. The bundle follows the de-facto Claude-plugin schema
 // (a `.claude-plugin/plugin.json` pointing at hooks/skills/commands/agents); the host's discovery order is
-// `.zcode-plugin > .claude-plugin > .codex-plugin` and z-code/Claude both read a `.claude-plugin` directly, so
-// the ONE `.claude-plugin` bundle reaches ZCode, Claude, and (future) Codex from a single emit.
+// `.adopter-a-plugin > .claude-plugin > .codex-plugin` and adopter-a/Claude both read a `.claude-plugin` directly, so
+// the ONE `.claude-plugin` bundle reaches AdopterA, Claude, and (future) Codex from a single emit.
 //
 // The contract is NOT delivered by an always-on CLAUDE.md block here (the bundle never touches the repo's own
 // files) — it maps to a SessionStart hook that emits hookSpecificOutput.additionalContext (the harness-neutral
-// injection Claude/z-code normalize, the superpowers pattern), so a plugin host gets the contract with no
+// injection Claude/adopter-a normalize, the superpowers pattern), so a plugin host gets the contract with no
 // --append-system-prompt. The hooks reuse the SAME dispatch.sh wiring as the natives, located via the host's
 // ${CLAUDE_PLUGIN_ROOT} variable; dispatch.sh's first arg is the harness id `plugin`, so its shell mirror
-// (harness.sh) parses payloads as the claude family (z-code/Claude share Claude's tool names + file_path).
+// (harness.sh) parses payloads as the claude family (adopter-a/Claude share Claude's tool names + file_path).
 
 const PKG = fileURLToPath(new URL('..', import.meta.url))   // installed spec-cli root
 const HOOKS_SRC = join(PKG, 'hooks')                        // the canonical dispatch.sh + harness.sh source
 const PLUGIN_NAME = 'spexcode'
 // the host substitutes ${CLAUDE_PLUGIN_ROOT} with the bundle's own absolute path before running a hook command
-// (the same variable z-code's hook-compat honours), so dispatch.sh/inject-contract.sh resolve regardless of
+// (the same variable adopter-a's hook-compat honours), so dispatch.sh/inject-contract.sh resolve regardless of
 // where the host scanned the bundle from.
 const PLUGIN_ROOT = '${CLAUDE_PLUGIN_ROOT}'
-// the lifecycle events the bundle binds — the Claude/z-code superset; a host that fires fewer (Codex) simply
+// the lifecycle events the bundle binds — the Claude/adopter-a superset; a host that fires fewer (Codex) simply
 // never invokes the extras, so binding all is harmless and one emit serves every host.
 const PLUGIN_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'StopFailure', 'Notification'] as const
 
@@ -51,7 +51,7 @@ export function pluginBundleDir(proj: string, folder: string): string {
 }
 
 // the de-facto Claude-plugin manifest: name (the bundle identity clean() gates on), version, description, and
-// the component pointers Claude/z-code discover (hooks.json + the skills/commands/agents dirs).
+// the component pointers Claude/adopter-a discover (hooks.json + the skills/commands/agents dirs).
 function pluginManifest(version: string): string {
   return JSON.stringify({
     name: PLUGIN_NAME,
@@ -64,7 +64,7 @@ function pluginManifest(version: string): string {
   }, null, 2)
 }
 
-// hooks.json in the Claude/z-code-compatible shape { "hooks": { "<Event>": [{ "hooks": [command…] }] } }. Every
+// hooks.json in the Claude/adopter-a-compatible shape { "hooks": { "<Event>": [{ "hooks": [command…] }] } }. Every
 // event → the SHARED dispatch.sh (`plugin` baked as its harness id, SPEX inherited by handlers); SessionStart
 // ALSO runs inject-contract.sh first, so the contract additionalContext lands alongside the normal dispatch.
 function pluginHooksJson(spex: string): string {
@@ -90,7 +90,7 @@ function contractContextJson(contract: string): string {
 // stand-in for --append-system-prompt). A bare cat — all the encoding happened at materialize time.
 const INJECT_SH = `#!/usr/bin/env bash
 # Emit the SpexCode contract as SessionStart additionalContext — the harness-neutral contract injection (the
-# superpowers pattern; Claude/z-code normalize hookSpecificOutput.additionalContext) that replaces a plugin
+# superpowers pattern; Claude/adopter-a normalize hookSpecificOutput.additionalContext) that replaces a plugin
 # host's missing --append-system-prompt. The JSON was written at materialize time, so this is a trivial cat.
 here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
 [ -f "$here/contract-context.json" ] && cat "$here/contract-context.json"

package/spec-cli/src/reviews.ts

@@ -42,6 +42,9 @@ export type PagedReview<T extends ReviewItem = ReviewItem> = {
 
 export type EvalDetailReview = {
   scope: string | null
+  requestedScope: string | null
+  scopeFallback: 'trunk' | null
+  availability: 'measured' | 'unmeasured' | 'missing'
   selected: ReviewItem | null
   history: ReviewItem[]
   neighbors: {
@@ -56,6 +59,16 @@ export type EvalDetailReview = {
   evalRevision?: SessionEvals['evalRevision']
 }
 
+type EvalDetailMetadata = {
+  scope?: string | null
+  requestedScope?: string | null
+  scopeFallback?: 'trunk' | null
+  summary?: SessionEvals['summary']
+  evalRevision?: SessionEvals['evalRevision']
+  // the scope's whole measured sequence, when `items` deliberately holds only the rendered window
+  sequence?: { node: string; scenario: string }[]
+}
+
 const revisionOf = (value: unknown): string => createHash('sha256').update(JSON.stringify(value)).digest('hex')
 
 export function reviewPageNumber(value: unknown): number {
@@ -113,7 +126,7 @@ export function paginateReview<T extends ReviewItem>(
     pageCount,
     prev: page > 1 ? page - 1 : null,
     next: page < pageCount || overflow ? page + 1 : null,
-    revision: revisionOf(revisionInputs),
+    revision: revisionOf({ page, source: revisionInputs }),
     ...responseModel(model),
   }
 }
@@ -259,16 +272,15 @@ export function projectEvalDetail(
   historySource: ReviewItem[],
   node: string,
   scenario: string,
-  metadata: {
-    scope?: string | null
-    summary?: SessionEvals['summary']
-    evalRevision?: SessionEvals['evalRevision']
-    // the scope's whole measured sequence, when `items` deliberately holds only the rendered window
-    sequence?: { node: string; scenario: string }[]
-  } = {},
+  metadata: EvalDetailMetadata = {},
 ): EvalDetailReview {
   const results = items.filter((item: any) => item.filterKind === EVAL_FILTER_KIND.RESULT)
   const selected = results.find((item) => evalItemKey(item) === `${node}\0${scenario}`) ?? null
+  const availability = selected
+    ? 'measured'
+    : items.some((item: any) => evalItemKey(item) === `${node}\0${scenario}` && item.filterKind === EVAL_FILTER_KIND.BLIND)
+      ? 'unmeasured'
+      : 'missing'
   const history = historySource.filter((reading: any) => String(reading.scenario) === scenario)
   const stateByKey = new Map(results.map((item: any) => [evalItemKey(item), String(item.state ?? evalReviewState(item))]))
   const sequence = metadata.sequence
@@ -276,12 +288,17 @@ export function projectEvalDetail(
   const neighbors = boundedEvalNeighbors(sequence, node, scenario,
     (row) => stateByKey.get(evalItemKey(row)) ?? 'empty')
   const scope = metadata.scope ?? null
+  const requestedScope = metadata.requestedScope ?? scope
+  const scopeFallback = metadata.scopeFallback ?? null
   return {
     scope,
+    requestedScope,
+    scopeFallback,
+    availability,
     selected,
     history,
     neighbors,
-    revision: revisionOf({ scope, selected, history, neighbors, summary: metadata.summary, evalRevision: metadata.evalRevision }),
+    revision: revisionOf({ scope, requestedScope, scopeFallback, availability, selected, history, neighbors, summary: metadata.summary, evalRevision: metadata.evalRevision }),
     ...(metadata.summary ? { summary: metadata.summary } : {}),
     ...(metadata.evalRevision ? { evalRevision: metadata.evalRevision } : {}),
   }
@@ -306,45 +323,51 @@ export function focusNodes(order: SessionEvalOrderRow[], node: string, scenario:
   return [...new Set([node, ...sequence.slice(Math.max(0, index - 6), index + 7).map((row) => row.node)])]
 }
 
-export async function evalDetailReview(node: string, scenario: string, scope?: string | null): Promise<EvalDetailReview | null> {
+async function trunkEvalDetailReview(node: string, scenario: string, metadata: EvalDetailMetadata = {}): Promise<EvalDetailReview> {
+  await getBoard()
+  const snapshot = readReviewSnapshot()
+  const sourceNode = snapshot.evalNodes.find((candidate) => candidate.id === node)
+  return projectEvalDetail(trunkEvalReviewItems(snapshot.evalNodes), sourceNode?.readings ?? [], node, scenario, metadata)
+}
+
+export async function evalDetailReview(node: string, scenario: string, scope?: string | null): Promise<EvalDetailReview> {
   if (scope) {
     // A detail renders ONE row plus at most five neighbours, but owes the whole population's index/total.
     // So name the window from the freshness-free sequence and let only those nodes pay the freshness pass;
     // a build that finds a full cached model ignores the pick and answers from it instead.
     const model = await buildSessionEvals(scope, (order) => focusNodes(order, node, scenario))
-    if (!model) return null
+    if (!model) return trunkEvalDetailReview(node, scenario, { requestedScope: scope, scopeFallback: 'trunk' })
     const sourceNode = model.nodes.find((candidate) => candidate.id === node)
     return projectEvalDetail(scopedEvalReviewItems(model), sourceNode?.evals ?? [], node, scenario, {
       scope,
+      requestedScope: scope,
       summary: model.summary,
       evalRevision: model.evalRevision,
       ...(model.order ? { sequence: measuredSequence(model.order) } : {}),
     })
   }
-  await getBoard()
-  const snapshot = readReviewSnapshot()
-  const sourceNode = snapshot.evalNodes.find((candidate) => candidate.id === node)
-  return projectEvalDetail(trunkEvalReviewItems(snapshot.evalNodes), sourceNode?.readings ?? [], node, scenario)
+  return trunkEvalDetailReview(node, scenario)
 }
 
-async function timelineEvalReview(text: string, requestedPage: unknown) {
-  const node = readToken(text, 'node')
-  if (!node) return null
-  const [timeline, sessions] = await Promise.all([evalTimeline(node), listSessions()])
-  const measured = new Set(timeline.readings.map((reading) => reading.scenario))
-  const items = [
-    ...timeline.scenarios.filter((scenario) => !measured.has(scenario.name)).map((scenario) => ({
+export function timelineEvalReviewItems(timeline: Awaited<ReturnType<typeof evalTimeline>>, node: string): ReviewItem[] {
+  const declared = new Set(timeline.scenarios.map((scenario) => scenario.name))
+  const latest = new Map<string, any>()
+  for (const reading of timeline.readings) {
+    if (declared.has(reading.scenario) && !latest.has(reading.scenario)) latest.set(reading.scenario, reading)
+  }
+  return [
+    ...timeline.scenarios.filter((scenario) => !latest.has(scenario.name)).map((scenario) => ({
       ...scenario,
       scenario: scenario.name,
       node,
       filterKind: EVAL_FILTER_KIND.UNMEASURED,
     })),
-    ...timeline.readings.map((reading, index) => ({
+    ...[...latest.values()].map((reading) => ({
       ...reading,
       state: evalReviewState(reading),
       node,
       filterKind: EVAL_FILTER_KIND.RESULT,
-      filterKey: `${EVAL_FILTER_KIND.RESULT}:${index}`,
+      filterKey: `${EVAL_FILTER_KIND.RESULT}:${reading.scenario}`,
     })),
     ...(timeline.dangling ?? []).map((track) => ({
       ...track,
@@ -353,6 +376,13 @@ async function timelineEvalReview(text: string, requestedPage: unknown) {
       filterKey: `${EVAL_FILTER_KIND.DANGLING}:${track.threadId}`,
     })),
   ]
+}
+
+async function timelineEvalReview(text: string, requestedPage: unknown) {
+  const node = readToken(text, 'node')
+  if (!node) return null
+  const [timeline, sessions] = await Promise.all([evalTimeline(node), listSessions()])
+  const items = timelineEvalReviewItems(timeline, node)
   const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions, defaultKind: 'all', defaultSection: '' })
   return {
     scope: null,
@@ -379,14 +409,13 @@ export async function evalsReview(query: string | undefined, requestedPage: unkn
     const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions, defaultKind: 'all', defaultSection: '' })
     return {
       scope,
-      gates: model.gates ?? [],
+      gates: [],
       unknown: model.nodes.reduce((count, node) => count + (node.unknownCoverage?.length ?? 0), 0),
       summary: model.summary,
       evalRevision: model.evalRevision,
-      impact: model.impact,
       ...paginateReview(items, filtered.shown, filtered, requestedPage, {
-        domain: 'evals', scope, items, gates: model.gates ?? [], summary: model.summary,
-        evalRevision: model.evalRevision, impact: model.impact, sessions: sessions.map((session) => session.id),
+        domain: 'evals', scope, query: text, gates: [], summary: model.summary,
+        evalRevision: model.evalRevision, sessions: sessions.map((session) => session.id),
       }),
     }
   }

package/spec-cli/src/session-execution.ts

@@ -0,0 +1,68 @@
+import { streamSSE } from 'hono/streaming'
+import type { Context } from 'hono'
+import { harnessById } from './harness.js'
+import { readAliasedRawRecord } from './layout.js'
+import { currentHumanTurn } from './session-timeline.js'
+import type { ExecutionStep, ExecutionTurn } from './execution-trace.js'
+
+export type SessionExecution = Readonly<{
+  revision: string
+  turnId: string | null
+  workingNote: string | null
+  steps: readonly ExecutionStep[]
+}>
+
+const absentExecution = (turn: ExecutionTurn | null = null): SessionExecution => ({ revision: `turn:${turn?.token ?? '0'}`, turnId: turn?.token ?? null, workingNote: null, steps: [] })
+
+// This is deliberately a read projection. Native transcript bytes stay within the adapter, while the API owns
+// only enough information for the frontend's fixed renderer to paint the current execution slice.
+export function readSessionExecution(id: string): SessionExecution | null {
+  let record: ReturnType<typeof readAliasedRawRecord>
+  try { record = readAliasedRawRecord(id) } catch { return null }
+  if (!record?.governed) return null
+  const turn = currentHumanTurn(id)
+  const threadId = typeof record.harness_session_id === 'string' ? record.harness_session_id : ''
+  if (!threadId) return absentExecution(turn)
+  try {
+    const trace = harnessById(typeof record.harness === 'string' && record.harness ? record.harness : 'claude')
+      .executionTrace(threadId, turn)
+    return trace || absentExecution(turn)
+  } catch {
+    // A missing/unreadable native source is an absent transient trace, not a synthetic conversation failure.
+    return absentExecution(turn)
+  }
+}
+
+const TRACE_TICK_MS = 500
+const HEARTBEAT_TICKS = 20
+
+export async function sessionExecutionStream(c: Context) {
+  const id = c.req.param('id') || ''
+  if (!readSessionExecution(id)) return c.json({ error: 'no such session' }, 404)
+  return streamSSE(c, async (stream) => {
+    let aborted = false
+    let lastRevision = ''
+    let ticks = 0
+    const publish = async (): Promise<boolean> => {
+      const execution = readSessionExecution(id)
+      if (!execution) return false
+      if (execution.revision === lastRevision) return true
+      lastRevision = execution.revision
+      await stream.writeSSE({ event: 'execution', data: JSON.stringify(execution) })
+      return true
+    }
+
+    stream.onAbort(() => { aborted = true })
+    try {
+      if (!await publish()) return
+      while (!aborted) {
+        await stream.sleep(TRACE_TICK_MS)
+        if (aborted) break
+        if (!await publish()) break
+        if (++ticks % HEARTBEAT_TICKS === 0) await stream.writeSSE({ event: 'ping', data: 'x' })
+      }
+    } catch {
+      // EventSource reconnects a dropped stream. A native trace read must never take down the session server.
+    }
+  })
+}