spexcode 0.6.1 → 0.6.5

package/spec-cli/src/reviews.ts

@@ -1,405 +0,0 @@
-import { createHash } from 'node:crypto'
-import { listSessions } from './sessions.js'
-import { getBoard, getBoardForForgeRevision } from './graphCache.js'
-import { type SessionEvalOrderRow, buildSessionEvals, type SessionEvals } from '../../spec-eval/src/sessioneval.js'
-import { evalTimeline } from '../../spec-eval/src/evaltab.js'
-import { issuesEnabled as issuesEnabledForReview } from './localIssues.js'
-import { issueStores as issueStoresForReview } from './issues.js'
-import { hasReviewSnapshot, readReviewSnapshot } from './reviewSnapshot.js'
-import { residentForgeRevision, residentForgeState } from '../../spec-forge/src/resident.js'
-// @ts-expect-error The dashboard module is deliberately plain JS so the browser and server execute the
-// exact same tokenizer/matcher. It is shipped beside the built dashboard by the root package manifest.
-import { EVAL_FILTER_KIND, evalFilterModel, evalReviewState, issueFilterModel, tokenFilterState } from '../../spec-dashboard/src/reviewFilters.js'
-// @ts-expect-error See the shared-domain note above.
-import { EVAL_QUERY_DEFAULT, ISSUE_QUERY_DEFAULT, readToken } from '../../spec-dashboard/src/reviewQuery.js'
-
-export const REVIEW_PER_PAGE = 25
-
-type ReviewItem = Record<string, unknown>
-// A section count is one number, or — when the domain adapter splits that section — its named buckets,
-// which re-add to the same whole population ([[review-filters]] owns the split; Evals splits its measured
-// verdicts into {fresh,stale} so the remeasurement debt travels with the count instead of being recomputed
-// per surface). The fold happens ONCE, here on the server, over the complete filtered population.
-export type ReviewCount = number | Record<string, number>
-type ReviewOption = { value: string; label?: string; count?: number }
-type ReviewFacet = { key: string; label?: string; value: string; meaningful?: boolean; options: ReviewOption[] }
-type EvalNeighbor = { node: string; scenario: string; state: string }
-
-export type PagedReview<T extends ReviewItem = ReviewItem> = {
-  items: T[]
-  page: number
-  perPage: number
-  total: number
-  sourceTotal: number
-  pageCount: number
-  prev: number | null
-  next: number | null
-  revision: string
-  counts: Record<string, ReviewCount>
-  facets: Record<string, ReviewFacet>
-  section: { key: string; value: string; options: ReviewOption[] } | null
-}
-
-export type EvalDetailReview = {
-  scope: string | null
-  selected: ReviewItem | null
-  history: ReviewItem[]
-  neighbors: {
-    prev: EvalNeighbor[]
-    next: EvalNeighbor[]
-    total: number
-    index: number | null
-    order: 'default'
-  }
-  revision: string
-  summary?: SessionEvals['summary']
-  evalRevision?: SessionEvals['evalRevision']
-}
-
-const revisionOf = (value: unknown): string => createHash('sha256').update(JSON.stringify(value)).digest('hex')
-
-export function reviewPageNumber(value: unknown): number {
-  const raw = typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : Number.NaN
-  return Number.isSafeInteger(raw) && raw > 0 ? raw : 1
-}
-
-function responseModel(model: any): Pick<PagedReview, 'counts' | 'facets' | 'section'> {
-  const facets = Object.fromEntries(Object.entries(model.facets ?? {}).map(([key, raw]) => {
-    const facet = raw as any
-    return [key, {
-      key,
-      ...(facet.label != null ? { label: String(facet.label) } : {}),
-      value: String(facet.value ?? ''),
-      ...(facet.meaningful != null ? { meaningful: !!facet.meaningful } : {}),
-      options: (facet.options ?? []).map((option: any) => ({
-        value: String(option.value ?? ''),
-        ...(option.label != null ? { label: String(option.label) } : {}),
-        ...(Number.isFinite(option.count) ? { count: Number(option.count) } : {}),
-      })),
-    }]
-  })) as Record<string, ReviewFacet>
-  const section = model.section ? {
-    key: String(model.section.key),
-    ...(model.section.label != null ? { label: String(model.section.label) } : {}),
-    value: String(model.section.value ?? ''),
-    ...(model.section.meaningful != null ? { meaningful: !!model.section.meaningful } : {}),
-    options: (model.section.options ?? []).map((option: any) => ({
-      value: String(option.value ?? ''),
-      ...(option.label != null ? { label: String(option.label) } : {}),
-      ...(Number.isFinite(option.count) ? { count: Number(option.count) } : {}),
-    })),
-  } : null
-  return { counts: { ...(model.sections ?? {}) }, facets, section }
-}
-
-export function paginateReview<T extends ReviewItem>(
-  source: T[],
-  shown: T[],
-  model: any,
-  requestedPage: unknown,
-  revisionInputs: unknown,
-): PagedReview<T> {
-  const page = reviewPageNumber(requestedPage)
-  const total = shown.length
-  const pageCount = Math.ceil(total / REVIEW_PER_PAGE)
-  const start = (page - 1) * REVIEW_PER_PAGE
-  const overflow = pageCount > 0 ? page > pageCount : page > 1
-  return {
-    items: shown.slice(start, start + REVIEW_PER_PAGE),
-    page,
-    perPage: REVIEW_PER_PAGE,
-    total,
-    sourceTotal: source.length,
-    pageCount,
-    prev: page > 1 ? page - 1 : null,
-    next: page < pageCount || overflow ? page + 1 : null,
-    revision: revisionOf(revisionInputs),
-    ...responseModel(model),
-  }
-}
-
-const issueOrder = (a: any, b: any): number => String(b.created ?? '').localeCompare(String(a.created ?? ''))
-  || String(a.id ?? '').localeCompare(String(b.id ?? ''))
-
-export async function issuesReview(query: string | undefined, requestedPage: unknown) {
-  // The first request must wait for the first atomic publication. Once one exists, a graph refresh may be
-  // rebuilding unrelated board/session state; the published review source remains a valid answer and its
-  // revision/poll path will deliver the next generation without making this page join that flight.
-  residentForgeState()
-  if (!hasReviewSnapshot()) await getBoard()
-  else if (readReviewSnapshot().forgeRevision < residentForgeRevision()) {
-    await getBoardForForgeRevision(residentForgeRevision())
-  }
-  const sessions = await listSessions()
-  const issues = readReviewSnapshot().issues.slice().sort(issueOrder)
-  const text = String(query ?? '').trim() || ISSUE_QUERY_DEFAULT
-  const model = issueFilterModel(issues, tokenFilterState(text, 'issue'), { sessions, defaultSection: '' })
-  return {
-    enabled: issuesEnabledForReview(),
-    stores: issueStoresForReview(),
-    ...paginateReview(issues, model.shown, model, requestedPage, {
-      domain: 'issues', issues, sessions: sessions.map((session) => session.id),
-    }),
-  }
-}
-
-const byNewest = (a: any, b: any): number => Number(b.filterKind === EVAL_FILTER_KIND.RESULT) - Number(a.filterKind === EVAL_FILTER_KIND.RESULT)
-  || String(b.ts ?? '').localeCompare(String(a.ts ?? ''))
-  || String(a.node ?? '').localeCompare(String(b.node ?? ''))
-  || String(a.scenario ?? '').localeCompare(String(b.scenario ?? ''))
-
-export function trunkEvalReviewItems(nodes: any[]): ReviewItem[] {
-  const items: any[] = []
-  for (const node of nodes ?? []) {
-    const latest = new Map<string, any>()
-    for (const reading of node.evals ?? []) if (!latest.has(reading.scenario)) latest.set(reading.scenario, reading)
-    for (const scenario of node.scenarios ?? []) {
-      const reading = latest.get(scenario.name)
-      if (!reading) {
-        items.push({
-          scenario: scenario.name,
-          expected: scenario.expected,
-          tags: scenario.tags,
-          node: node.id,
-          hue: node.hue,
-          filterKind: EVAL_FILTER_KIND.BLIND,
-        })
-        continue
-      }
-      items.push({
-        ...reading,
-        expected: scenario.expected ?? reading.expected,
-        tags: scenario.tags,
-        state: evalReviewState(reading),
-        node: node.id,
-        hue: node.hue,
-        filterKind: EVAL_FILTER_KIND.RESULT,
-      })
-    }
-  }
-  return items.sort(byNewest)
-}
-
-export function scopedEvalReviewItems(model: SessionEvals): ReviewItem[] {
-  const items: any[] = []
-  for (const node of model.nodes ?? []) {
-    const latest = new Map<string, any>()
-    for (const reading of node.evals ?? []) if (!latest.has(reading.scenario)) latest.set(reading.scenario, reading)
-    for (const scenario of node.scenarios ?? []) {
-      const reading = latest.get(scenario.name)
-      if (!reading) {
-        items.push({
-          scenario: scenario.name,
-          expected: scenario.expected,
-          tags: scenario.tags,
-          impact: scenario.impact,
-          node: node.id,
-          hue: node.hue,
-          filterKind: EVAL_FILTER_KIND.BLIND,
-        })
-        continue
-      }
-      const item = {
-        ...reading,
-        expected: scenario.expected ?? reading.expected,
-        tags: scenario.tags,
-        impact: scenario.impact,
-        state: evalReviewState(reading),
-        node: node.id,
-        hue: node.hue,
-        filterKind: EVAL_FILTER_KIND.RESULT,
-      }
-      items.push(item)
-    }
-  }
-  return items.sort(byNewest)
-}
-
-const evalItemKey = (item: any): string => `${String(item?.node ?? '')}\0${String(item?.scenario ?? '')}`
-
-function evalNeighbor(item: any, stateOf: (row: { node: string; scenario: string }) => string): EvalNeighbor {
-  return {
-    node: String(item.node),
-    scenario: String(item.scenario),
-    state: stateOf(item),
-  }
-}
-
-// `sequence` is the whole measured population in list order; `stateOf` answers only for rows whose freshness
-// was actually computed. On a focused build those are two different sets — the sequence spans the scope, the
-// states cover the selected row and its window — which is exactly why the state is looked up rather than
-// carried: a row this response does not render contributes its POSITION and nothing else.
-export function boundedEvalNeighbors(
-  sequence: { node: string; scenario: string }[],
-  node: string,
-  scenario: string,
-  stateOf: (row: { node: string; scenario: string }) => string,
-  want = 5,
-) {
-  const items = sequence
-  const key = `${node}\0${scenario}`
-  const index = items.findIndex((item) => evalItemKey(item) === key)
-  if (index < 0) return { prev: [], next: [], total: items.length, index: null, order: 'default' as const }
-  const before = index
-  const after = items.length - index - 1
-  const take = Math.min(want, before + after)
-  const nextN = Math.min(after, Math.max(Math.ceil(take / 2), take - before))
-  const prevN = Math.min(before, take - nextN)
-  return {
-    prev: items.slice(index - prevN, index).reverse().map((item) => evalNeighbor(item, stateOf)),
-    next: items.slice(index + 1, index + 1 + nextN).map((item) => evalNeighbor(item, stateOf)),
-    total: items.length,
-    index,
-    order: 'default' as const,
-  }
-}
-
-export function projectEvalDetail(
-  items: ReviewItem[],
-  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 }[]
-  } = {},
-): 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 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
-    ?? results.map((item: any) => ({ node: String(item.node), scenario: String(item.scenario) }))
-  const neighbors = boundedEvalNeighbors(sequence, node, scenario,
-    (row) => stateByKey.get(evalItemKey(row)) ?? 'empty')
-  const scope = metadata.scope ?? null
-  return {
-    scope,
-    selected,
-    history,
-    neighbors,
-    revision: revisionOf({ scope, selected, history, neighbors, summary: metadata.summary, evalRevision: metadata.evalRevision }),
-    ...(metadata.summary ? { summary: metadata.summary } : {}),
-    ...(metadata.evalRevision ? { evalRevision: metadata.evalRevision } : {}),
-  }
-}
-
-// the measured population in list order, from the freshness-free rows: a filed reading leads (newest first),
-// and the tie-breaks are the identity ones — the SAME comparison `byNewest` applies, over the only fields it
-// actually reads. Blind rows never enter, exactly as the detail's own `results` filter excludes them.
-export function measuredSequence(order: SessionEvalOrderRow[]): { node: string; scenario: string }[] {
-  return order.filter((row) => row.ts)
-    .sort((a, b) => String(b.ts ?? '').localeCompare(String(a.ts ?? ''))
-      || a.node.localeCompare(b.node) || a.scenario.localeCompare(b.scenario))
-    .map((row) => ({ node: row.node, scenario: row.scenario }))
-}
-
-// the nodes whose verdicts the response will publish: the selected row's, plus a window wide enough to
-// contain any neighbour boundedEvalNeighbors can choose (it takes at most five, split around the index).
-export function focusNodes(order: SessionEvalOrderRow[], node: string, scenario: string): string[] {
-  const sequence = measuredSequence(order)
-  const index = sequence.findIndex((row) => row.node === node && row.scenario === scenario)
-  if (index < 0) return [node]
-  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> {
-  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
-    const sourceNode = model.nodes.find((candidate) => candidate.id === node)
-    return projectEvalDetail(scopedEvalReviewItems(model), sourceNode?.evals ?? [], node, scenario, {
-      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)
-}
-
-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) => ({
-      ...scenario,
-      scenario: scenario.name,
-      node,
-      filterKind: EVAL_FILTER_KIND.UNMEASURED,
-    })),
-    ...timeline.readings.map((reading, index) => ({
-      ...reading,
-      state: evalReviewState(reading),
-      node,
-      filterKind: EVAL_FILTER_KIND.RESULT,
-      filterKey: `${EVAL_FILTER_KIND.RESULT}:${index}`,
-    })),
-    ...(timeline.dangling ?? []).map((track) => ({
-      ...track,
-      node,
-      filterKind: EVAL_FILTER_KIND.DANGLING,
-      filterKey: `${EVAL_FILTER_KIND.DANGLING}:${track.threadId}`,
-    })),
-  ]
-  const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions, defaultKind: 'all', defaultSection: '' })
-  return {
-    scope: null,
-    view: 'timeline',
-    node,
-    hasEvalFile: timeline.hasEvalFile,
-    gates: [],
-    unknown: 0,
-    ...paginateReview(items, filtered.shown, filtered, requestedPage, {
-      domain: 'evals', view: 'timeline', node, timeline, sessions: sessions.map((session) => session.id),
-    }),
-  }
-}
-
-export async function evalsReview(query: string | undefined, requestedPage: unknown, options: { view?: string } = {}) {
-  const text = String(query ?? '').trim() || EVAL_QUERY_DEFAULT
-  if (options.view === 'timeline') return timelineEvalReview(text, requestedPage)
-  const scope = readToken(text, 'scope') || null
-  if (scope) {
-    const model = await buildSessionEvals(scope)
-    if (!model) return null
-    const items = scopedEvalReviewItems(model)
-    const sessions = await listSessions()
-    const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions, defaultKind: 'all', defaultSection: '' })
-    return {
-      scope,
-      gates: model.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),
-      }),
-    }
-  }
-  if (!hasReviewSnapshot()) await getBoard()
-  const sessions = await listSessions()
-  const items = trunkEvalReviewItems(readReviewSnapshot().evalNodes)
-  const filtered = evalFilterModel(items, tokenFilterState(text, 'eval'), { sessions, defaultKind: 'all', defaultSection: '' })
-  return {
-    scope: null,
-    gates: [],
-    unknown: 0,
-    ...paginateReview(items, filtered.shown, filtered, requestedPage, {
-      domain: 'evals', items, sessions: sessions.map((session) => session.id),
-    }),
-  }
-}

package/spec-cli/src/runtime-guard.ts

@@ -1,35 +0,0 @@
-import { spawnSync } from 'node:child_process'
-
-// tmux presence is the primitive we actually depend on, so probe THAT rather than assuming by platform:
-// this also catches a bare POSIX box that simply hasn't installed tmux, not only native Windows.
-export function hasTmux(): boolean {
-  try {
-    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
-  } catch {
-    return false
-  }
-}
-
-// Pure so it is unit-testable without spawning or exiting: null = runtime OK; otherwise the stderr lines.
-// The pointer branches on platform because the honest repair differs — WSL2 on Windows (no POSIX analog at
-// all), install-tmux on a POSIX host that merely lacks it.
-export function sessionRuntimeBlock(env: { hasTmux: boolean; platform: string }): string[] | null {
-  if (env.hasTmux) return null
-  const lines = ['spex: the session runtime needs a POSIX host (tmux, bash, and unix-domain sockets).']
-  if (env.platform === 'win32') {
-    lines.push('Native Windows has no analog for these — run SpexCode under WSL2 (a real Linux kernel):')
-    lines.push('  wsl --install   # then, in the Ubuntu shell: nvm install 22 && npm i -g spexcode')
-  } else {
-    lines.push('tmux is not on PATH — install it and retry (e.g. `apt install tmux`, `brew install tmux`).')
-  }
-  return lines
-}
-
-// Called at the top of the session-launching command path (`spex serve`). Exits 69 (EX_UNAVAILABLE: a
-// required support program does not exist) — a distinct, honest code, not a swallowed error or a stacktrace.
-export function assertSessionRuntime(): void {
-  const block = sessionRuntimeBlock({ hasTmux: hasTmux(), platform: process.platform })
-  if (!block) return
-  for (const line of block) console.error(line)
-  process.exit(69)
-}

package/spec-cli/src/runtime-ownership.ts

@@ -1,88 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import { spawn } from 'node:child_process'
-import { closeSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { repoRoot } from './git.js'
-import { readJsonConfig, runtimeRoot } from './layout.js'
-import { processStartToken, writeDetachedRuntimeReceipt, type ProcessIdentity } from './process-identity.js'
-
-export type BackendInstanceRecord = {
-  version: 1
-  instanceId: string
-  pid: number
-  startToken: string
-  projectRoot: string
-  startedAt: string
-}
-
-const backendInstancesDir = () => join(runtimeRoot(), 'backend-instances')
-const backendInstancePath = (instanceId: string) => join(backendInstancesDir(), `${instanceId}.json`)
-
-const atomicJson = (path: string, value: unknown) => {
-  mkdirSync(dirname(path), { recursive: true })
-  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`
-  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 })
-  renameSync(tmp, path)
-}
-
-export function readBackendInstanceRecords(root = repoRoot()): BackendInstanceRecord[] {
-  let names: string[]
-  try { names = readdirSync(backendInstancesDir()) } catch { return [] }
-  return names.flatMap((name) => {
-    try {
-      const rec = readJsonConfig(join(backendInstancesDir(), name)) as BackendInstanceRecord
-      return rec?.version === 1 && rec.projectRoot === root ? [rec] : []
-    } catch { return [] }
-  })
-}
-
-export function registerBackendInstance(instanceId: string, pid = process.pid, root = repoRoot()): BackendInstanceRecord {
-  const startToken = processStartToken(pid)
-  if (!startToken) throw new Error(`cannot identify backend supervisor PID ${pid}`)
-  const record: BackendInstanceRecord = { version: 1, instanceId, pid, startToken, projectRoot: root, startedAt: new Date().toISOString() }
-  atomicJson(backendInstancePath(instanceId), record)
-  return record
-}
-
-export function unregisterBackendInstance(instanceId: string, pid = process.pid): void {
-  try {
-    const record = readJsonConfig(backendInstancePath(instanceId)) as BackendInstanceRecord
-    if (record.instanceId === instanceId && record.pid === pid && record.startToken === processStartToken(pid)) rmSync(backendInstancePath(instanceId), { force: true })
-  } catch { /* not ours / already removed */ }
-}
-
-export function spawnDetachedRuntime(opts: {
-  cwd: string
-  logFile: string
-  pidFile: string
-  receiptFile: string
-  command: string
-  args: string[]
-  env?: NodeJS.ProcessEnv
-}): ProcessIdentity {
-  mkdirSync(dirname(opts.logFile), { recursive: true })
-  mkdirSync(dirname(opts.pidFile), { recursive: true })
-  const log = openSync(opts.logFile, 'a', 0o600)
-  let child: ReturnType<typeof spawn>
-  try {
-    child = spawn(opts.command, opts.args, {
-      cwd: opts.cwd,
-      env: opts.env ?? process.env,
-      detached: true,
-      stdio: ['ignore', log, log],
-    })
-  } finally { closeSync(log) }
-  child.once('error', () => {})
-  if (!child.pid) throw new Error(`could not spawn detached shared runtime: ${opts.command}`)
-  child.unref()
-  try {
-    const identity = writeDetachedRuntimeReceipt(child.pid, opts.receiptFile)
-    writeFileSync(opts.pidFile, `${child.pid}\n`, { mode: 0o600 })
-    return { pid: identity.pid, startToken: identity.startToken }
-  } catch (error) {
-    try { child.kill('SIGTERM') } catch { /* exact just-spawned child already exited */ }
-    rmSync(opts.pidFile, { force: true })
-    rmSync(opts.receiptFile, { force: true })
-    throw error
-  }
-}

package/spec-cli/src/search.bench.mjs

@@ -1,80 +0,0 @@
-// throwaway benchmark harness for spec-search — drives the REAL `spex spec search --json` over the holdout
-// cases and reports recall@1, recall@3, MRR. The cases live in the node's eval.md.
-//
-// Labels are node LEAF names, matched with the same de-collision rule the loader applies (specs.ts reId):
-// a returned id matches a label if it IS the label or ends with `_<label>` — so a bare leaf keeps matching
-// after collision-qualification renames it (e.g. a colliding `probe` leaf → `a_probe`). A label may
-// also be written pre-qualified to pin one collision branch.
-import { execFileSync } from 'node:child_process'
-import { fileURLToPath } from 'node:url'
-import { dirname, join } from 'node:path'
-
-const BIN = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'spex.mjs')
-
-const CASES = [
-  ['exit-cleanup', "does /exit remove the session's worktree and tmux, or just orphan them?", ['session-console']],
-  ['owner-at-edit', 'how does an agent learn which spec governs a file it just edited?', ['spec-of-file']],
-  ['main-block', 'what stops an agent from committing or merging straight into main?', ['main-guard']],
-  ['main-escape', 'the escape hatch that lets seeding run on the main branch', ['main-guard']],
-  ['inter-agent-msg', 'how do two running agent sessions send messages to each other?', ['agent-reply-channel', 'comms']],
-  ['search-hidden-node', 'keyboard shortcut to find a node hidden inside a collapsed subtree', ['keyboard-nav']],
-  ['session-order', 'how is the order of sessions in the session list decided?', ['session-console']],
-  ['node-status', 'what makes a node show as pending vs active vs merged vs drift?', ['spec-node-states']],
-  ['dashboard-backend', 'how does the dashboard reach the backend API and on which port?', ['api-endpoint']],
-  ['loss-measured', "how is a node's loss measured and its scenarios scored?", ['eval-core']],
-  ['launch-injection', "what context gets injected into a freshly launched agent's prompt?", ['injected-context']],
-  ['read-before-code', 'the one-shot nudge that makes an agent read its spec before touching code', ['spec-first']],
-  ['hot-reload', 'zero-downtime backend reload without dropping connections', ['supervisor']],
-  ['many-owners', 'can several specs own the same code file, and what happens if too many do?', ['governed-related']],
-  ['active-spec-search', 'an injected sub-agent that searches specs for the agent, the spec analog of Explore', ['spec-search']],
-  ['declare-done', 'how does a worker declare it is done', ['state']],
-]
-
-// de-collision-aware label match: exact id, or the id's trailing `_`-suffix is the label.
-const matches = (id, label) => id === label || id.endsWith('_' + label)
-
-let r1 = 0, r3 = 0, mrr = 0
-const rows = []
-for (const [name, query, expect] of CASES) {
-  const out = execFileSync('node', [BIN, 'spec', 'search', query, '--json', '--limit', '10'], { encoding: 'utf8' })
-  const results = JSON.parse(out)
-  const ids = results.map((x) => x.id)
-  const rank = ids.findIndex((id) => expect.some((label) => matches(id, label))) + 1   // 1-based; 0 = not found
-  const hit1 = rank === 1
-  const hit3 = rank >= 1 && rank <= 3
-  if (hit1) r1++
-  if (hit3) r3++
-  if (rank >= 1) mrr += 1 / rank
-  rows.push({ name, rank: rank || '—', top: ids.slice(0, 3).join(', '), expect: expect.join('|') })
-}
-const n = CASES.length
-for (const row of rows) {
-  const mark = row.rank === 1 ? '✓1' : (typeof row.rank === 'number' && row.rank <= 3 ? '·3' : (row.rank === '—' ? '✗ ' : `·${row.rank}`))
-  console.log(`${mark} ${row.name.padEnd(20)} want=${row.expect.padEnd(22)} rank=${String(row.rank).padStart(2)}  top3: ${row.top}`)
-}
-
-// CJK-positive: the corpus is mostly English but a few nodes carry Chinese prose — the root `spexcode`
-// node's body repeats 节点 throughout. A per-CJK-character tokenizer must let a Chinese content word reach
-// that node; `spex spec search "节点"` MUST return `spexcode` in results (the bug: the old tokenizer split on
-// [^a-z0-9]+ and discarded all CJK, so every Chinese query dead-ended at zero results).
-const cjkPos = JSON.parse(execFileSync('node', [BIN, 'spec', 'search', '节点', '--json', '--limit', '10'], { encoding: 'utf8' }))
-const cjkPosRank = cjkPos.map((x) => x.id).findIndex((id) => matches(id, 'spexcode')) + 1
-const cjkPosPass = cjkPosRank >= 1
-console.log(`${cjkPosPass ? `✓${cjkPosRank}` : '✗ '} cjk-positive          want=spexcode(节点)                rank=${cjkPosRank || '—'}  top3: ${cjkPos.slice(0, 3).map((x) => x.id).join(', ')}`)
-
-// zero-result fail-loud regression: a CJK query whose characters appear NOWHERE in the corpus (会/话) returns
-// nothing, and the zero-result message must still carry the corpus-is-English translate-and-retry fact
-// (fail-loud) plus the browse-all next step — CJK support does not suppress the honest zero-result route.
-// (No nearest titles: a CJK query has nothing to be lexically near.)
-const cjk = execFileSync('node', [BIN, 'spec', 'search', '会话'], { encoding: 'utf8' })
-const cjkPass = cjk.includes('corpus is English') && cjk.includes('spex graph')
-console.log(`${cjkPass ? '✓ ' : '✗ '} cjk-zero-result       want=corpus-is-English + spex-tree  ${cjkPass ? 'both present' : 'MISSING: ' + cjk.trim()}`)
-
-// zero-result typo routing: an English typo that matches nothing must surface the nearest node titles
-// (per-word edit distance) plus the browse-all next step, so a typo routes forward instead of dead-ending.
-const typo = execFileSync('node', [BIN, 'spec', 'search', 'kyeboard'], { encoding: 'utf8' })
-const typoPass = typo.includes('nearest titles') && typo.includes('keyboard-nav') && typo.includes('spex graph')
-console.log(`${typoPass ? '✓ ' : '✗ '} typo-zero-result      want=nearest-titles(keyboard-nav) + spex-tree  ${typoPass ? 'both present' : 'MISSING: ' + typo.trim()}`)
-
-console.log('—'.repeat(72))
-console.log(`recall@1 = ${r1}/${n} = ${(r1 / n).toFixed(3)}   recall@3 = ${r3}/${n} = ${(r3 / n).toFixed(3)}   MRR = ${(mrr / n).toFixed(3)}   cjk-positive = ${cjkPosPass ? 'PASS' : 'FAIL'}   cjk-hint = ${cjkPass ? 'PASS' : 'FAIL'}   typo-route = ${typoPass ? 'PASS' : 'FAIL'}`)

package/spec-cli/src/search.ts

@@ -1,63 +0,0 @@
-import { loadSpecsLite } from './specs.js'
-import { rankDocs, type RankInput } from './ranker.js'
-
-export type SearchResult = { id: string; title: string; path: string; score: number; snippet: string }
-export type SearchStats = { nodes: number; tokens: number; ms: number }
-
-// zero-result fallback: nearest node titles by per-word edit distance over title+id — the lightweight
-// string distance that routes a typo'd query to a next step. Each query word takes its best normalised
-// Levenshtein similarity against any title/id word (≥0.5, so unrelated words don't accumulate), then the
-// words sum. Same loadSpecsLite read as the ranker; deliberately NOT part of rankDocs scoring (this
-// tolerates typos, the ranker must not).
-export function nearestTitles(query: string, n = 3): { id: string; title: string }[] {
-  const words = (s: string) => s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 1)
-  const lev = (a: string, b: string) => {
-    const dp = Array.from({ length: b.length + 1 }, (_, i) => i)
-    for (let i = 1; i <= a.length; i++) {
-      let prev = dp[0]
-      dp[0] = i
-      for (let j = 1; j <= b.length; j++) {
-        const cur = dp[j]
-        dp[j] = Math.min(dp[j] + 1, dp[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1))
-        prev = cur
-      }
-    }
-    return dp[b.length]
-  }
-  const qws = words(query)
-  if (!qws.length) return []   // nothing to be "near" (e.g. a pure-CJK query) — the caller still points at spex graph
-  return loadSpecsLite()
-    .map((s) => {
-      const tws = [...new Set(words(`${s.title} ${s.id}`))]
-      let score = 0
-      for (const q of qws) {
-        let best = 0
-        for (const t of tws) best = Math.max(best, 1 - lev(q, t) / Math.max(q.length, t.length))
-        if (best >= 0.5) score += best
-      }
-      return { id: s.id, title: s.title, score }
-    })
-    .filter((s) => s.score > 0)
-    .sort((a, b) => b.score - a.score)
-    .slice(0, n)
-    .map(({ id, title }) => ({ id, title }))
-}
-
-export async function searchSpecs(query: string, opts: { limit?: number; onStats?: (s: SearchStats) => void } = {}): Promise<SearchResult[]> {
-  const t0 = performance.now()
-  // pre-sort by (shorter id, then id): rankDocs sorts stably, so for equal-scored nodes this IS the tiebreak.
-  const nodes = loadSpecsLite()
-    .slice()
-    .sort((a, b) => a.id.length - b.id.length || a.id.localeCompare(b.id))
-  const inputs: RankInput<(typeof nodes)[number]>[] = nodes.map((s) => ({
-    ref: s, name: `${s.title} ${s.id}`, desc: s.desc, body: s.body,
-  }))
-  const out = rankDocs(query, inputs, { limit: opts.limit }).map((r) => ({
-    id: r.ref.id, title: r.ref.title, path: r.ref.path, score: r.score, snippet: r.snippet,
-  }))
-  if (opts.onStats) {
-    const tokens = inputs.reduce((a, i) => a + `${i.name} ${i.desc} ${i.body}`.split(/[^a-z0-9]+/i).filter(Boolean).length, 0)
-    opts.onStats({ nodes: inputs.length, tokens, ms: performance.now() - t0 })
-  }
-  return out
-}