@spexcode/spec-cli 0.6.7 → 0.6.8

package/dist/delivery-lock.js

@@ -0,0 +1,58 @@
+import { mkdirSync, openSync, readFileSync, unlinkSync, writeSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { runtimeRoot } from '@spexcode/spec-core';
+const lockRoot = () => join(runtimeRoot(), '.delivery-locks');
+const lockPath = (id) => join(lockRoot(), `${id}.lock`);
+const pause = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+async function acquire(id, timeoutMs) {
+    mkdirSync(lockRoot(), { recursive: true });
+    const path = lockPath(id), deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const fd = openSync(path, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                unlinkSync(path);
+            }
+            catch { /* a dead owner may have reclaimed it */ } };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let owner = 0;
+            try {
+                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
+            }
+            catch { /* creator/releaser race */ }
+            if (owner && owner !== process.pid) {
+                try {
+                    process.kill(owner, 0);
+                }
+                catch {
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch { /* race */ }
+                    ;
+                    continue;
+                }
+            }
+            if (Date.now() >= deadline)
+                throw new Error(`delivery queue ${id}: timed out waiting for transaction lock`);
+            await pause(25);
+        }
+    }
+}
+/** Serialize delivery claims without making the transport itself part of SQLite. */
+export async function withDeliveryLocks(rawIds, body, index = 0, ids = [...new Set(rawIds)].sort()) {
+    if (index >= ids.length)
+        return body();
+    const release = await acquire(ids[index], 30_000);
+    try {
+        return await withDeliveryLocks(ids, body, index + 1, ids);
+    }
+    finally {
+        release();
+    }
+}

package/dist/doctor.js

@@ -3,9 +3,10 @@ import { join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
-import { loadSystemConfig, loadSkillConfig, loadSpecs } from '@spexcode/spec-core';
-import { runtimeRoot, treeSlotDir, envSessionId, readAliasedRawRecord, mainCheckout, readJsonConfig } from '@spexcode/spec-core';
+import { loadSystemConfig, loadSkillConfig, loadAgentConfig, loadSpecs } from '@spexcode/spec-core';
+import { treeSlotDir, envSessionId, readAliasedRawRecord, mainCheckout, readJsonConfig } from '@spexcode/spec-core';
 import { loadConfig } from './lint.js';
+import { GENERATED_MARK } from './harness.js';
 import { trackedSourceFiles } from './source-files.js';
 import { gitBinary } from '@spexcode/spec-core';
 // this file lives at <pkgRoot>/src/self.ts, so `..` is the package root — the same derivation init.ts/
@@ -211,6 +212,25 @@ function manifestScripts(text) {
     }
     return [...out];
 }
+// which EVENTS the manifest actually binds. A tree can carry handlers and still be ungoverned in the way
+// that matters, because a handler answers an event and the lifecycle rides on specific ones.
+function manifestEvents(text) {
+    const out = new Set();
+    for (const line of text.split('\n')) {
+        const f = line.split('\t');
+        if (f.length >= 4 && f[0])
+            out.add(f[0]);
+    }
+    return out;
+}
+// THE LIFECYCLE EVENTS, and why they are named here rather than derived from an adapter's full event list.
+// A tree that binds no turn-end event has a shim, a manifest, and readable handlers — every check above it
+// passes — and still cannot report that its agent stopped: the record keeps whatever state it last held and
+// a dead turn still shows as running. That is not hypothetical; a deployment whose `.config` predated
+// the stop-gate node hit exactly this, and nothing in the diagnosis said so. Stop is the gate; StopFailure
+// is the failed-turn writer; PostToolUse is the freshness mark. Missing any of them is a distinct break
+// from "no manifest", and it is the one a passing installation can hide.
+const LIFECYCLE_EVENTS = ['Stop', 'StopFailure', 'PostToolUse'];
 // the bundle's declared name, from plugin.json (root or the .claude-plugin/ convention), or null when none.
 function pluginName(dir) {
     for (const p of [join(dir, 'plugin.json'), join(dir, '.claude-plugin', 'plugin.json')]) {
@@ -263,6 +283,12 @@ async function doubleDeliveryReport(base) {
     catch {
         return [];
     } })();
+    const ourAgents = (() => { try {
+        return loadAgentConfig().map((c) => c.name);
+    }
+    catch {
+        return [];
+    } })();
     const L = [];
     const line = (k, v) => L.push(`  ${k.padEnd(16)}: ${v}`);
     let conflict = false;
@@ -282,6 +308,13 @@ async function doubleDeliveryReport(base) {
             ...(looseDispatch ? [`loose ${rel(shimFile)}`] : []),
             ...bundles.filter((b) => b.hooksToDispatch).map((b) => `plugin "${b.name}" (${b.scope})`),
         ];
+        // a DIFFERENT collision from the double-delivery channels below: a skill/agent path a live spec node
+        // names, already occupied by a file the user wrote (no GENERATED_MARK). materialize skips those, so the
+        // node silently never reaches this harness — worth naming here, where somebody asks "do we clash?".
+        const userOwned = [
+            ...(looseSkillDir ? ourSkills.map((s) => join(looseSkillDir, s, 'SKILL.md')) : []),
+            ...((dir) => dir ? ourAgents.map((a) => join(dir, `${a}.md`)) : [])(h.agentDir(base)),
+        ].filter((f) => existsSync(f) && !read(f).includes(GENERATED_MARK));
         // channel 2 — same-named skill in loose skillDir AND a bundle's skills dir
         const skillHits = [];
         for (const s of ourSkills) {
@@ -302,6 +335,7 @@ async function doubleDeliveryReport(base) {
             line('  plugin', `"${b.name}" (${b.scope}) — ${b.dir}`);
         line('hooks→dispatch', `${hookSrc.length}${hookSrc.length > 1 ? '  (>1 → CONFLICT): ' + hookSrc.join(', ') : hookSrc.length === 1 ? '  (single — ok)' : '  (none wired)'}`);
         line('skill shadowing', skillHits.length ? `CONFLICT: ${skillHits.join(', ')}` : 'none');
+        line('your files kept', userOwned.length ? `${userOwned.map(rel).join(', ')} — yours (no spexcode stamp), so the same-named spec node is NOT delivered here` : 'none');
         L.push('');
     }
     if (conflict) {
@@ -423,31 +457,39 @@ async function doctor() {
         const shim = read(h.shimFile(base));
         line(`${h.id} shim`, /dispatch\.sh/.test(shim) ? `wired (${h.shimFile(base).replace(base + '/', '')})` : 'NOT wired (no dispatch shim)');
     }
-    // manifest resolution mirrors dispatch.sh: this tree's materialize slot first, then the legacy global file
-    // (a pre-slot tree's migration-window fallback) — so the doctor reads exactly what a dispatch would.
+    // Manifest resolution mirrors dispatch.sh: only the current tree slot is executable.
     let manifestText = '';
     let manifestHome = 'tree slot';
     try {
         manifestText = read(join(treeSlotDir(base), 'hooks-manifest'));
     }
     catch { /* non-git / no store */ }
-    if (!manifestText) {
-        try {
-            manifestText = read(join(runtimeRoot(base), 'hooks-manifest'));
-            manifestHome = 'legacy global file (pre-slot materialize — re-run `spex materialize`)';
-        }
-        catch { /* neither */ }
+    const manifestFile = (() => { try {
+        return join(treeSlotDir(base), 'hooks-manifest');
     }
+    catch {
+        return null;
+    } })();
+    const manifestPresent = !!manifestFile && existsSync(manifestFile);
     if (!manifestText) {
-        line('manifest', 'MISSING from the global store — materialize never ran (hooks fire but find no manifest)');
+        // ABSENT and EMPTY are different breaks and want different repairs, and the dispatcher cannot tell them
+        // apart at all: a missing file is a loud exit 78, an empty one dispatches nothing and exits 0 in silence.
+        line('manifest', manifestPresent
+            ? 'EMPTY in the current tree slot — materialize ran and bound ZERO handlers: this tree has no hook nodes, so every event dispatches nothing and exits 0 in silence'
+            : 'MISSING from the current tree slot — materialize must run before hooks can execute');
     }
     else {
         const scripts = manifestScripts(manifestText);
         const missing = scripts.filter((s) => !existsSync(join(base, s)));
+        const events = manifestEvents(manifestText);
         line('manifest', `${scripts.length} handler(s) in the ${manifestHome}`);
         line('handlers', missing.length === 0 ? 'all readable in the worktree' : `${missing.length} MISSING in the worktree → those hooks SILENTLY NO-OP:`);
         for (const m of missing)
             L.push(`      ✗ ${m}`);
+        const unbound = LIFECYCLE_EVENTS.filter((event) => !events.has(event));
+        line('lifecycle events', unbound.length === 0
+            ? `${LIFECYCLE_EVENTS.join(', ')} all bound`
+            : `${unbound.join(', ')} NOT bound → this tree cannot report its own turn ending; the record keeps its last state and a stopped agent still shows as running`);
     }
     // codex trust
     const trustPresent = codexCfg.includes(`# spexcode:trust:${base}`);

package/dist/execution-trace.d.ts

@@ -19,6 +19,7 @@ export type ExecutionTrace = Readonly<{
 type ExportLoader = (threadId: string) => string;
 export declare function codexRolloutPath(threadId: string, root?: string): string | null;
 export declare function readCodexExecutionTrace(threadId: string, turn: ExecutionTurn | null, root?: string): ExecutionTrace;
+export declare function claudeTranscriptPath(threadId: string, root?: string): string | null;
 export declare function readProjectJsonlExecutionTrace(threadId: string, turn: ExecutionTurn | null, root?: string): ExecutionTrace;
 export declare function readSessionJsonlExecutionTrace(threadId: string, turn: ExecutionTurn | null, root?: string): ExecutionTrace;
 export declare function readLocalStoreExecutionTrace(threadId: string, turn: ExecutionTurn | null, root?: string, load?: ExportLoader): ExecutionTrace;

package/dist/execution-trace.js

@@ -359,7 +359,7 @@ export function readCodexExecutionTrace(threadId, turn, root = codexSessionsDir(
     return readIncremental(codexRolloutPath(threadId, root), applyRolloutEvent, turn);
 }
 const projectTranscriptRoot = () => join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects');
-function projectJsonlPath(threadId, root = projectTranscriptRoot()) {
+export function claudeTranscriptPath(threadId, root = projectTranscriptRoot()) {
     for (const project of children(root)) {
         const path = join(root, project, `${threadId}.jsonl`);
         try {
@@ -371,7 +371,7 @@ function projectJsonlPath(threadId, root = projectTranscriptRoot()) {
     return null;
 }
 export function readProjectJsonlExecutionTrace(threadId, turn, root = projectTranscriptRoot()) {
-    return readIncremental(projectJsonlPath(threadId, root), applyProjectJsonlEvent, turn);
+    return readIncremental(claudeTranscriptPath(threadId, root), applyProjectJsonlEvent, turn);
 }
 const sessionJsonlRoot = () => join(process.env.SPEXCODE_PI_AGENT_DIR || join(homedir(), '.pi', 'agent'), 'sessions');
 function sessionJsonlPath(threadId, root = sessionJsonlRoot()) {

package/dist/gateway-hub.js

@@ -11,6 +11,7 @@
 //                                       mounted, an explicit text/html GET gets the Projects UI instead
 //   PUT|DELETE /projects/admin-password admin: set/clear the admin password
 //   PUT|DELETE /projects/:id/password   admin: set/clear one project's password
+//   DELETE /projects/:id                host extension: high-friction catalog registration removal
 //   /p/:projectId/login|logout          project session for that project
 //   ANY /p/:projectId/*  (+ WS upgrade) authorized → proxied, prefix-stripped, to that project's backend
 // Authorization never trusts the cookie's name or Path — the token's projectId claim is validated against
@@ -332,7 +333,7 @@ export function startHubGateway(opts) {
         host: opts.host,
         label: opts.label ?? 'hub gateway',
         cleanup: opts.onBindFail,
-        ready: `[hub] multi-project gateway on ${scheme}://${opts.host ?? '0.0.0.0'}:${port} — /projects + /p/:projectId/*`,
+        ready: (actualPort) => `[hub] multi-project gateway on ${scheme}://${opts.host ?? '0.0.0.0'}:${actualPort} — /projects + /p/:projectId/*`,
     });
     return server;
 }

package/dist/gateway.js

@@ -181,9 +181,12 @@ export function startGateway(opts) {
     const scheme = secure ? 'https' : 'http';
     const label = opts.label ?? 'public mode';
     const gate = isLoopback ? '' : ` — ${gated ? 'password-gated' : 'OPEN (no password)'}`;
-    const ready = [...(opts.readyLines ?? []), `[gateway] ${label} on ${scheme}://${isLoopback ? 'localhost' : (opts.host ?? '0.0.0.0')}:${opts.publicPort}${gate}, proxying /api to :${opts.upstreamPort}`];
-    if (!secure && !isLoopback && !opts.host)
-        ready.push('[gateway] (TLS off — --http)');
+    const ready = (port) => {
+        const lines = [...(opts.readyLines ?? []), `[gateway] ${label} on ${scheme}://${isLoopback ? 'localhost' : (opts.host ?? '0.0.0.0')}:${port}${gate}, proxying /api to :${opts.upstreamPort}`];
+        if (!secure && !isLoopback && !opts.host)
+            lines.push('[gateway] (TLS off — --http)');
+        return lines;
+    };
     // a busy public port is a hard, loud, non-zero exit — the SAME contract as the supervisor's proxy
     // (see [[spec-cli]] / listen.ts), so `spex serve` and `spex serve ui` fail a port clash identically.
     listenOrExit(server, opts.publicPort, { host: opts.host, label: opts.label ?? 'gateway', cleanup: opts.onBindFail, ready });

package/dist/graphCache.js

@@ -11,6 +11,7 @@ import { residentForgeState } from '@spexcode/spec-forge/resident';
 import { resolveProjectIdentity } from '@spexcode/spec-core';
 import { readReviewSnapshot } from '@spexcode/spec-core';
 import { sessionEvalProjection } from '@spexcode/spec-eval/sessioneval';
+import { resolveDatabasePath } from '@spexcode/session-selflaunch';
 const DEBUG = process.env.SPEXCODE_BOARD_DEBUG === '1';
 function textOrNull(path) {
     try {
@@ -128,6 +129,28 @@ function strictSpecTreeRevision(wtPath) {
     }
     return parts.sort().join('\n');
 }
+// The canonical session database ([[production-cutin]]) is a board input exactly like the runtime envelope:
+// lifecycle status lives there, and ANY process may commit to it — a hook's `spex internal session-state`, a CLI
+// declaration, the backend's own routes. Its file identity folds into the session revision, so a commit no leaf
+// pushed (graph-stream's `session-db` leaf held or disabled) is still a moved revision that the patrol answers
+// with the sessions splice. journal_mode=delete rewrites the file in place on every commit, so this is the same
+// strict stat contract as the `.spec` walk: ctime catches a same-size rewrite, ENOENT is a legitimate fresh
+// store, and every other read failure is loud.
+function strictFileRevision(path) {
+    try {
+        const stat = statSync(path);
+        return `${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}
+function sessionDatabaseRevision() {
+    const databasePath = resolveDatabasePath();
+    return [databasePath, strictFileRevision(databasePath)];
+}
 function worktreeRevision(root) {
     return {
         root,
@@ -153,12 +176,17 @@ function sessionInputRevision() {
         textOrNull(sessionRecordPath(id)),
         textOrNull(sessionArtifactPath(id, 'prompt')),
     ]);
+    // The canonical database carries the lifecycle those envelopes no longer do, and a commit from ANY process
+    // moves it. It is an input only while a record exists to read it through: with no session records the board
+    // has no row that derives from the store, and the store's own birth — the first canonical access inside a
+    // build initializes it — must not read as an input that moved during that build.
+    const canonical = ids.length ? sessionDatabaseRevision() : null;
     const projections = digest(ids.map((id) => [id, sessionEvalProjection(id)]));
     const activeRoots = [...new Set(ids.flatMap((id) => {
             const entry = readPublicRecordEntry(id);
             return entry.kind === 'ok' && entry.raw.governed && !entry.raw.archived ? [entry.raw.worktree_path] : [];
         }))].sort();
-    return { sessions: digest(sessionInputs), projections, projectionIds: ids, activeRoots };
+    return { sessions: digest([canonical, sessionInputs]), projections, projectionIds: ids, activeRoots };
 }
 function boardInputRevision(board) {
     const root = repoRoot();
@@ -444,6 +472,8 @@ function startBuild(mode = 'dirty') {
     });
     // Give a stale HTTP response a turn to flush before the producer's synchronous setup occupies the event
     // loop. Fresh callers simply absorb this small scheduling window while waiting on the same flight.
+    // A direct cold reader may be the only live work in a short-lived CLI process. Keep this one-shot
+    // scheduler referenced until it starts the producer, otherwise Node can exit with its fresh read pending.
     setTimeout(() => {
         if (controller.signal.aborted) {
             rejectBuild(Object.assign(new Error('graph build aborted before start'), { name: 'AbortError' }));
@@ -547,7 +577,7 @@ function startBuild(mode = 'dirty') {
         catch (error) {
             rejectBuild(error);
         }
-    }, mode === 'patrol' ? 0 : BACKGROUND_START_DELAY_MS).unref?.();
+    }, mode === 'patrol' ? 0 : BACKGROUND_START_DELAY_MS);
     const timeoutError = () => new Error(`graph build did not settle within ${BUILD_TIMEOUT_MS}ms`);
     // `settle` owns the real builder. The watchdog only rejects `wait`; the slot remains occupied until this
     // promise settles, so a next read can never overlap an abandoned git/fs build.

package/dist/graphSnapshot.js

@@ -1,4 +1,6 @@
-import { loadSpecs, requireGitWorkspace } from '@spexcode/spec-core';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { loadSpecs, requireGitWorkspace, headSha } from '@spexcode/spec-core';
 import { resolveLayout } from '@spexcode/spec-core';
 import { listSessions } from './sessions.js';
 import { driftIndex, historyIndex, repoRoot } from '@spexcode/spec-core';
@@ -9,6 +11,46 @@ import { buildBoard as assembleBoard, spliceSessions as spliceBoardSessions } fr
 import { evalContext, evalTimelines } from '@spexcode/spec-eval/evaltab';
 import { evalNodesAsync } from '@spexcode/spec-eval/scenarios';
 import { sessionEvalProjections } from '@spexcode/spec-eval/sessioneval';
+import { evalRemarkSourceFingerprint } from '@spexcode/spec-eval/host';
+import { listBlobs } from '@spexcode/spec-eval/cache';
+let timelineCache = null;
+function fileFingerprint(path) {
+    try {
+        return readFileSync(path).toString('base64');
+    }
+    catch {
+        return '<missing>';
+    }
+}
+function timelineCacheKey(root, nodeIds, specs, evalNodes) {
+    const hash = createHash('sha256');
+    hash.update(root);
+    hash.update('\0');
+    hash.update(headSha(root) || '<no-head>');
+    hash.update('\0');
+    hash.update(JSON.stringify(nodeIds));
+    for (const spec of specs) {
+        hash.update('\0spec\0');
+        hash.update(spec.path);
+        hash.update('\0');
+        hash.update(spec.body);
+    }
+    for (const node of evalNodes) {
+        hash.update('\0eval\0');
+        hash.update(node.id);
+        hash.update('\0');
+        hash.update(node.evalSource ?? '');
+        hash.update('\0');
+        hash.update(fileFingerprint(node.sidecarPath));
+    }
+    // Issue remarks are an eval input even though they live outside the spec tree.
+    hash.update('\0remarks\0');
+    hash.update(evalRemarkSourceFingerprint());
+    // Evidence presence is part of each published timeline row (`present` vs `miss`).
+    hash.update('\0blobs\0');
+    hash.update(listBlobs().join('\0'));
+    return hash.digest('hex');
+}
 // The application adapter is the sole reader of runtime/forge state. graph.ts only receives this result.
 export async function boardSnapshot() {
     const root = repoRoot();
@@ -22,7 +64,20 @@ export async function boardSnapshot() {
     const { issues, stamp: issuesStamp } = boardThreads({ host: resolveForgeHost(), state: residentForgeState() }, nodeIds);
     const [idx, hidx, evalNodes] = await Promise.all([driftIndex(root), historyIndex(root), evalNodesAsync(root)]);
     const context = await evalContext(root, specs, idx, hidx, undefined, evalNodes);
-    const timelines = await evalTimelines(nodeIds, context);
+    const key = timelineCacheKey(root, nodeIds, specs, evalNodes);
+    let timelines;
+    if (timelineCache?.key === key) {
+        timelines = timelineCache.timelines;
+    }
+    else {
+        // The board carries only latest-per-scenario counts, so the cold build reads latest-only: the retained
+        // sidecar history is served by the detail endpoints and probing it here scales graph latency with the
+        // reading count instead of the live verdict population. Freshness itself is NOT deferred — the board
+        // publishes verdicts, and a verdict whose freshness was never computed is not a stale verdict, it is no
+        // verdict at all. An order-only board would report every measured row as stale and none as fresh.
+        timelines = await evalTimelines(nodeIds, context, { latestOnly: true });
+        timelineCache = { key, timelines };
+    }
     return {
         root, specs, layout, sessions, issues, issuesStamp, forgeRevision: residentForgeRevision(),
         evalTimelines: new Map(nodeIds.map((nodeId, index) => [nodeId, timelines[index]])),

package/dist/graphStream.d.ts

@@ -58,6 +58,8 @@ export type PendingGraphChanges = {
 export declare const addPendingGraphChange: (pending: PendingGraphChanges, scope: Scope) => PendingGraphChanges;
 export declare function isSessionCreateCandidateRegistryEvent(relativePath: string, candidatePaths: Iterable<string>): boolean;
 export declare const notifyBoardChanged: (scope?: Scope) => void;
+export declare const sessionDatabaseWatchIgnore: (databasePath: string) => ((relativePath: string) => boolean);
+export declare function watchSessionDatabase(databasePath: string, onInput: () => void, onFailure: (error: Error) => void, watchFactory?: WatchFactory): TreeWatcherRegistry;
 type RegistryGroup = {
     root: string;
     close(): void;

package/dist/graphStream.js

@@ -1,7 +1,8 @@
 import { streamSSE } from 'hono/streaming';
 import { watch, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { join, dirname, relative, resolve, basename } from 'node:path';
-import { sessionsRoot, gitCommonDir, repoRoot, sessionBranchIndex, mainBranch } from '@spexcode/spec-core';
+import { sessionsRoot, gitCommonDir, repoRoot, sessionBranchIndex, mainBranch, isTrashWorktreePath } from '@spexcode/spec-core';
+import { resolveDatabasePath } from '@spexcode/session-selflaunch';
 import { hotSignature, warmSignature, listSessions, pendingSessionCreateWorktreePaths } from './sessions.js';
 import { getBoard, getBoardForSessionRefresh, invalidateBoard, patrolBoard } from './graphCache.js';
 import { unitize, tagOf, diffUnits } from '@spexcode/spec-core';
@@ -439,7 +440,7 @@ function fireChanged(scope = 'full', evalTarget) {
 }
 // ---- event source 0: an EXPLICIT server-side nudge ----
 // for a server-side mutation that must show instantly regardless of watcher health: /rename writes the
-// session's global record (`session.json` — [[session-rename]]), which lives INSIDE the watched store, so
+// session's global runtime envelope (`runtime.json` — [[session-rename]]), which lives INSIDE the watched store, so
 // source 1 normally sees the write too. The explicit route call stays because that fs watch is best-effort
 // (it can fail to attach), and the nudge makes the sub-second rename guarantee deterministic. Same
 // debounced funnel as every other source; defaults to 'full' but the rename route passes 'sessions'.
@@ -535,6 +536,80 @@ function ensureWatcher(root) {
     }
     noteSourceHealthy('store');
 }
+// ---- event source 1b: the canonical session database (lifecycle commits from ANY process) → 'sessions' ----
+// Since the JSON cutover ([[production-cutin]]) a lifecycle transition is a SQLite commit, not a write inside the
+// store above: that watch still sees the runtime envelope and the prompt, but the state a HOOK authors — mark-active
+// on every prompt and tool call, the stop-gate's declarations, idle — is committed by the hook's OWN process through
+// `spex internal session-state`. The backend's in-process commit observer (index.ts) bridges only its own commits,
+// so without this leaf a hook-authored flip reached the board only when some unrelated signal happened to re-splice:
+// a message sent from the dashboard left the row idle for minutes (measured on the dogfood board: 150s of nothing
+// but pings after the commit). One NON-recursive watch on the database's directory, delivering only the database's
+// own names — the file and its `-journal` (journal_mode=delete writes both on every commit); every other file in
+// that directory is filtered out at delivery. Attach failure is held and repaired like every other source, and
+// [[graph-cache]] folds the same file into its session revision so the patrol covers a held or disabled leaf.
+let sessionDatabaseWatcher = null;
+let activeDatabasePath = null;
+const SESSION_DB_SOURCE = 'session-db';
+export const sessionDatabaseWatchIgnore = (databasePath) => {
+    const name = basename(databasePath);
+    return (relativePath) => relativePath !== name && !relativePath.startsWith(`${name}-`);
+};
+export function watchSessionDatabase(databasePath, onInput, onFailure, watchFactory) {
+    return new TreeWatcherRegistry({
+        root: dirname(databasePath),
+        source: SESSION_DB_SOURCE,
+        scope: 'sessions',
+        recursive: false,
+        ignore: sessionDatabaseWatchIgnore(databasePath),
+        watchFactory,
+        onInput: () => onInput(),
+        onFailure,
+    });
+}
+function closeSessionDatabaseWatcher() {
+    sessionDatabaseWatcher?.close();
+    sessionDatabaseWatcher = null;
+    activeDatabasePath = null;
+}
+function ensureSessionDatabaseWatcher() {
+    if (isDisabled(SESSION_DB_SOURCE)) {
+        closeSessionDatabaseWatcher();
+        return;
+    }
+    let databasePath;
+    try {
+        databasePath = resolveDatabasePath();
+    }
+    catch (error) {
+        noteSourceFailure(SESSION_DB_SOURCE, error);
+        return;
+    }
+    if (sessionDatabaseWatcher && activeDatabasePath === databasePath)
+        return;
+    closeSessionDatabaseWatcher();
+    activeDatabasePath = databasePath;
+    if (!mayAttach(SESSION_DB_SOURCE))
+        return;
+    try {
+        mkdirSync(dirname(databasePath), { recursive: true });
+    }
+    catch (error) {
+        console.error(`spec-cli: graph watcher '${SESSION_DB_SOURCE}' could not create ${dirname(databasePath)}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const registry = watchSessionDatabase(databasePath, () => fireChanged('sessions'), (error) => {
+        if (sessionDatabaseWatcher === registry)
+            sessionDatabaseWatcher = null;
+        noteSourceFailure(SESSION_DB_SOURCE, error);
+        fireChanged('sessions');
+    });
+    sessionDatabaseWatcher = registry;
+    if (!registry.refresh()) {
+        if (sessionDatabaseWatcher === registry)
+            sessionDatabaseWatcher = null;
+        return;
+    }
+    noteSourceHealthy(SESSION_DB_SOURCE);
+}
 let refsWatchers = null;
 const REFS_OBSERVER = 'graph:refs';
 // @@@ the moved ref NAMES its scope - the watcher has always known which ref moved and threw it away, so
@@ -657,13 +732,14 @@ const worktreeSource = (name) => `worktree:${name}`;
 const PROJECT_ROOT_SOURCE = 'project-root';
 let projectRootWatcher = null;
 const ignoredWorktreePath = (file) => file.split(/[\\/]/).some((segment) => segment === '.git' || segment === 'node_modules');
+const ignoredGeneratedBuildPath = (file) => file.split(/[\\/]/).some((segment) => segment === 'dist' || segment.startsWith('.dist-next-') || segment.startsWith('.dist-previous-'));
 // @@@ linked worktrees are not graph input for THIS backend - the board's node statuses derive from the
 // served checkout's own HEAD, so a file under `.worktrees/<node>` belongs to a different branch's tree and
 // cannot move any status here until it lands and this HEAD advances. Watching them registers one inotify
 // watch per directory (Linux takes the exact-directory transport) and buys nothing: measured on this repo,
 // 20,124 of 20,473 watched directories were linked worktrees against 843 in the served tree.
 // The per-worktree registries above keep their own roots; only the project-root sweep skips them.
-export const ignoredProjectRootPath = (file) => ignoredWorktreePath(file) || file.split(/[\\/]/).some((segment) => segment === '.worktrees');
+export const ignoredProjectRootPath = (file) => ignoredWorktreePath(file) || ignoredGeneratedBuildPath(file) || file.split(/[\\/]/).some((segment) => segment === '.worktrees');
 // The directory whose tree this backend serves is graph input even before it has a `.spec` tree or any live
 // session worktree. Keeping it in the same root registry as linked worktrees means a first `spex init` or
 // agent-created spec invalidates a warmed empty board instead of leaving a confidently stale cache until a
@@ -807,6 +883,8 @@ async function reconcileWorktreePass(forcedSessions, era, common) {
         catch {
             continue;
         }
+        if (isTrashWorktreePath(wtPath))
+            continue;
         const normalizedPath = resolve(wtPath);
         if (!wantedPaths.has(normalizedPath)) {
             if (dropWorktreeWatcher(e.name))
@@ -1033,6 +1111,7 @@ export async function ensureBoardFileWatchers(forceSessionId) {
     activeStoreRoot = storeRoot;
     activeCommonRoot = commonRoot;
     ensureWatcher(storeRoot);
+    ensureSessionDatabaseWatcher();
     ensureRefsWatcher(commonRoot);
     await ensureWorktreeRegistry(forceSessionId);
     ensureProjectRootWatcher();
@@ -1055,6 +1134,7 @@ export function closeBoardFileWatchers() {
     worktreeReconcileFlight = null;
     storeWatcher?.close();
     storeWatcher = null;
+    closeSessionDatabaseWatcher();
     refsWatchers?.close();
     refsWatchers = null;
     registryWatcher?.close();

package/dist/guide.js

@@ -71,8 +71,9 @@ FRONTMATTER (YAML between the opening and closing --- lines; every field optiona
            duplicates, globs/directories with a selector, and dead/ambiguous units all error loud. A
            selector-scoped governor claims units, not the file, so it stays out of the \`owners\` bound
            (spex spec owner still displays it, marked "(scoped)"). Anchors are optional.
-           Python \`.py\`/\`.pyi\` anchors recognize structural \`def\`, \`async def\`, and \`class\`
-           declarations. Methods and nested declarations use lexical qualified names such as
+           Tree-sitter-backed \`.ts\`/\`.tsx\`/\`.py\`/\`.go\`/\`.rs\`/\`.java\`/\`.rb\` anchors recognize
+           structural function, method, class, interface, enum, and type declarations. Methods and nested
+           declarations use lexical qualified names such as
            \`Class.method\`, \`outer.inner\`, or \`Outer.Inner.method\`; attached decorators belong to
            the declaration's range. Runtime-created/assigned callables, imported aliases, and generated
            names are outside this declaration extractor and therefore resolve as dead anchors.
@@ -546,8 +547,15 @@ behavior, decided per KIND (and, for a contract file, by its live CONTENT).
 ── THE FOUR KINDS (all fixed) ──
   spec data       .spec/ (incl .plugins/) + spexcode.json — ALWAYS tracked. Git is the database; there is
                   deliberately NO way to say "untrack the spec" in this schema.
-  machine facts   spexcode.local.json, the hook shims (.claude/settings.json, .codex/hooks.json), plugin
-                  bundles — NEVER tracked; always in the per-clone exclude.
+  (no delivery)   \`spex init --harness none\` ("harnesses": []) adopts the spec tree, the lint and the git
+                  hooks and writes NOTHING into any agent's config — the L0-only footprint.
+  machine facts   spexcode.local.json, the hook shims, plugin bundles — NEVER tracked; always in the
+                  per-clone exclude. A shim is a machine fact only while it is WHOLLY OURS: where the harness
+                  discovers its hooks in a file that is ALSO your project config (.claude/settings.json,
+                  .codex/hooks.json, .zcode/settings.json), SpexCode co-owns only its own hook entries —
+                  your permissions/env/statusLine/hooks are merged around, never replaced, and uninstall
+                  takes back exactly those entries. Such a file stays visible to git (hiding yours would be
+                  data-loss shaped), so keep our absolute toolchain paths out of your commits.
   artifacts       the CLAUDE.md/AGENTS.md contract blocks + materialized skills/agents — derived, NEVER
                   tracked; hidden via .git/info/exclude. The host's tracked .gitignore is never touched.
   run residue     .worktrees/, the global store (~/.spexcode), .git/spexcode evidence — never tracked;
@@ -621,15 +629,20 @@ Use the session's file list when an artifact belongs in the human's hands:
   spex session files retract <path>  withdraw one path
 
 Posting resolves a relative path from your current directory and records its absolute path beside the global
-session record. It copies, moves, stages, and uploads NOTHING. The path is live: editing the file after
+session record only after confirming it is a readable regular file. It copies, moves, stages, and uploads NOTHING. The path is live: editing the file after
 posting changes what the human downloads. The reference is host-local; opening the session elsewhere cannot
 make its path point at another machine's file.
 
+Put raw run artifacts in a persistent directory OUTSIDE the product repository by default. A worktree artifact
+makes merge readiness report a dirty tree and pressures generated evidence into the product commit. Before review,
+run \`spex session files ls\`: a target that disappeared or became unreadable is printed as \`INVALID\` and must be
+recreated or retracted; a valid path prints normally.
+
 The session page's top-right files icon is grey while the list is empty. Once live, it opens the posted list;
 choosing a path previews its current text or raster-image bytes in a pop-out, while the adjacent download tool
 downloads it through the backend at that moment. Previews are limited to 2 MiB, text and PNG/JPEG/GIF/WebP;
-other types and larger files say to download instead. A missing, moved, or unreadable target stays listed but
-reports that it no longer exists. The backend refuses a preview or download for any path not on that session's
+other types and larger files say to download instead. A missing, moved, or unreadable target stays listed and is
+marked invalid by the CLI; preview/download reports that it no longer exists. The backend refuses a preview or download for any path not on that session's
 list.
 
 This is the reverse of a dashboard attachment: [[file-attach]] sends human bytes to an agent. Files publishes