spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/reviews.js

@@ -0,0 +1,350 @@
+import { createHash } from 'node:crypto';
+import { listSessions } from './sessions.js';
+import { getBoard, getBoardForForgeRevision } from './graphCache.js';
+import { buildSessionEvals } from '@spexcode/spec-eval/sessioneval';
+import { evalTimeline } from '@spexcode/spec-eval/evaltab';
+import { issuesEnabled as issuesEnabledForReview } from './localIssues.js';
+import { issueStores as issueStoresForReview } from './issues.js';
+import { hasReviewSnapshot, readReviewSnapshot } from '@spexcode/spec-core';
+import { residentForgeRevision, residentForgeState } from '@spexcode/spec-forge/resident';
+import { EVAL_FILTER_KIND, evalFilterModel, evalReviewState, issueFilterModel, tokenFilterState } from '@spexcode/spec-core/review';
+import { EVAL_QUERY_DEFAULT, ISSUE_QUERY_DEFAULT, readToken } from '@spexcode/spec-core/review';
+export const REVIEW_PER_PAGE = 25;
+const revisionOf = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export function reviewPageNumber(value) {
+    const raw = typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : Number.NaN;
+    return Number.isSafeInteger(raw) && raw > 0 ? raw : 1;
+}
+function responseModel(model) {
+    const facets = Object.fromEntries(Object.entries(model.facets ?? {}).map(([key, raw]) => {
+        const facet = raw;
+        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) => ({
+                    value: String(option.value ?? ''),
+                    ...(option.label != null ? { label: String(option.label) } : {}),
+                    ...(Number.isFinite(option.count) ? { count: Number(option.count) } : {}),
+                })),
+            }];
+    }));
+    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) => ({
+            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(source, shown, model, requestedPage, revisionInputs) {
+    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({ page, source: revisionInputs }),
+        ...responseModel(model),
+    };
+}
+const issueOrder = (a, b) => String(b.created ?? '').localeCompare(String(a.created ?? ''))
+    || String(a.id ?? '').localeCompare(String(b.id ?? ''));
+export async function issuesReview(query, requestedPage) {
+    // 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, b) => 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) {
+    const items = [];
+    for (const node of nodes ?? []) {
+        const latest = new Map();
+        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) {
+    const items = [];
+    for (const node of model.nodes ?? []) {
+        const latest = new Map();
+        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) => `${String(item?.node ?? '')}\0${String(item?.scenario ?? '')}`;
+function evalNeighbor(item, stateOf) {
+    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, scenario, stateOf, 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' };
+    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',
+    };
+}
+export function projectEvalDetail(items, historySource, node, scenario, metadata = {}) {
+    const results = items.filter((item) => item.filterKind === EVAL_FILTER_KIND.RESULT);
+    const selected = results.find((item) => evalItemKey(item) === `${node}\0${scenario}`) ?? null;
+    const availability = selected
+        ? 'measured'
+        : items.some((item) => evalItemKey(item) === `${node}\0${scenario}` && item.filterKind === EVAL_FILTER_KIND.BLIND)
+            ? 'unmeasured'
+            : 'missing';
+    const history = historySource.filter((reading) => String(reading.scenario) === scenario);
+    const stateByKey = new Map(results.map((item) => [evalItemKey(item), String(item.state ?? evalReviewState(item))]));
+    const sequence = metadata.sequence
+        ?? results.map((item) => ({ 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;
+    const requestedScope = metadata.requestedScope ?? scope;
+    const scopeFallback = metadata.scopeFallback ?? null;
+    return {
+        scope,
+        requestedScope,
+        scopeFallback,
+        availability,
+        selected,
+        history,
+        neighbors,
+        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 } : {}),
+    };
+}
+// 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) {
+    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, node, scenario) {
+    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)])];
+}
+async function trunkEvalDetailReview(node, scenario, metadata = {}) {
+    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, scenario, scope) {
+    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 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) } : {}),
+        });
+    }
+    return trunkEvalDetailReview(node, scenario);
+}
+export function timelineEvalReviewItems(timeline, node) {
+    const declared = new Set(timeline.scenarios.map((scenario) => scenario.name));
+    const latest = new Map();
+    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,
+        })),
+        ...[...latest.values()].map((reading) => ({
+            ...reading,
+            state: evalReviewState(reading),
+            node,
+            filterKind: EVAL_FILTER_KIND.RESULT,
+            filterKey: `${EVAL_FILTER_KIND.RESULT}:${reading.scenario}`,
+        })),
+        ...(timeline.dangling ?? []).map((track) => ({
+            ...track,
+            node,
+            filterKind: EVAL_FILTER_KIND.DANGLING,
+            filterKey: `${EVAL_FILTER_KIND.DANGLING}:${track.threadId}`,
+        })),
+    ];
+}
+async function timelineEvalReview(text, requestedPage) {
+    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,
+        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, requestedPage, options = {}) {
+    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: [],
+            unknown: model.nodes.reduce((count, node) => count + (node.unknownCoverage?.length ?? 0), 0),
+            summary: model.summary,
+            evalRevision: model.evalRevision,
+            ...paginateReview(items, filtered.shown, filtered, requestedPage, {
+                domain: 'evals', scope, query: text, gates: [], summary: model.summary,
+                evalRevision: model.evalRevision, 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/node_modules/@spexcode/spec-cli/dist/runtime-guard.d.ts

@@ -0,0 +1,6 @@
+export declare function hasTmux(): boolean;
+export declare function sessionRuntimeBlock(env: {
+    hasTmux: boolean;
+    platform: string;
+}): string[] | null;
+export declare function assertSessionRuntime(): void;

package/node_modules/@spexcode/spec-cli/dist/runtime-guard.js

@@ -0,0 +1,37 @@
+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() {
+    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) {
+    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() {
+    const block = sessionRuntimeBlock({ hasTmux: hasTmux(), platform: process.platform });
+    if (!block)
+        return;
+    for (const line of block)
+        console.error(line);
+    process.exit(69);
+}

package/node_modules/@spexcode/spec-cli/dist/runtime-ownership.d.ts

@@ -0,0 +1,21 @@
+import { type ProcessIdentity } from '@spexcode/spec-core';
+export type BackendInstanceRecord = {
+    version: 1;
+    instanceId: string;
+    pid: number;
+    startToken: string;
+    projectRoot: string;
+    startedAt: string;
+};
+export declare function readBackendInstanceRecords(root?: string): BackendInstanceRecord[];
+export declare function registerBackendInstance(instanceId: string, pid?: number, root?: string): BackendInstanceRecord;
+export declare function unregisterBackendInstance(instanceId: string, pid?: number): void;
+export declare function spawnDetachedRuntime(opts: {
+    cwd: string;
+    logFile: string;
+    pidFile: string;
+    receiptFile: string;
+    command: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+}): ProcessIdentity;

package/node_modules/@spexcode/spec-cli/dist/runtime-ownership.js

@@ -0,0 +1,84 @@
+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 '@spexcode/spec-core';
+import { readJsonConfig, runtimeRoot } from '@spexcode/spec-core';
+import { processStartToken, writeDetachedRuntimeReceipt } from '@spexcode/spec-core';
+const backendInstancesDir = () => join(runtimeRoot(), 'backend-instances');
+const backendInstancePath = (instanceId) => join(backendInstancesDir(), `${instanceId}.json`);
+const atomicJson = (path, value) => {
+    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()) {
+    let names;
+    try {
+        names = readdirSync(backendInstancesDir());
+    }
+    catch {
+        return [];
+    }
+    return names.flatMap((name) => {
+        try {
+            const rec = readJsonConfig(join(backendInstancesDir(), name));
+            return rec?.version === 1 && rec.projectRoot === root ? [rec] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function registerBackendInstance(instanceId, pid = process.pid, root = repoRoot()) {
+    const startToken = processStartToken(pid);
+    if (!startToken)
+        throw new Error(`cannot identify backend supervisor PID ${pid}`);
+    const record = { version: 1, instanceId, pid, startToken, projectRoot: root, startedAt: new Date().toISOString() };
+    atomicJson(backendInstancePath(instanceId), record);
+    return record;
+}
+export function unregisterBackendInstance(instanceId, pid = process.pid) {
+    try {
+        const record = readJsonConfig(backendInstancePath(instanceId));
+        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) {
+    mkdirSync(dirname(opts.logFile), { recursive: true });
+    mkdirSync(dirname(opts.pidFile), { recursive: true });
+    const log = openSync(opts.logFile, 'a', 0o600);
+    let child;
+    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/node_modules/@spexcode/spec-cli/dist/search.bench.d.mts

@@ -0,0 +1 @@
+export {};

package/node_modules/@spexcode/spec-cli/dist/search.bench.mjs

@@ -0,0 +1,75 @@
+// 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/node_modules/@spexcode/spec-cli/dist/search.d.ts

@@ -0,0 +1,20 @@
+export type SearchResult = {
+    id: string;
+    title: string;
+    path: string;
+    score: number;
+    snippet: string;
+};
+export type SearchStats = {
+    nodes: number;
+    tokens: number;
+    ms: number;
+};
+export declare function nearestTitles(query: string, n?: number): {
+    id: string;
+    title: string;
+}[];
+export declare function searchSpecs(query: string, opts?: {
+    limit?: number;
+    onStats?: (s: SearchStats) => void;
+}): Promise<SearchResult[]>;

package/node_modules/@spexcode/spec-cli/dist/search.js

@@ -0,0 +1,61 @@
+import { loadSpecsLite } from '@spexcode/spec-core';
+import { rankDocs } from './ranker.js';
+// 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, n = 3) {
+    const words = (s) => s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 1);
+    const lev = (a, b) => {
+        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, opts = {}) {
+    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 = 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;
+}