spexcode 0.6.2 → 0.6.6

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

@@ -0,0 +1,1908 @@
+// static import is fine here: mentions.ts is dependency-free at module level, and stripRefSigil is needed
+// by several verbs (spec owner, graph, issue/eval node args) — a CLI reference arg tolerates an optional @/[[ ]]
+// sigil ([[mentions]]).
+import { stripRefSigil } from './mentions.js';
+import { installEvalHost } from './eval-host.js';
+installEvalHost();
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+const cmd = process.argv[2];
+function levenshtein(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        let previous = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const current = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+            previous = current;
+        }
+    }
+    return row[b.length];
+}
+function nearestPublicCommand(input, commands) {
+    const query = input.toLowerCase();
+    if (!/^[a-z0-9-]+$/.test(query))
+        return null;
+    const similarity = (a, b) => 1 - levenshtein(a, b) / Math.max(a.length, b.length);
+    const words = (text) => text.toLowerCase().match(/[a-z0-9-]+/g) ?? [];
+    let best = null;
+    for (const command of commands) {
+        const [headline = '', ...detail] = command.text.split('\n');
+        const score = Math.max(similarity(query, command.name), ...words(headline).map((word) => similarity(query, word)), ...words(detail.join('\n')).map((word) => similarity(query, word) * 0.8));
+        if (!best || score > best.score)
+            best = { name: command.name, score };
+    }
+    return best && best.score >= 0.8 ? best.name : null;
+}
+if (cmd === '--version' || cmd === '-v') {
+    const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    console.log(manifest.version);
+    process.exit(0);
+}
+const DAEMON_DEPENDENCIES = ['hono', '@hono/node-server', '@hono/node-ws', 'node-pty'];
+async function assertDaemonDependencies(command) {
+    const { createRequire } = await import('node:module');
+    const resolve = createRequire(import.meta.url).resolve;
+    const missing = DAEMON_DEPENDENCIES.filter((dependency) => {
+        try {
+            resolve(dependency);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    });
+    if (!missing.length)
+        return;
+    console.error(`${command}: missing optional daemon dependencies: ${missing.join(', ')}`);
+    console.error(`Install them with: npm install ${missing.join(' ')}`);
+    process.exit(1);
+}
+// Registered before any await so a fatal top-level error lands here. Errors we OWN — BackendError, the
+// loud malformed-config ConfigError, the --api/--port UsageError, the write-guard GuardError, and a
+// GitWorkspaceError that teaches a fresh directory how to continue — are
+// matched BY NAME (to avoid importing them) and rendered as a one-line `spex: <message>` (a user's
+// config typo or a refused cross-project write must read as their situation, not a SpexCode stack dump);
+// anything else prints in full so a real bug keeps its trace. A synchronous throw inside an awaited call
+// (loadConfig on a malformed spexcode.json) surfaces as uncaughtException, not unhandledRejection, so BOTH
+// paths route through the same printer.
+function fatal(e) {
+    if (e instanceof Error && ['BackendError', 'ConfigError', 'UsageError', 'GuardError', 'DashboardAssetError', 'GitWorkspaceError'].includes(e.name))
+        console.error(`spex: ${e.message}`);
+    else
+        console.error(e);
+    process.exit(1);
+}
+process.on('unhandledRejection', fatal);
+process.on('uncaughtException', fatal);
+// tiny flag reader: --key value  (and bare positionals)
+function flag(name) {
+    const i = process.argv.indexOf(`--${name}`);
+    return i >= 0 ? process.argv[i + 1] : undefined;
+}
+// Exit AFTER stdout has flushed. process.exit() force-quits without draining buffered pipe writes, so a
+// large piped dump (`spex issue ls --json | …`, graph --json, review --json) is silently cut off at the
+// pipe buffer (~64KB). The empty write's callback fires once every prior queued chunk has drained; the
+// returned promise never resolves (process.exit ends the process inside the callback), so
+// `await flushExit(code)` halts execution here exactly like process.exit did — safe to drop in on any
+// unbounded-output verb. EPIPE (a reader that closed early — `| head`, `| jq` exiting) can never drain, so
+// we ALSO exit on the stream error rather than hang: the truncation is the reader's choice then, not ours.
+function flushExit(code = 0) {
+    return new Promise(() => {
+        const done = () => process.exit(code);
+        process.stdout.on('error', done);
+        process.stdout.write('', done);
+    });
+}
+const has = (name) => process.argv.includes(`--${name}`);
+// bare positionals after argv index `from`, skipping flags and their values (selectors for ls/watch).
+const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--prompt-file', '--timeout', '--reason', '--out', '--content-dir', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api', '--api-port', '--host', '--preset', '--limit', '--session', '--depth', '--focus', '--keys', '--ssh', '--allow-stop', '--allow-resume', '--ttl-ms', '--wait-ms', '--adapter', '--thread', '--tmux', '--worktree', '--branch', '--to', '--name', '--base', '--path', '--owner', '--details', '--variant', '--cli', '--count', '--ids']);
+const EXPLICIT_BACKEND_ROUTE_FLAGS = ['api', 'port', 'password', 'insecure'];
+const EXPLICIT_BACKEND_VALUE_FLAGS = EXPLICIT_BACKEND_ROUTE_FLAGS
+    .filter((name) => VALUE_FLAGS.has(`--${name}`))
+    .map((name) => `--${name}`);
+const EXPLICIT_BACKEND_BARE_FLAGS = EXPLICIT_BACKEND_ROUTE_FLAGS
+    .filter((name) => !VALUE_FLAGS.has(`--${name}`))
+    .map((name) => `--${name}`);
+function positionals(from) {
+    const out = [];
+    for (let i = from; i < process.argv.length; i++) {
+        const t = process.argv[i];
+        if (t.startsWith('--')) {
+            if (VALUE_FLAGS.has(t))
+                i++;
+            continue;
+        }
+        out.push(t);
+    }
+    return out;
+}
+function rejectFlags(command, from, allowed, attached = []) {
+    const known = new Set(allowed.map((name) => `--${name}`));
+    for (let i = from; i < process.argv.length; i++) {
+        const token = process.argv[i];
+        if (!token.startsWith('--'))
+            continue;
+        if (attached.some((name) => token.startsWith(`--${name}=`)))
+            continue;
+        if (!known.has(token)) {
+            console.error(`${command}: unknown flag ${token}`);
+            process.exit(2);
+        }
+        if (VALUE_FLAGS.has(token))
+            i++;
+    }
+}
+function rejectUnknownFlags(command, from, allowed, attached = []) {
+    rejectFlags(command, from, allowed, attached);
+}
+function rejectUnknownBackendFlags(command, from, allowed, attached = []) {
+    rejectFlags(command, from, [...allowed, ...EXPLICIT_BACKEND_ROUTE_FLAGS], attached);
+}
+// `--children` deliberately has an optional value only in its attached form. A separated following token
+// remains a normal ls selector, so the long-standing `ls --children <child-SEL>` grammar keeps its meaning.
+function childrenScopeOption() {
+    const forms = process.argv.slice(4).filter((token) => token === '--children' || token.startsWith('--children='));
+    if (!forms.length)
+        return undefined;
+    if (forms.length > 1) {
+        console.error('spex session ls: --children may appear only once');
+        process.exit(2);
+    }
+    if (forms[0] === '--children')
+        return null;
+    const selector = forms[0].slice('--children='.length);
+    if (!selector) {
+        console.error('spex session ls: --children=<PARENT-SEL> requires a non-empty parent selector');
+        process.exit(2);
+    }
+    return selector;
+}
+const idLikeSelector = (selector) => /^[0-9a-f-]{8,}$/i.test(stripRefSigil(selector));
+function sessionSendUsage(detail, keys = false) {
+    console.error(`spex session send: ${detail}`);
+    console.error(keys
+        ? 'usage: spex session send <SEL> --keys "<keys>"   (e.g. "Up Up Enter", "C-r", single chars — last resort; try a plain send first)'
+        : 'usage: spex session send <SEL> "<msg>" [--api <url> | --port <n>]\n       spex session send --ssh <address> <FULL-SESSION-ID> "<msg>"\n       spex session send <SEL> [--api <url> | --port <n>] -- <option-shaped-msg>');
+    process.exit(2);
+}
+function parseSessionSendArgs(args) {
+    const valueFlags = new Set([...EXPLICIT_BACKEND_VALUE_FLAGS, '--keys', '--ssh']);
+    const bareFlags = new Set(EXPLICIT_BACKEND_BARE_FLAGS);
+    const values = new Map();
+    const positionals = [];
+    let endOfOptions = false;
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i];
+        if (!endOfOptions && token === '--') {
+            endOfOptions = true;
+            continue;
+        }
+        if (!endOfOptions && token.startsWith('--')) {
+            if (!valueFlags.has(token) && !bareFlags.has(token))
+                sessionSendUsage(`unknown flag ${token}`);
+            if (values.has(token))
+                sessionSendUsage(`${token} may appear only once`, token === '--keys');
+            values.set(token, '');
+            if (bareFlags.has(token))
+                continue;
+            const value = args[++i];
+            if (value === undefined || value === '' || value.startsWith('--'))
+                sessionSendUsage(`${token} expects one non-empty value`, token === '--keys');
+            values.set(token, value);
+            continue;
+        }
+        positionals.push(token);
+    }
+    if ((values.has('--api') && values.has('--port')) || (values.has('--ssh') && (values.has('--api') || values.has('--port')))) {
+        sessionSendUsage('--ssh, --api, and --port are alternate routes; choose one');
+    }
+    if (values.has('--ssh') && (values.has('--password') || values.has('--insecure'))) {
+        sessionSendUsage('--password and --insecure apply only to an explicit --api route, not --ssh');
+    }
+    const rawKeys = values.get('--keys');
+    if (rawKeys !== undefined) {
+        if (values.has('--ssh'))
+            sessionSendUsage('--keys cannot cross a machine peer', true);
+        if (positionals.length !== 1)
+            sessionSendUsage('raw keys take one selector and no text message', true);
+        const keys = rawKeys.split(/\s+/).filter(Boolean);
+        if (!keys.length)
+            sessionSendUsage('--keys expects one non-empty value', true);
+        return { selector: positionals[0], kind: 'keys', keys };
+    }
+    if (positionals.length !== 2)
+        sessionSendUsage('plain send requires exactly one selector and one message');
+    return { selector: positionals[0], kind: 'text', text: positionals[1], ...(values.has('--ssh') ? { sshAddress: values.get('--ssh') } : {}) };
+}
+const FULL_SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function sessionPeerAnchorUsage(verb, detail) {
+    console.error(`spex session ${verb}: ${detail}`);
+    console.error(verb === 'ls'
+        ? 'usage: spex session ls [SEL...] [--status a,b] [--all] [--json]\n       spex session ls --ssh <address> <FULL-SESSION-ID> [--status a,b] [--json]'
+        : 'usage: spex session new "<prompt>" [--prompt-file <path>|-] [--launcher <name>] [--name <name>] [--base <commit-ish>]\n       spex session new --ssh <address> <FULL-SESSION-ID> "<prompt>" [--prompt-file <path>|-] [--launcher <name>] [--name <name>] [--base <commit-ish>]');
+    process.exit(2);
+}
+// With SSH, every session verb starts with the same full-id anchor. Target operations address that record;
+// ls/new derive its project at the remote gateway. This keeps project identity out of a second flag grammar.
+function parseSessionPeerAnchor(verb, args) {
+    const sshCount = process.argv.filter((token) => token === '--ssh').length;
+    if (!sshCount)
+        return null;
+    if (sshCount !== 1)
+        sessionPeerAnchorUsage(verb, '--ssh may appear only once');
+    const sshAddress = flag('ssh');
+    if (!sshAddress || sshAddress.startsWith('--'))
+        sessionPeerAnchorUsage(verb, '--ssh expects one non-empty address');
+    if (has('api') || has('port'))
+        sessionPeerAnchorUsage(verb, '--ssh, --api, and --port are alternate routes; choose one');
+    if (has('password') || has('insecure'))
+        sessionPeerAnchorUsage(verb, '--password and --insecure apply only to an explicit --api route, not --ssh');
+    const sessionId = args[0];
+    if (!FULL_SESSION_ID.test(sessionId ?? ''))
+        sessionPeerAnchorUsage(verb, '--ssh requires a full session id as its first positional');
+    return { sshAddress, sessionId };
+}
+function sessionTargetUsage(verb, detail) {
+    console.error(`spex session ${verb}: ${detail}`);
+    console.error(verb === 'show'
+        ? 'usage: spex session show <SEL> [--capture] [--json] [--api <url> | --port <n>]\n       spex session show --ssh <address> <FULL-SESSION-ID> [--json]'
+        : 'usage: spex session close <SEL> [--api <url> | --port <n>]\n       spex session close --ssh <address> <FULL-SESSION-ID>');
+    process.exit(2);
+}
+function parseSessionTargetArgs(verb, args) {
+    const values = new Map();
+    const valueFlags = new Set([...EXPLICIT_BACKEND_VALUE_FLAGS, '--ssh']);
+    const bareFlags = new Set([...EXPLICIT_BACKEND_BARE_FLAGS, ...(verb === 'show' ? ['--capture', '--json'] : [])]);
+    const positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i];
+        if (!token.startsWith('--')) {
+            positionals.push(token);
+            continue;
+        }
+        if (!valueFlags.has(token) && !bareFlags.has(token))
+            sessionTargetUsage(verb, `unknown flag ${token}`);
+        if (values.has(token))
+            sessionTargetUsage(verb, `${token} may appear only once`);
+        values.set(token, '');
+        if (bareFlags.has(token))
+            continue;
+        const value = args[++i];
+        if (value === undefined || value === '' || value.startsWith('--'))
+            sessionTargetUsage(verb, `${token} expects one non-empty value`);
+        values.set(token, value);
+    }
+    if ((values.has('--api') && values.has('--port')) || (values.has('--ssh') && (values.has('--api') || values.has('--port')))) {
+        sessionTargetUsage(verb, '--ssh, --api, and --port are alternate routes; choose one');
+    }
+    if (values.has('--ssh') && (values.has('--password') || values.has('--insecure'))) {
+        sessionTargetUsage(verb, '--password and --insecure apply only to an explicit --api route, not --ssh');
+    }
+    if (values.has('--ssh') && verb === 'show' && values.has('--capture'))
+        sessionTargetUsage(verb, '--capture cannot cross a machine peer');
+    if (positionals.length !== 1)
+        sessionTargetUsage(verb, 'requires exactly one session selector');
+    return { selector: positionals[0], ...(values.has('--ssh') ? { sshAddress: values.get('--ssh') } : {}) };
+}
+const SIGNPOSTS = {
+    search: 'spex spec search <query>',
+    owner: 'spex spec owner <path>',
+    lint: 'spex spec lint',
+    ack: 'spex spec ack <node>… --reason "<why>"',
+    tree: 'spex graph',
+    board: 'spex graph --json',
+    blob: 'spex evidence put|get',
+    issues: 'spex issue — ls (was: bare issues) · show · open · reply · close · promote; on|off|status → the `issues.enabled` key in spexcode.json; `issues nudge` → spex internal nudge',
+    forge: 'spex issue links [--pending] [--store <host>]  (--host is now --store)',
+    runtime: 'spex doctor repair app-server',
+    new: 'spex session new',
+    ls: 'spex session ls',
+    watch: 'spex session watch',
+    wait: 'spex session wait',
+    review: 'spex session review',
+    merge: 'spex session merge',
+    send: 'spex session send',
+    reopen: 'spex session resume',
+    done: 'spex session done',
+    park: 'spex session park',
+    ask: 'spex session ask',
+    exit: 'spex session stop',
+    close: 'spex session close',
+    capture: 'spex session show <SEL> --capture',
+    attach: 'spex session attach',
+    rename: 'spex session rename',
+    prompt: 'spex session show <SEL>',
+    rawkey: 'spex session send <SEL> --keys "<keys>"',
+    resolve: 'spex remark resolve <ref>',
+    retract: 'spex remark retract <ref>',
+};
+const SESSION_SIGNPOSTS = {
+    rawkey: 'spex session send <SEL> --keys "<keys>"',
+    exit: 'spex session stop <SEL>',
+    reopen: 'spex session resume <SEL> [--force]',
+    capture: 'spex session show <SEL> --capture',
+    prompt: 'spex session show <SEL>',
+    state: 'spex internal session-state',
+    fail: 'spex internal session-fail',
+    idle: 'spex internal session-idle',
+    'commit-gate': 'spex internal commit-gate',
+};
+function signpost(oldSpelling, newSpelling) {
+    console.error(`spex: \`${oldSpelling}\` was removed in v0.3.0 — use: ${newSpelling}  (map: spex help)`);
+    process.exit(2);
+}
+if (cmd !== undefined && SIGNPOSTS[cmd])
+    signpost(`spex ${cmd}`, SIGNPOSTS[cmd]);
+async function followKit(selectors, verb) {
+    const { followSessions } = await import('./session-follow.js');
+    const { localCachedSessions } = await import('./client.js');
+    const { fromRaw, ownSessionId, selectSessions, toSession } = await import('./sessions.js');
+    const { listSessionIds, readPublicRecordEntry } = await import('@spexcode/spec-core');
+    const real = selectors.filter((sel) => sel && sel !== '@all');
+    let picked = [];
+    if (real.length) {
+        picked = selectSessions(localCachedSessions(true), real).map((s) => s.id);
+        if (!picked.length) {
+            console.error(`${verb}: no such session: ${real.join(' ')}`);
+            process.exit(2);
+        }
+    }
+    const targets = real.length ? () => picked : () => listSessionIds();
+    // A feed line needs a session's NAME, which is record data; its STATUS comes from the log event, never from
+    // a fresh sample of the mutable record — that resample is what made the old poll lose moves.
+    const row = (id, status, note) => {
+        const entry = readPublicRecordEntry(id);
+        if (entry.kind !== 'ok')
+            return null;
+        return { ...toSession(fromRaw(entry.raw), status, 'unknown'), note };
+    };
+    const watcher = ownSessionId();
+    return { watcher, follow: (emit, opts) => followSessions(emit, { ...opts, targets, self: watcher, row }) };
+}
+async function localWatchTargetsOrExit(selectors, verb) {
+    if (!selectors.length) {
+        console.error(`usage: ${verb} <SEL...>`);
+        process.exit(2);
+    }
+    const { localCachedSessions } = await import('./client.js');
+    const { selectSessions } = await import('./sessions.js');
+    const targets = selectSessions(localCachedSessions(true), selectors).map((session) => session.id);
+    if (!targets.length) {
+        console.error(`${verb}: no such local session: ${selectors.join(' ')}`);
+        process.exit(2);
+    }
+    return targets;
+}
+async function resolveSessionOrExit(selector) {
+    if (!selector) {
+        console.error('spex: missing session selector (id | id-prefix | node | branch | . for self)');
+        process.exit(2);
+    }
+    const { resolveClientSession } = await import('./client.js');
+    const { sessionTitle } = await import('./sessions.js');
+    const r = await resolveClientSession(selector);
+    if ('ok' in r)
+        return r.ok;
+    if ('none' in r) {
+        console.error(`spex: no such session: ${selector}`);
+        process.exit(2);
+    }
+    console.error(`spex: ambiguous selector "${selector}" matches ${r.ambiguous.length} sessions — be more specific:`);
+    for (const s of r.ambiguous)
+        console.error(`  ${s.id.slice(0, 8)}  ${sessionTitle(s)}`);
+    process.exit(2);
+}
+async function resolveSelectorOrExit(selector) {
+    return (await resolveSessionOrExit(selector)).id;
+}
+// the [[session-eval]] EXPORT artifact behind `spex eval ls --session <SEL> --export`: fetch the
+// backend-rendered self-contained HTML, write it (--out, else a tmp file) or open it (--open). Never returns.
+async function evalExport(id) {
+    const { clientEvalExport } = await import('./client.js');
+    const r = await clientEvalExport(id);
+    if (!r.ok) {
+        console.error(`no export for ${id} (status ${r.status})`);
+        process.exit(1);
+    }
+    const { writeFileSync } = await import('node:fs');
+    const { join } = await import('node:path');
+    const { tmpdir } = await import('node:os');
+    const out = flag('out') ?? join(tmpdir(), `spexcode-eval-${id.slice(0, 8)}.html`);
+    writeFileSync(out, r.body);
+    if (has('open')) {
+        const { spawn } = await import('node:child_process');
+        const opener = process.platform === 'darwin' ? 'open' : 'xdg-open';
+        try {
+            spawn(opener, [out], { detached: true, stdio: 'ignore' }).unref();
+            console.log(`opened ${out}`);
+        }
+        catch {
+            console.log(`wrote ${out} — couldn't auto-open, open it in a browser`);
+        }
+    }
+    else
+        console.log(out);
+    process.exit(0);
+}
+// Internal lifecycle writers use the same local record-resolution rules as worker declarations, but the
+// porcelain done/park/ask dispatch below goes straight to its named handler.
+async function stateKit() {
+    const { sessionStateKit } = await import('./session-declarations.js');
+    return sessionStateKit(flag('session'));
+}
+// a trailing --help/-h prints help and exits BEFORE any verb runs, so a help probe never fires a
+// streaming/mutating command. It prints THAT command's usage when an entry exists (the second layer
+// of the help journey — see help.ts); session noun-verb probes project the exact verb from the shared
+// drawer definition. Unknown tokens preserve the existing drawer/map fallback. (Removed spellings never
+// reach here — the signpost table above already exited.)
+if (cmd && cmd !== 'help' && (has('help') || process.argv.includes('-h'))) {
+    const { commandHelp, overviewHelp } = await import('./help.js');
+    console.log(commandHelp(cmd, cmd === 'session' || cmd === 'doctor' ? process.argv[3] : undefined) ?? overviewHelp());
+    process.exit(0);
+}
+if (cmd === 'serve') {
+    // `spex serve [api]` runs the backend; `spex serve ui` serves the dashboard on top of a running backend —
+    // two processes, two verbs in one operator drawer.
+    const target = positionals(3)[0];
+    if (target === 'ui') {
+        const { ensureDashboardArtifact } = await import('./dashboard-assets.js');
+        ensureDashboardArtifact('dist');
+        await assertDaemonDependencies('spex serve');
+        // the natural post-install UI: serve the bundled dashboard on its OWN port (loopback by default;
+        // --host widens the bind for LAN/tailnet viewing), proxying /api + the terminal socket to a
+        // separately-run `spex serve`. Replaces the dogfood-only `npm run web` (vite).
+        const { serveDashboardLocal } = await import('./gateway.js');
+        const port = Number(flag('port') ?? process.env.SPEXCODE_DASHBOARD_PORT ?? 5173);
+        const apiPort = Number(flag('api-port') ?? process.env.PORT ?? 8787);
+        const host = flag('host') ?? '127.0.0.1';
+        if (!Number.isInteger(port) || !Number.isInteger(apiPort)) {
+            console.error('spex serve ui: --port and --api-port must be integers');
+            process.exit(2);
+        }
+        serveDashboardLocal({ port, apiPort, host });
+    }
+    else if (target === undefined || target === 'api') {
+        await assertDaemonDependencies('spex serve');
+        // fail loud, not cryptic ([[platform-support]]): serve IS the entry to the session runtime, which needs a
+        // POSIX host (tmux/bash/unix-sockets). On a non-POSIX host (native Windows) point at WSL2 and exit here,
+        // before importing the supervisor starts the backend.
+        const { assertSessionRuntime } = await import('./runtime-guard.js');
+        assertSessionRuntime();
+        // the supervisor owns the public port and runs the compiled index.js child for zero-downtime reloads.
+        // --port is sugar over the PORT env supervise.ts reads — set BEFORE importing so it takes effect. This
+        // mirrors `spex serve ui --api-port`, so one host runs many projects (each `serve --port N` paired with
+        // a `serve ui --api-port N`), cwd picking which project's .spec is served — no shared default collides.
+        const portArg = flag('port');
+        if (portArg !== undefined) {
+            if (!Number.isInteger(Number(portArg))) {
+                console.error('spex serve: --port must be an integer');
+                process.exit(2);
+            }
+            process.env.PORT = portArg;
+        }
+        await import('./supervise.js');
+    }
+    else {
+        console.error(`spex serve: unknown target '${target}' — spex serve [api] (the backend) | spex serve ui (the dashboard)`);
+        process.exit(2);
+    }
+}
+else if (cmd === 'dashboard') {
+    const { ensureDashboardArtifact } = await import('./dashboard-assets.js');
+    ensureDashboardArtifact('dist');
+    await assertDaemonDependencies('spex dashboard');
+    // the HOST-level dashboard ([[host-gateway]]): ONE gateway for every project this user serves. The
+    // engine is [[gateway-hub]] (routing + [[gateway-auth]] authorization: admin scope implicit from
+    // loopback until an admin password is set; per-project gates as configured); the host layer mounts the
+    // instance-validated project registry, its SSE stream, the durable catalog, and the /projects
+    // operations (register · init · doctor · start a backend) as the hub's admin extension. No --api-port
+    // pairing: which backend a request reaches is named in its /p/:projectId path, resolved per request.
+    // `spex serve ui` remains the explicit one-backend pairing; this verb is the zero-config many-project face.
+    const { startHostDashboard } = await import('./host.js');
+    const port = Number(flag('port') ?? process.env.SPEXCODE_DASHBOARD_PORT ?? 5173);
+    const host = flag('host') ?? '127.0.0.1';
+    if (!Number.isInteger(port)) {
+        console.error('spex dashboard: --port must be an integer');
+        process.exit(2);
+    }
+    startHostDashboard({ port, host });
+}
+else if (cmd === 'guidance') {
+    let out;
+    for (let i = 3; i < process.argv.length; i++) {
+        const token = process.argv[i];
+        if (token === '--json')
+            continue;
+        if (token === '--out') {
+            if (out !== undefined) {
+                console.error('spex guidance: --out may appear only once');
+                process.exit(2);
+            }
+            const value = process.argv[++i];
+            if (!value || value.startsWith('--')) {
+                console.error('spex guidance: --out expects a file path');
+                process.exit(2);
+            }
+            out = value;
+            continue;
+        }
+        if (token.startsWith('--')) {
+            console.error(`spex guidance: unknown flag ${token}`);
+            process.exit(2);
+        }
+        console.error(`spex guidance: unexpected argument '${token}'`);
+        process.exit(2);
+    }
+    const { buildGuidanceCatalog } = await import('./guidance-catalog.js');
+    const catalog = buildGuidanceCatalog();
+    if (out) {
+        catalog.write(out);
+        console.log(out);
+        process.exit(0);
+    }
+    process.stdout.write(catalog.exportJson());
+    await flushExit(0);
+}
+else if (cmd === undefined || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    // `spex help <cmd>` drills into one command; bare help is the map. Both name the next layer down.
+    const { commandHelp, overviewHelp } = await import('./help.js');
+    const topic = positionals(3)[0];
+    if (cmd === 'help' && topic) {
+        if (SIGNPOSTS[topic])
+            signpost(`spex ${topic}`, SIGNPOSTS[topic]);
+        const h = commandHelp(topic);
+        if (!h) {
+            console.error(`spex help: no command '${topic}' — run \`spex help\` for the map`);
+            process.exit(2);
+        }
+        console.log(h);
+    }
+    else
+        console.log(overviewHelp());
+}
+else if (cmd === 'guide') {
+    const { guideText, guideTopics } = await import('./guide.js');
+    if (process.argv[3] === 'config')
+        signpost('spex guide config', 'spex guide settings');
+    const text = guideText(process.argv[3]);
+    if (text === null) {
+        console.error(`spex guide: no topic '${process.argv[3]}'. Topics: ${guideTopics().join(', ')}. Run \`spex guide\` (no topic) for the setup workflow, \`spex help\` for the command map.`);
+        process.exit(2);
+    }
+    console.log(text);
+}
+else if (cmd === 'graph') {
+    if (flag('node') !== undefined) {
+        console.error('spex graph: --node was renamed — use --focus <id>');
+        process.exit(2);
+    }
+    if (has('public')) {
+        const focusRaw = flag('focus');
+        const depthRaw = flag('depth');
+        const out = flag('out');
+        const contentDir = flag('content-dir');
+        if (focusRaw !== undefined || depthRaw !== undefined) {
+            console.error('spex graph --public: --focus and --depth are not supported');
+            process.exit(2);
+        }
+        const { buildPublicGraphArtifact, publicGraphJson } = await import('./public-graph.js');
+        const artifact = await buildPublicGraphArtifact();
+        const payload = publicGraphJson(artifact.graph);
+        if (out) {
+            writeFileSync(out, payload);
+            console.log(out);
+        }
+        else {
+            process.stdout.write(payload);
+        }
+        if (contentDir) {
+            mkdirSync(contentDir, { recursive: true });
+            for (const document of artifact.documents) {
+                writeFileSync(`${contentDir}/${encodeURIComponent(document.id)}.json`, `${JSON.stringify(document, null, 2)}\n`);
+            }
+        }
+        await flushExit(0);
+    }
+    if (flag('content-dir') !== undefined) {
+        console.error('spex graph: --content-dir requires --public');
+        process.exit(2);
+    }
+    const { buildBoard } = await import('./graphSnapshot.js');
+    const focusRaw = flag('focus');
+    const depthRaw = flag('depth');
+    const depth = depthRaw === undefined ? undefined : Number(depthRaw);
+    if (depth !== undefined && (!Number.isInteger(depth) || depth < 0)) {
+        console.error('spex graph: --depth must be a non-negative integer');
+        process.exit(2);
+    }
+    const board = await buildBoard();
+    if (has('json') && focusRaw === undefined && depth === undefined) {
+        // interactive-only stderr hint: the JSON dump is machine food; a human at a tty gets pointed at
+        // the readable twin. Piped/redirected stdout stays byte-identical (the hint never touches stdout).
+        if (process.stdout.isTTY)
+            console.error('(human-readable: spex graph)');
+        console.log(JSON.stringify(board, null, 2));
+        await flushExit(0);
+    }
+    const { renderTree, treeJson } = await import('./tree.js');
+    const opts = { node: focusRaw && stripRefSigil(focusRaw), depth, color: process.stdout.isTTY && !process.env.NO_COLOR };
+    try {
+        // --json on a FOCUSED/pruned view is that view's JSON (the filtered subtree, badge counts precomputed);
+        // --json bare is the full payload above — the filter chooses which representation you asked for.
+        console.log(has('json') ? JSON.stringify(treeJson(board.nodes, opts), null, 2) : renderTree(board.nodes, opts));
+    }
+    catch (e) {
+        console.error(`spex graph: ${e?.message ?? e}`);
+        process.exit(2);
+    }
+    await flushExit(0);
+}
+else if (cmd === 'spec') {
+    const sub = process.argv[3];
+    if (sub === undefined) {
+        console.log((await import('./help.js')).commandHelp('spec'));
+    }
+    else if (sub === 'search') {
+        const { searchSpecs, nearestTitles } = await import('./search.js');
+        const query = positionals(4).join(' ');
+        if (!query.trim()) {
+            console.error('usage: spex spec search <query> [--json] [--limit N]');
+            process.exit(2);
+        }
+        const limit = Number(flag('limit')) || 10;
+        const results = await searchSpecs(query, { limit, onStats: (s) => console.error(`[spec-search] compute ${s.ms.toFixed(1)}ms · ${s.nodes} nodes · ${s.tokens} tokens (excludes process start)`) });
+        // zero-result fail-loud + route-to-next-step: always the corpus-is-English fact (unconditional — no
+        // language sniffing, no score threshold), plus the nearest titles when anything is even near (typo
+        // recovery) and the browse-all pointer, so no query dead-ends.
+        const NO_MATCH = (q) => {
+            const near = nearestTitles(q, 3);
+            return [
+                `no spec node matches "${q}" (the corpus is English — if your query isn't, translate and retry)`,
+                ...(near.length ? ['nearest titles:', ...near.map((t) => `  ${t.title}  [${t.id}]`)] : []),
+                'browse all: spex graph',
+            ].join('\n');
+        };
+        if (has('json')) {
+            if (!results.length)
+                console.error(NO_MATCH(query)); // stderr: the stdout JSON contract stays verbatim
+            console.log(JSON.stringify(results));
+            await flushExit(0);
+        }
+        if (!results.length) {
+            console.log(NO_MATCH(query));
+            process.exit(0);
+        }
+        results.forEach((r, i) => {
+            console.log(`${String(i + 1).padStart(2)}. ${r.title}  [${r.id}]  ·  score ${r.score}`);
+            console.log(`    ${r.path}`);
+            if (r.snippet)
+                console.log(`    ${r.snippet}`);
+        });
+        process.exit(0);
+    }
+    else if (sub === 'owner') {
+        // BOTH [[governed-related]] relations, distinctly: governors (code: — the verdict) and referencers
+        // (related: — pointers; coverage only, never drift, never eval freshness).
+        const { specOwners, specRelated } = await import('@spexcode/spec-core');
+        const { loadConfig } = await import('./lint.js');
+        const p0 = positionals(4)[0];
+        if (!p0) {
+            console.error('usage: spex spec owner <path> [--actionable]');
+            process.exit(2);
+        }
+        const p = stripRefSigil(p0);
+        const rel = p.startsWith(process.cwd()) ? p.slice(process.cwd().length + 1) : p;
+        const owners = specOwners(p);
+        const related = specRelated(p);
+        const maxOwners = loadConfig(process.cwd()).maxOwners;
+        // a selector-SCOPED governor (every claiming code: entry carries `#symbol` — [[code-anchor]]) still
+        // DISPLAYS, marked, but does not count toward the too-many-owners bound: it claims named units, not
+        // the whole file.
+        const whole = owners.filter((o) => !o.scoped);
+        const names = (xs) => xs.map((o) => `'${o.id}'${o.scoped ? ' (scoped)' : ''}`).join(', ');
+        const relLine = related.length ? `\n  also referenced by ${names(related)} (related: coverage only — no drift, no eval freshness)` : '';
+        if (owners.length === 0 && related.length === 0) {
+            console.log(`${rel} — no spec claims this yet (uncovered). If your change is substantive, give it a home before it drifts.`);
+        }
+        else if (owners.length === 0) {
+            // related-only: lint's coverage is satisfied, so the per-edit hook stays silent (lint-consistent) —
+            // but a human asking gets the honest nuance about what does and does not track this file.
+            if (has('actionable'))
+                process.exit(0);
+            // @@@ both axes - "nothing tracks its drift" is a verdict about the WHOLE tracking model
+            // ([[governed-related]]: spec nodes AND eval scenarios), so it cannot be spoken from the spec axis
+            // alone — a scenario's code: anchor drives eval freshness with no spec claim involved. Derived, never
+            // asserted: a message that enumerates one axis cannot report what the other holds. The empty
+            // nodeCode fallback is exact HERE and only here — reaching this branch means no spec node code:-claims
+            // the file, so no scenario can anchor to it by inheriting its node's claim, only by an explicit one.
+            const { evalNodes, scenarioCodeAxis } = await import('@spexcode/spec-eval/scenarios');
+            const anchored = [];
+            for (const n of evalNodes(process.cwd())) {
+                for (const sc of n.scenarios) {
+                    if (scenarioCodeAxis(sc.code).paths.includes(rel))
+                        anchored.push(`'${n.id}' scenario '${sc.name}'`);
+                }
+            }
+            const tracking = anchored.length
+                ? `Its drift is tracked on the eval axis only: ${anchored.length} scenario${anchored.length === 1 ? '' : 's'} anchor${anchored.length === 1 ? 's' : ''} freshness to it (${anchored.join(', ')}), so changing it makes those measurements stale — but no spec body says what it should do`
+                : 'Nothing tracks its drift';
+            console.log(`${rel} — not governed (no code: claim), but referenced by ${names(related)} (related: coverage only). ${tracking}; if your change is substantive, consider giving it a governing home.`);
+        }
+        else if (whole.length <= maxOwners) {
+            // a sanely-owned file is NOT actionable: --actionable callers (the per-edit spec-of-file hook) stay
+            // silent here, so the annotation fires only on an OVER-owned or uncovered file — rare and worth acting on.
+            if (has('actionable'))
+                process.exit(0);
+            const named = names(owners);
+            const lead = owners.length === 1 ? `${rel} is governed by ${named} — ${owners[0].desc}` : `${rel} is governed by ${named} (shared, fine).`;
+            console.log(`${lead} Read/honor the spec; if your change shifts the intent, update the spec in the SAME commit.${relLine}`);
+        }
+        else {
+            const ids = names(owners);
+            console.log(`${rel} is governed whole-file by ${whole.length} specs (all claims: ${ids}) — more than one file should hold. This file does TOO MUCH: SPLIT it so each governor owns its own module (or merge the nodes if they're one concern, or give it a single foundation owner + relate the rest).${relLine}`);
+        }
+    }
+    else if (sub === 'lint') {
+        const { specLintReport, pendingTouchesGoverned, DRIFT_GUIDANCE } = await import('./lint.js');
+        const pending = flag('pending');
+        if (pending && process.env.SPEXCODE_GATE_SCOPE_ONLY === '1') {
+            const touches = await pendingTouchesGoverned(process.cwd(), pending);
+            if (!touches)
+                process.exit(76);
+        }
+        const report = await specLintReport(undefined, undefined, {
+            tip: pending || 'HEAD',
+        });
+        const { findings } = report;
+        const errors = findings.filter((f) => f.level === 'error');
+        if (has('json')) {
+            console.log(JSON.stringify(report, null, 2));
+            await flushExit(errors.length ? 1 : 0);
+        }
+        for (const f of findings)
+            console.error(`  ${f.level === 'error' ? '✗' : '•'} ${f.rule}: ${f.msg}`);
+        console.error(`spex spec lint: ${errors.length} error(s), ${findings.length - errors.length} warning(s)`);
+        // drift teaches from the ONE `spex spec lint` (no flag). Unanchored drift stays advisory forever; the
+        // Blocking tier is anchor-drift ([[code-anchor]]) — CI/default lint judges HEAD; the local armed hook
+        // supplies --pending <real commit oid>; canonical pre-commit leaves the whole lint to that one run.
+        if (findings.some((f) => f.rule === 'drift' || f.rule === 'anchor-drift'))
+            console.error(`\n${DRIFT_GUIDANCE}`);
+        process.exit(errors.length ? 1 : 0);
+    }
+    else if (sub === 'ack') {
+        // An EMPTY stamp commit on top of HEAD, never an amend: driftFor (git.ts) quiets every drift commit
+        // REACHABLE from an ack, so a child stamp covers exactly what amending HEAD would — and it works where
+        // amend can't: on a trunk merge commit, re-authoring it after MERGE_HEAD is gone reads to main-guard as
+        // a direct trunk commit. The guard passes the stamp through its tree-unchanged gate instead. `--only`
+        // with no paths pins the commit to HEAD's tree even when the index is dirty — an ack must never sweep
+        // staged files along. git de-dupes adjacent trailers, so re-acking is harmless.
+        const { git } = await import('@spexcode/spec-core');
+        const nodes = positionals(4);
+        const reason = (flag('reason') ?? '').trim();
+        if (!nodes.length || !reason) {
+            console.error('usage: spex spec ack <node-id>… --reason "<why this change keeps each spec valid>"');
+            console.error('  --reason is required (it forces you to check before acking) and is recorded in the ack commit\'s message body — an ack that quiets an anchor hit is a strong claim, so its why must be durable.');
+            process.exit(2);
+        }
+        try {
+            git(['commit', '--only', '--allow-empty', '-m', `ack: Spec-OK ${nodes.join(', ')}`, '-m', reason,
+                ...nodes.flatMap((n) => ['--trailer', `Spec-OK: ${n}`])]);
+            console.log(`Spec-OK: ${nodes.join(', ')} → ${git(['rev-parse', '--short', 'HEAD']).trim()}  (empty stamp commit; reason recorded in the commit body)`);
+        }
+        catch (e) {
+            console.error(`ack failed: ${e?.message ?? e}`);
+            process.exit(1);
+        }
+    }
+    else {
+        console.error(`spex spec: unknown verb '${sub}' — search | owner | lint | ack  (spex help spec)`);
+        process.exit(2);
+    }
+}
+else if (cmd === 'init') {
+    // scaffold a repo to adopt SpexCode: copy the shipped DATA templates (seed spec tree + git hooks)
+    // into <targetDir> (default cwd). spex init [targetDir] --harness <ids> [--preset <tier>]
+    const { specInit } = await import('./init.js');
+    await specInit(positionals(3)[0], flag('preset'), flag('harness'));
+}
+else if (cmd === 'uninstall') {
+    // the surgical inverse of init: remove every SpexCode-generated artifact (harness shims/contract/trust, the
+    // .gitignore block, the global store, any plugin bundle) — NEVER the user's .spec/.plugins data or their own
+    // prose. Git hooks preserved unless --hooks. spex uninstall [targetDir] [--hooks]
+    const { uninstall } = await import('./uninstall.js');
+    uninstall(positionals(3)[0], { hooks: has('hooks') });
+}
+else if (cmd === 'eval') {
+    const sub = process.argv[3];
+    if (sub === undefined) {
+        console.log((await import('./help.js')).commandHelp('eval'));
+    }
+    else if (sub === 'ls' && flag('session') !== undefined) {
+        // the session EVAL read ([[session-eval]]'s interactive face as a CLI verb): the dashboard Eval tab's
+        // text twin. Renders the session's changed nodes with each DECLARED scenario at its CURRENT score
+        // (latest reading per scenario, worktree-rooted) — filed results keep the backend's newest-first order
+        // across ownership, the session's OWN measurements are ✦-marked, and blind spots follow. --export writes
+        // the self-contained HTML artifact instead.
+        const id = await resolveSelectorOrExit(flag('session'));
+        if (has('export'))
+            await evalExport(id);
+        const { clientEvals } = await import('./client.js');
+        const r = await clientEvals(id);
+        if (!r.ok) {
+            console.error(`no evals for ${id} (status ${r.status})`);
+            process.exit(1);
+        }
+        if (has('json')) {
+            console.log(JSON.stringify(r.model, null, 2));
+            await flushExit(0);
+        }
+        const m = r.model;
+        const own = m.items.filter((item) => item.inSession).length;
+        console.log(`eval session  [${m.id}]`);
+        if (m.gates.length)
+            console.log(`  gates  : ${m.gates.map((g) => `${g.ok ? '✓' : '✗'} ${g.label} — ${g.detail}`).join(' · ')}`);
+        if (own)
+            console.log(`  ✦      : ${own} scenario(s) measured by THIS session (unmarked rows = evals filed by other sessions)`);
+        if (!m.items.length)
+            console.log('\n  no affected scenarios to evaluate yet');
+        let lastNode = null;
+        for (const e of m.items) {
+            if (e.node !== lastNode) {
+                console.log(`\n${e.node}`);
+                lastNode = e.node;
+            }
+            if (e.filterKind === 'blind') {
+                console.log(`      ∅ unmeasured  ${e.scenario}  — declared, never measured (blind spot)`);
+                continue;
+            }
+            const verdict = e.verdict?.status === 'pass' ? '✓ pass' : e.verdict?.status === 'fail' ? '✗ fail' : '· unscored';
+            const stale = e.fresh ? '' : ` (stale: ${(e.staleAxes || []).join(',')})`;
+            console.log(`    ${e.inSession ? '✦' : ' '} ${verdict}${stale}  ${e.scenario}  — ${e.ts}${e.evaluator ? ` · ${e.evaluator}` : ''}`);
+        }
+    }
+    else if (['add', 'ls', 'scenario', 'lint', 'ok', 'retract', 'clean'].includes(sub)) {
+        // node-scoped verbs — thin route; the logic lives in spec-eval.
+        const { runEval } = await import('@spexcode/spec-eval/cli');
+        await flushExit(await runEval(process.argv.slice(3)));
+    }
+    else {
+        console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls/write | lint | ok | retract | clean  (spex help eval)`);
+        if (!sub.startsWith('--'))
+            console.error(`  (the old \`spex eval <SEL>\` session read is now \`spex eval ls --session <SEL>\` [--export])`); // dead-words-ok: signpost — one-version tombstone teaching the renamed spelling (0.4.0 removes it)
+        process.exit(2);
+    }
+}
+else if (cmd === 'evidence') {
+    if (process.argv[3] === undefined) {
+        console.log((await import('./help.js')).commandHelp('evidence'));
+    }
+    else {
+        const { runEvidence } = await import('@spexcode/spec-eval/cli');
+        await flushExit(await runEvidence(process.argv.slice(3)));
+    }
+}
+else if (cmd === 'issue') {
+    if (process.argv[3] === undefined) {
+        console.log((await import('./help.js')).commandHelp('issue'));
+    }
+    else {
+        const { runIssues } = await import('./issues-cli.js');
+        await flushExit(await runIssues(process.argv.slice(3)));
+    }
+}
+else if (cmd === 'remark') {
+    const sub = process.argv[3];
+    const m = sub === 'add' || sub === 'resolve' || sub === 'retract' ? await import('./issues-cli.js') : null;
+    if (sub === undefined) {
+        console.log((await import('./help.js')).commandHelp('remark'));
+    }
+    else if (sub === 'add') {
+        await flushExit(await m.runRemark(process.argv.slice(4)));
+    }
+    else if (sub === 'resolve') {
+        await flushExit(await m.runResolve(process.argv.slice(4)));
+    }
+    else if (sub === 'retract') {
+        await flushExit(await m.runRetract(process.argv.slice(4)));
+    }
+    else {
+        console.error(`spex remark: unknown verb '${sub}' — add | resolve | retract  (spex help remark)`);
+        if (!sub.startsWith('--'))
+            console.error('  (the old bare `spex remark <host> --body …` write is now `spex remark add <host> --body …`)');
+        process.exit(2);
+    }
+}
+else if (cmd === 'materialize') {
+    const { materialize } = await import('./materialize.js');
+    try {
+        console.log(`materialized — content-hash ${materialize().contentHash}`);
+    }
+    catch (e) {
+        // a policy error (e.g. a missing/illegal `harnesses` set) is a user-facing verdict, not a crash — one
+        // line + the repair it already carries, never a stack trace.
+        console.error(`spex materialize: ${e.message}`);
+        process.exit(1);
+    }
+}
+else if (cmd === 'doctor') {
+    const { runDoctor } = await import('./doctor.js');
+    await flushExit(await runDoctor(process.argv.slice(3)));
+}
+else if (cmd === 'flat') {
+    const { runFlat } = await import('./flat.js');
+    await flushExit(await runFlat(process.argv.slice(3)));
+}
+else if (cmd === 'peer') {
+    const sub = process.argv[3];
+    if (sub === undefined) {
+        console.log((await import('./help.js')).commandHelp('peer'));
+    }
+    else if (sub === 'connect' || sub === 'disconnect') {
+        rejectUnknownFlags(`spex peer ${sub}`, 4, []);
+        const address = positionals(4);
+        if (address.length !== 1) {
+            console.error(`usage: spex peer ${sub} <SSH-ADDRESS>`);
+            process.exit(2);
+        }
+        const { peerControlOrThrow } = await import('./machine-peer.js');
+        try {
+            const peer = await peerControlOrThrow({ op: sub, sshAddress: address[0] });
+            if (!Array.isArray(peer))
+                console.log(`${sub === 'connect' ? 'connected' : 'disconnected'} ${peer.sshAddress} (${peer.machineId})`);
+        }
+        catch (error) {
+            console.error(`spex peer ${sub}: ${error.message}`);
+            process.exit(1);
+        }
+    }
+    else if (sub === 'ls') {
+        rejectUnknownFlags('spex peer ls', 4, ['json']);
+        const { peerControlOrThrow } = await import('./machine-peer.js');
+        try {
+            const peers = await peerControlOrThrow({ op: 'list' });
+            if (!Array.isArray(peers))
+                throw new Error('peer service returned an invalid list');
+            if (has('json'))
+                console.log(JSON.stringify(peers, null, 2));
+            else
+                for (const peer of peers)
+                    console.log(`${peer.state.padEnd(10)} ${peer.sshAddress}  ${peer.machineId}  ${peer.owner ? 'owner' : 'reverse'}`);
+        }
+        catch (error) {
+            console.error(`spex peer ls: ${error.message}`);
+            process.exit(1);
+        }
+    }
+    else {
+        console.error(`spex peer: unknown verb '${sub}' — connect | ls | disconnect  (spex help peer)`);
+        process.exit(2);
+    }
+}
+else if (cmd === 'session') {
+    const sub = process.argv[3];
+    if (sub === undefined) {
+        console.log((await import('./help.js')).commandHelp('session'));
+    }
+    else if (SESSION_SIGNPOSTS[sub]) {
+        signpost(`spex session ${sub}`, SESSION_SIGNPOSTS[sub]);
+    }
+    else if (sub === 'new') {
+        // spex session new "<prompt>"  (prompt = first positional or --prompt, or --prompt-file
+        // <path>|- so a long multi-paragraph prompt never fights shell quoting — [[prompt-file]]).
+        // createSession POSTs to the running backend so the launch runs in the backend's process (auth env + cap);
+        // it falls back to an in-process launch only when no backend answers.
+        if (has('node')) {
+            console.error('spex session new: --node was removed — put a [[<id>]] mention in the prompt — the first mention binds');
+            process.exit(2);
+        }
+        const newPositionals = positionals(4);
+        const peerAnchor = parseSessionPeerAnchor('new', newPositionals);
+        rejectUnknownBackendFlags('spex session new', 4, ['prompt', 'prompt-file', 'launcher', 'name', 'base', 'ssh']);
+        if (peerAnchor && newPositionals.length > 2)
+            sessionPeerAnchorUsage('new', '--ssh accepts one full-id anchor and one inline prompt at most');
+        const { createSession, ownSessionId, withPeerSenderHint } = await import('./sessions.js');
+        const promptFile = flag('prompt-file');
+        const explicitPrompt = flag('prompt');
+        if (peerAnchor && explicitPrompt !== undefined && newPositionals.length !== 1)
+            sessionPeerAnchorUsage('new', 'give the prompt either after the full-id anchor or via --prompt, not both');
+        const inline = explicitPrompt ?? newPositionals[peerAnchor ? 1 : 0];
+        let prompt = inline ?? '';
+        if (promptFile !== undefined) {
+            // fail-loud exclusive: never silently pick one of two prompt sources.
+            if (inline !== undefined) {
+                console.error('spex session new: give the prompt either inline or via --prompt-file, not both');
+                process.exit(2);
+            }
+            const { readFileSync } = await import('node:fs');
+            try {
+                prompt = promptFile === '-' ? readFileSync(0, 'utf8') : readFileSync(promptFile, 'utf8');
+            }
+            catch (e) {
+                console.error(`spex session new: --prompt-file ${promptFile}: ${e instanceof Error ? e.message : e}`);
+                process.exit(2);
+            }
+            if (!prompt.trim()) {
+                console.error(`spex session new: --prompt-file ${promptFile === '-' ? 'stdin' : promptFile} is empty — refusing a promptless launch`);
+                process.exit(2);
+            }
+        }
+        let peerPrompt = prompt;
+        if (peerAnchor) {
+            const senderId = ownSessionId();
+            if (senderId) {
+                const { readPeerMachineId } = await import('./machine-peer.js');
+                peerPrompt = withPeerSenderHint(prompt, { id: senderId, label: null }, peerAnchor.sshAddress, readPeerMachineId());
+            }
+        }
+        const created = peerAnchor
+            ? await (await import('./client.js')).clientCreateThroughPeer(peerAnchor.sshAddress, peerAnchor.sessionId, {
+                prompt: peerPrompt, launcher: flag('launcher') ?? undefined, name: flag('name') ?? undefined, base: flag('base') ?? undefined,
+            })
+            : await createSession(prompt, flag('launcher') ?? undefined, flag('name') ?? undefined, flag('base') ?? undefined);
+        let watchEstablished = false;
+        if (!peerAnchor && created.parent && created.parent === ownSessionId()) {
+            try {
+                const { subscribeSessionWatch } = await import('./sessions.js');
+                await subscribeSessionWatch(created.parent, [created.id], 'parent');
+                watchEstablished = true;
+            }
+            catch (error) {
+                console.error(`spex session new: child ${created.id} was created, but its managed watch was not established: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        console.log(JSON.stringify(created, null, 2));
+        const help = await import('./help.js');
+        console.error(peerAnchor
+            ? help.peerSessionLaunchReceipt(created.id, peerAnchor.sshAddress)
+            : help.sessionLaunchReceipt(created.id, watchEstablished));
+    }
+    else if (sub === 'ls') {
+        // pretty list of living sessions + states. `spex session ls [SEL...] [--children[=PARENT-SEL]] [--status a,b] [--json]`
+        // the board comes from the backend (so it shows the sessions of whatever SPEXCODE_API_URL points at,
+        // incl. a remote machine); selectSessions/formatTable are pure presentation, applied client-side.
+        const { ownSessionId, resolveSession, selectChildren, selectSessions, formatTable } = await import('./sessions.js');
+        const { clientListSessions, clientListSessionsThroughPeer, clientSessionClosure } = await import('./client.js');
+        // The backend's default projection excludes cold archives. --all and an explicit selector request the
+        // history projection so an operator can still inspect or unarchive one deliberately.
+        const selectors = positionals(4);
+        rejectUnknownBackendFlags('spex session ls', 4, ['status', 'all', 'json', 'ssh', 'children'], ['children']);
+        const peerAnchor = parseSessionPeerAnchor('ls', selectors);
+        const children = childrenScopeOption();
+        if (peerAnchor && selectors.length !== 1)
+            sessionPeerAnchorUsage('ls', '--ssh accepts exactly one full-id project anchor, not session selectors');
+        if (peerAnchor && has('all'))
+            sessionPeerAnchorUsage('ls', '--all is unavailable through a machine peer');
+        if (peerAnchor && children === null)
+            sessionPeerAnchorUsage('ls', '--children over a machine peer requires --children=<remote-parent-SEL>');
+        const visible = peerAnchor
+            ? await clientListSessionsThroughPeer(peerAnchor.sshAddress, peerAnchor.sessionId)
+            : await clientListSessions(has('all') || selectors.length > 0);
+        let scoped = visible;
+        let scope = { kind: 'sessions' };
+        if (children !== undefined) {
+            let parent;
+            if (children === null) {
+                parent = ownSessionId() || '';
+                if (!parent) {
+                    console.error('spex session ls: --children needs a governed caller session; use --children=<PARENT-SEL> from a human shell');
+                    process.exit(2);
+                }
+            }
+            else {
+                const resolved = resolveSession(children, visible);
+                if ('ok' in resolved)
+                    parent = resolved.ok.id;
+                else if ('ambiguous' in resolved) {
+                    console.error(`spex session ls: parent selector ${children} is ambiguous: ${resolved.ambiguous.map((session) => session.id.slice(0, 8)).join(', ')}`);
+                    process.exit(2);
+                }
+                else {
+                    const pointed = [...new Set(visible.flatMap((session) => session.parent && (session.parent === children || session.parent.startsWith(children)) ? [session.parent] : []))];
+                    if (pointed.length === 1)
+                        parent = pointed[0];
+                    else if (pointed.length > 1) {
+                        console.error(`spex session ls: parent selector ${children} is ambiguous: ${pointed.map((id) => id.slice(0, 8)).join(', ')}`);
+                        process.exit(2);
+                    }
+                    else {
+                        console.error(`spex session ls: no session or child-parent pointer matches ${children}`);
+                        process.exit(2);
+                    }
+                }
+            }
+            scoped = selectChildren(visible, parent);
+            scope = { kind: 'children', parent };
+        }
+        const selected = selectSessions(scoped, peerAnchor ? [] : selectors);
+        const picked = flag('status') ? selected.filter((session) => flag('status').split(',').includes(session.status)) : selected;
+        if (!peerAnchor && children === undefined && selectors.length === 1 && !selected.length && idLikeSelector(selectors[0])) {
+            const closure = await clientSessionClosure(selectors[0]);
+            if (closure) {
+                const result = { id: closure.id, status: 'closed', closedAt: closure.closedAt };
+                console.log(has('json') ? JSON.stringify([result], null, 2) : `${closure.id.slice(0, 8)}: closed at ${closure.closedAt}`);
+            }
+            else {
+                console.error(`spex session ls: ${selectors[0]} was not found in this project's live, archive, or terminal-close history`);
+                process.exit(2);
+            }
+        }
+        else {
+            console.log(has('json') ? JSON.stringify(picked, null, 2) : formatTable(picked, true, scope));
+        }
+    }
+    else if (sub === 'resources') {
+        rejectUnknownBackendFlags('spex session resources', 4, ['json']);
+        const { clientResources } = await import('./client.js');
+        const report = await clientResources();
+        if (has('json'))
+            console.log(JSON.stringify(report, null, 2));
+        else
+            console.log((await import('./host-resources.js')).formatResourceReport(report));
+    }
+    else if (sub === 'files') {
+        rejectUnknownFlags('spex session files', 4, []);
+        const [verb, path, extra] = positionals(4);
+        if (extra || !verb || (verb !== 'ls' && !path) || (verb === 'ls' && path)) {
+            console.error('usage: spex session files add <path> | ls | retract <path>');
+            process.exit(2);
+        }
+        const { ownSessionId, withSessionRecordLockSync } = await import('./sessions.js');
+        const id = ownSessionId();
+        if (!id) {
+            console.error('spex session files: no governed caller session — run this from the agent session that produced the file');
+            process.exit(2);
+        }
+        const files = await import('./session-files.js');
+        if (verb === 'ls') {
+            for (const file of files.listSessionFiles(id))
+                console.log(file);
+        }
+        else if (verb === 'add') {
+            const result = files.addSessionFile(id, path, withSessionRecordLockSync);
+            console.log(result.added ? `posted ${result.path}` : `already posted ${result.path}`);
+        }
+        else if (verb === 'retract') {
+            const result = files.retractSessionFile(id, path, withSessionRecordLockSync);
+            if (!result.removed) {
+                console.error(`spex session files retract: path is not posted: ${result.path}`);
+                process.exit(2);
+            }
+            console.log(`retracted ${result.path}`);
+        }
+        else {
+            console.error(`spex session files: unknown verb '${verb}' — add | ls | retract  (spex help session)`);
+            process.exit(2);
+        }
+    }
+    else if (sub === 'web') {
+        rejectUnknownFlags('spex session web', 4, []);
+        const [verb, url, extra] = positionals(4);
+        if (extra || !verb || (verb !== 'ls' && !url) || (verb === 'ls' && url)) {
+            console.error('usage: spex session web add <url> | ls | retract <url>');
+            process.exit(2);
+        }
+        const { ownSessionId, withSessionRecordLockSync } = await import('./sessions.js');
+        const id = ownSessionId();
+        if (!id) {
+            console.error('spex session web: no governed caller session — run this from the agent session that started the local service');
+            process.exit(2);
+        }
+        const web = await import('./session-web.js');
+        if (verb === 'ls') {
+            for (const entry of web.listSessionWebs(id))
+                console.log(entry.url);
+        }
+        else if (verb === 'add') {
+            const result = web.addSessionWeb(id, url, withSessionRecordLockSync);
+            console.log(result.added ? `posted ${result.url}` : `already posted ${result.url}`);
+        }
+        else if (verb === 'retract') {
+            const result = web.retractSessionWeb(id, url, withSessionRecordLockSync);
+            if (!result.removed) {
+                console.error(`spex session web retract: URL is not posted: ${result.url}`);
+                process.exit(2);
+            }
+            console.log(`retracted ${result.url}`);
+        }
+        else {
+            console.error(`spex session web: unknown verb '${verb}' — add | ls | retract  (spex help session)`);
+            process.exit(2);
+        }
+    }
+    else if (sub === 'watch') {
+        const [verb, ...rest] = positionals(4);
+        const { ownSessionId, subscribeSessionWatch, listSessionWatches, cancelSessionWatch } = await import('./sessions.js');
+        const watcher = ownSessionId();
+        if (verb === 'stream') {
+            const kit = await followKit(rest, 'spex session watch stream');
+            await kit.follow((line) => console.log(line), {
+                statuses: flag('status')?.split(','),
+                includeIdle: has('idle'),
+                as: flag('as'),
+                intervalMs: (Number(flag('interval')) || 1) * 1000,
+            });
+        }
+        else if (verb === 'list') {
+            if (!watcher) {
+                console.error('spex session watch list: no governed caller session — this caller has no durable watch relation');
+                process.exit(2);
+            }
+            for (const watch of listSessionWatches(watcher))
+                console.log(`${watch.target}\t${watch.createdAt}`);
+        }
+        else if (verb === 'cancel') {
+            if (!watcher) {
+                console.error(`spex session watch cancel: no governed caller session — run \`spex session wait ${rest.join(' ')}\` in the background instead`);
+                process.exit(2);
+            }
+            const targets = await localWatchTargetsOrExit(rest, 'spex session watch cancel');
+            console.log(`cancelled ${cancelSessionWatch(watcher, targets)} watch${targets.length === 1 ? '' : 'es'}`);
+        }
+        else {
+            const selectors = [verb, ...rest].filter(Boolean);
+            if (!watcher) {
+                if (!selectors.length) {
+                    console.error('usage: spex session watch <SEL...>');
+                    process.exit(2);
+                }
+                console.error(`spex session watch: no governed caller session — run \`spex session wait ${selectors.join(' ')}\` in the BACKGROUND to receive the next actionable transition`);
+            }
+            else {
+                const targets = await localWatchTargetsOrExit(selectors, 'spex session watch');
+                const result = await subscribeSessionWatch(watcher, targets);
+                console.log(`watching ${result.watched.join(' ')}`);
+            }
+        }
+    }
+    else if (sub === 'wait') {
+        const selectors = positionals(4);
+        const kit = await followKit(selectors, 'spex session wait');
+        const named = selectors.join(' ') || 'your own log';
+        // point-of-use turn-freeze warning ([[session-follow]]): a managed agent that runs this wait in the FOREGROUND
+        // freezes its whole turn until the target produces an edge — a warning that used to live only in help
+        // prose, now said where it matters. Foreground vs background is invisible from here, so the hint prints
+        // for ANY managed-agent shell (harmless in a background transcript), on stderr, and changes nothing else.
+        if (kit.watcher)
+            console.error(`spex session wait: heads-up (managed agent ${kit.watcher.slice(0, 8)}) — this command BLOCKS until it OBSERVES ${named} transition from non-actionable into an actionable status, or a message arrives for you (edge-triggered: an already-actionable current state does NOT return it — to just read the state now, use \`spex session ls\`/\`review\`); run it in the BACKGROUND or it freezes your whole turn (its exit is your wake-up). Proceeding.`);
+        const timeoutSec = Number(flag('timeout')) || 1200;
+        const r = await kit.follow(() => { }, {
+            includeIdle: has('idle'),
+            intervalMs: (Number(flag('interval')) || 1) * 1000,
+            take: true,
+            timeoutMs: timeoutSec * 1000,
+            // the arrival state and each observed transition narrate on stderr AS THEY HAPPEN, so a backgrounded
+            // wait's transcript is the state sequence itself; stdout stays the one machine verdict.
+            onObserved: (sid, st, was) => console.error(was
+                ? `spex session wait: observed ${sid.slice(0, 8)} ${was} → ${st}`
+                : `spex session wait: ${sid.slice(0, 8)} current status ${st} — recorded as the path start; returns on the next non-actionable→actionable transition`),
+        });
+        // the observed status path is the stdout verdict: read the LAST token as the status reached. Printing the
+        // whole path (not just the final status) is the point — a manager sees what the wait lived through
+        // (e.g. review→working→close-pending across a merge dispatch), not a bare word out of context.
+        if ('reached' in r) {
+            console.log(r.path.join('→'));
+            process.exit(0);
+        }
+        if ('mail' in r) {
+            console.error(`spex session wait: message from ${r.mail.from ?? 'a human'} — ${r.mail.text}`);
+            console.log('message');
+            process.exit(0);
+        }
+        if ('gone' in r) {
+            console.error(`spex session wait: session ${r.gone} is gone — its store dir no longer exists`);
+            process.exit(2);
+        }
+        console.error(`spex session wait: timeout — observed no non-actionable→actionable transition on ${named} within ${timeoutSec}s (status path: ${r.path.join('→') || 'never sighted'})`);
+        process.exit(1);
+    }
+    else if (sub === 'review') {
+        const first = positionals(4)[0];
+        if (first === 'proof')
+            signpost('spex review proof', 'spex eval ls --session <SEL> --export'); // dead-words-ok: signpost — one-version tombstone teaching the renamed spelling (0.4.0 removes it)
+        const { clientReview } = await import('./client.js');
+        if (!first) {
+            console.error('usage: spex session review <SEL>  (id | id-prefix | node | branch)');
+            process.exit(2);
+        }
+        const session = await resolveSessionOrExit(first);
+        const r = await clientReview(session.id);
+        if (!r) {
+            console.error(`no such session ${session.id}`);
+            process.exit(1);
+        }
+        if (has('json')) {
+            console.log(JSON.stringify(r, null, 2));
+        }
+        else {
+            const g = r.gates;
+            console.log(`review ${session.title}  [${r.id}]`);
+            console.log(`  ahead of main : ${r.ahead} commit(s)`);
+            console.log(`  uncommitted   : ${r.dirtyNonRuntime} non-runtime file(s)`);
+            console.log(`  proposal      : ${r.proposal.kind ?? '—'}${r.proposal.note ? ` — ${r.proposal.note}` : ''}`);
+            console.log('  gates:');
+            console.log(`    conflicts w/ main : ${g.conflictsWithMain ? 'YES' : 'no'}`);
+            console.log(`    lint              : ${g.lint.errorCount} error(s), ${g.lint.warningCount} warning(s)`);
+            // measured loss is REPORTED, never graded — and a projection that isn't ready says so instead of
+            // printing four zeros that would read as a clean session.
+            console.log(`    evals             : ${g.evals.phase === 'ready'
+                ? `${g.evals.freshPass} fresh pass, ${g.evals.freshFail} fresh fail, ${g.evals.needReview} need review, ${g.evals.blind} blind`
+                : `not measured yet (${g.evals.phase})`}`);
+            console.log(`  diff (merge-base, ${r.diff.length} file(s)):`);
+            for (const f of r.diff)
+                console.log(`    ${f.status.padEnd(12)} +${f.additions} -${f.deletions}  ${f.path}`);
+        }
+    }
+    else if (sub === 'merge') {
+        const { clientMerge } = await import('./client.js');
+        const sel = positionals(4)[0];
+        if (!sel) {
+            console.error('usage: spex session merge <SEL>  (id | id-prefix | node | branch)');
+            process.exit(2);
+        }
+        const id = await resolveSelectorOrExit(sel);
+        const r = await clientMerge(id);
+        if (r.dispatched)
+            console.log(`merge dispatched to ${id} — its agent is landing the merge`);
+        else
+            console.error(`merge dispatch failed: ${r.reason}`);
+        process.exit(r.dispatched ? 0 : 1);
+    }
+    else if (sub === 'done' || sub === 'park' || sub === 'ask') {
+        const { runSessionDeclaration } = await import('./session-declarations.js');
+        await runSessionDeclaration(sub, process.argv);
+    }
+    else {
+        // `c` (client.ts) backs the read/control subs that route through the backend. Lazily imported.
+        const sendArgs = sub === 'send' ? parseSessionSendArgs(process.argv.slice(4)) : null;
+        const targetArgs = sub === 'show' || sub === 'close' ? parseSessionTargetArgs(sub, process.argv.slice(4)) : null;
+        const c = await import('./client.js');
+        const id = sendArgs?.selector ?? targetArgs?.selector ?? process.argv[4];
+        if (sub === 'resume') {
+            // bring the agent back up (relaunch ONLY if confirmed offline, the backend owns it); demotes a working
+            // `active` to idle but leaves a standing declaration/proposal untouched (see sessions.ts resumeSession()).
+            // The RESUME GUARD refuses a relaunch on a LIVE/unproven agent (that would kill a live worker) — `--force`
+            // overrides for a genuinely wedged process. A following prompt is what actually re-drives it.
+            const full = await resolveSelectorOrExit(id);
+            const r = await c.clientResume(full, process.argv.includes('--force'));
+            if (r.ok)
+                console.log(r.info ? `${full} -> ${r.info}` : `${full} -> resumed`);
+            else {
+                console.error(`spex session resume: ${r.error || `no such session ${full}`}`);
+                process.exit(2);
+            }
+        }
+        else if (sub === 'stop') {
+            // the SOFT stop: kill the agent's tmux + socket but KEEP the worktree, so the session goes offline and
+            // can be resumed (`session resume`). Distinct from `close`, which removes the worktree.
+            const full = await resolveSelectorOrExit(id);
+            const stopped = await c.clientStop(full);
+            if (!stopped) {
+                console.error(`spex session stop: no such session ${full} (no stop transition was committed)`);
+                process.exit(1);
+            }
+            console.log(`stopped ${full} (worktree kept — resumable)`);
+        }
+        else if (sub === 'interrupt') {
+            const full = await resolveSelectorOrExit(id);
+            const r = await c.clientInterrupt(full);
+            console.log(r.ok ? `interrupted ${full}` : `interrupt failed: ${r.error}`);
+            process.exit(r.ok ? 0 : 1);
+        }
+        else if (sub === 'archive' || sub === 'unarchive') {
+            // ARCHIVING/legacy unarchive ([[archive]]) — archive exact-stops before filing; unarchive signposts to
+            // resume and recreates the same conversation.
+            const on = sub === 'archive';
+            const full = await resolveSelectorOrExit(id);
+            const ok = await c.clientArchive(full, on);
+            console.log(!ok ? `no such session ${full}` : `${on ? 'archived' : 'resumed'} ${full}`);
+        }
+        else if (sub === 'close') {
+            const full = targetArgs?.sshAddress
+                ? (FULL_SESSION_ID.test(id ?? '') ? id : sessionTargetUsage('close', '--ssh requires a full session id, not a selector'))
+                : await resolveSelectorOrExit(id);
+            const closed = targetArgs?.sshAddress
+                ? await c.clientCloseThroughPeer(targetArgs.sshAddress, full)
+                : await c.clientClose(full);
+            if (!closed) {
+                console.error(`spex session close: no such session ${full} (record remains; no close was committed)`);
+                process.exit(1);
+            }
+            console.log(`closed ${full}`);
+        }
+        else if (sub === 'quarantine') {
+            rejectUnknownBackendFlags('spex session quarantine', 4, ['adapter', 'thread', 'tmux', 'worktree', 'branch', 'restore']);
+            if (!id) {
+                console.error('usage: spex session quarantine <ID> --adapter <harness> [--thread <native-id>] --tmux <session-id> --worktree <absent-path> --branch <absent-branch> (--thread is adapter-native; omit it for Claude)');
+                process.exit(2);
+            }
+            if (has('restore')) {
+                // Quarantine addresses an unreadable row which selector resolution intentionally excludes. Both the
+                // move and its reverse therefore take the literal exact id, with the backend proving record state.
+                const restored = await c.clientRestoreQuarantine(id);
+                console.log(`restored quarantined record ${restored.id} from ${restored.bundle}`);
+            }
+            else {
+                const adapter = flag('adapter'), tmux = flag('tmux'), worktree = flag('worktree'), branch = flag('branch');
+                if (!adapter || !tmux || !worktree || !branch) {
+                    console.error('usage: spex session quarantine <ID> --adapter <harness> [--thread <native-id>] --tmux <session-id> --worktree <absent-path> --branch <absent-branch> (--thread is adapter-native; omit it for Claude)');
+                    process.exit(2);
+                }
+                const quarantined = await c.clientQuarantine(id, { adapter, thread: flag('thread') ?? null, tmux, worktree, branch });
+                console.log(`quarantined ${quarantined.id} -> ${quarantined.bundle}`);
+            }
+        }
+        else if (sub === 'reparent') {
+            rejectUnknownBackendFlags('spex session reparent', 4, ['to']);
+            const children = positionals(4);
+            const to = flag('to');
+            if (!children.length || !to) {
+                console.error('usage: spex session reparent <child-SEL...> --to <parent-SEL>');
+                process.exit(2);
+            }
+            const childIds = [...new Set(await Promise.all(children.map(resolveSelectorOrExit)))];
+            const parent = await resolveSelectorOrExit(to);
+            const { reparentSessions } = await import('./session-reparent.js');
+            const result = await reparentSessions(childIds, parent);
+            console.log(`reparented ${result.children.join(', ')} -> ${result.parent}`);
+        }
+        else if (sub === 'send') {
+            if (!sendArgs)
+                sessionSendUsage('arguments were not parsed');
+            const full = sendArgs.sshAddress
+                ? (FULL_SESSION_ID.test(id ?? '')
+                    ? id
+                    : sessionSendUsage('--ssh requires a full session id, not a selector'))
+                : await resolveSelectorOrExit(id);
+            if (sendArgs.kind === 'keys') {
+                // the LAST-RESORT face of send: forward raw nav-mode keystrokes (tmux send-keys, NEVER the prompt
+                // socket) — how a manager drives a worker wedged in an interactive TUI dialog the prompt channel
+                // can't reach (a select menu wanting one Enter/arrow). UNSTABLE, and able to confirm dangerous
+                // dialogs — try plain `session send` text FIRST; reach for --keys only when text provably can't
+                // land. Tokens = named keys, single chars, C-/M-/S- combos; whitespace-separated, delivered as ONE
+                // ordered batch ([[nav-mode-key-ordering]]). Fail-loud: nothing delivered exits non-zero.
+                if (await c.clientSendRawKeys(full, sendArgs.keys)) {
+                    console.log(`sent ${sendArgs.keys.length} key${sendArgs.keys.length === 1 ? '' : 's'} -> ${full}`);
+                    process.exit(0);
+                }
+                console.error(`spex session send --keys: nothing delivered to ${full} (offline, unknown session, or no valid key token)`);
+                process.exit(1);
+            }
+            // A send is accepted at its timeline append, except a proven-unreachable transport attached to a live
+            // registered agent: that stranded combination refuses before it can add unclaimable queue debt.
+            // BIDIRECTIONAL: stamp the SENDER (this send process's OWN session — the only process that knows it, via
+            // ownSessionId from CLAUDE_CODE_SESSION_ID) + a one-line reply hint into the delivered
+            // message, so the recipient can reply over the SAME send. The sender's row (hence its display label) is
+            // resolved through the shared resolver; a human in a plain shell has no session id → bare message, no
+            // hint (see [[agent-reply-channel]]).
+            const s = await import('./sessions.js');
+            const senderId = s.ownSessionId();
+            let sender = null;
+            if (senderId) {
+                const sr = await c.resolveClientSession(senderId);
+                // name the sender by the board HEADLINE (sessionHeadline — the live self-summary the recipient sees on
+                // the board), NOT the stable sessionLabel that stops at the bare prompt-truncation title.
+                sender = 'ok' in sr ? { id: sr.ok.id, label: s.sessionHeadline(sr.ok) } : { id: senderId, label: null };
+            }
+            let text = sendArgs.text;
+            let from = senderId ?? undefined;
+            if (sendArgs.sshAddress && sender) {
+                const { peerSenderRef, readPeerMachineId } = await import('./machine-peer.js');
+                const machineId = readPeerMachineId();
+                text = s.withPeerSenderHint(text, sender, sendArgs.sshAddress, machineId);
+                from = peerSenderRef(machineId, sender.id);
+            }
+            else if (!sendArgs.sshAddress) {
+                text = s.withSenderHint(text, sender);
+            }
+            const r = sendArgs.sshAddress
+                ? await c.clientSendThroughPeer(sendArgs.sshAddress, full, text, from)
+                : await c.clientSend(full, text, from);
+            if (r.ok) {
+                console.log('sent');
+                process.exit(0);
+            }
+            console.error(`dispatch failed: ${r.error}`);
+            process.exit(1);
+        }
+        else if (sub === 'show') {
+            // the session RECORD as one per-id read (status · node · branch · launcher · the full originating
+            // prompt); --capture swaps in the LIVE PANE face of the same read. The pane contract is unchanged from
+            // the verb it absorbed — fail and empty stay DISTINCT: a real empty pane prints nothing and exits 0;
+            // unknown id exits 2, offline / capture-error exit 1, each with a named reason.
+            const full = targetArgs?.sshAddress
+                ? (FULL_SESSION_ID.test(id ?? '') ? id : sessionTargetUsage('show', '--ssh requires a full session id, not a selector'))
+                : await resolveSelectorOrExit(id);
+            if (has('capture')) {
+                const r = await c.clientCapture(full);
+                if (r.ok) {
+                    process.stdout.write(r.pane);
+                }
+                else {
+                    console.error(`spex session show --capture: ${r.reason}`);
+                    process.exit(r.status === 404 ? 2 : 1);
+                }
+            }
+            else {
+                const r = targetArgs?.sshAddress
+                    ? await c.clientShowThroughPeer(targetArgs.sshAddress, full)
+                    : await c.clientShow(full);
+                if (!r.ok) {
+                    console.error(`spex session show: no such session ${full}`);
+                    process.exit(2);
+                }
+                if (has('json')) {
+                    console.log(JSON.stringify(r.session, null, 2));
+                }
+                else {
+                    const x = r.session;
+                    console.log(`${x.title}  [${x.id}]`);
+                    console.log(`  status   : ${x.status}  (lifecycle ${x.lifecycle} · liveness ${x.liveness})`);
+                    console.log(`  node     : ${x.node ?? '—'}`);
+                    console.log(`  branch   : ${x.branch ?? '—'}`);
+                    console.log(`  launcher : ${x.launcher ?? '—'}  (harness ${x.harness})`);
+                    console.log(`  worktree : ${x.path}`);
+                    console.log(`  created  : ${new Date(x.created).toISOString()}`);
+                    if (x.note)
+                        console.log(`  note     : ${x.note}`);
+                    if (x.proposal)
+                        console.log(`  proposal : ${x.proposal}`);
+                    console.log(x.prompt ? `  prompt   |\n${x.prompt.replace(/\n$/, '').split('\n').map((l) => `    ${l}`).join('\n')}` : '  prompt   : (none recorded)');
+                }
+            }
+        }
+        else if (sub === 'rename') {
+            // set the session's display-name override — the right-click rename ([[session-rename]]) as a verb, so an
+            // agent manager can fix a label without the GUI. An EXPLICIT "" clears back to the derived label; a
+            // MISSING argument is a usage error, never a silent clear. Unknown session → the endpoint's 404, loud.
+            const full = await resolveSelectorOrExit(id);
+            const name = process.argv[5];
+            if (name === undefined) {
+                console.error('usage: spex session rename <SEL> "<name>"   (an explicit "" clears the override)');
+                process.exit(2);
+            }
+            if (await c.clientRename(full, name))
+                console.log(name.trim() ? `${full} -> renamed "${name.trim()}"` : `${full} -> name cleared (derived label restored)`);
+            else {
+                console.error(`spex session rename: no such session ${full}`);
+                process.exit(2);
+            }
+        }
+        else if (sub === 'attach') {
+            // the HUMAN escape hatch (attach.ts, [[session-attach]]): foreground `tmux attach` into the worker's
+            // real session. Guards fail loud BEFORE resolving: local-only (the tmux server is the backend
+            // machine's) and terminal-only (an agent must never block its turn on it — capture/send).
+            const { assertLocalBackend, attachSession } = await import('./attach.js');
+            await assertLocalBackend();
+            process.exit(await attachSession(await resolveSelectorOrExit(id)));
+        }
+        else {
+            console.error(`spex session: unknown verb '${sub}' — new | ls | files | web | show | watch | wait | review | merge | reparent | send | interrupt | rename | resume | stop | close | attach | done | park | ask  (spex help session)`);
+            process.exit(2);
+        }
+    }
+}
+else if (cmd === 'internal') {
+    const sub = process.argv[3];
+    if (sub === 'peer-accept' || sub === 'peer-drop') {
+        const encoded = process.argv[4];
+        if (!encoded) {
+            console.error(`usage: spex internal ${sub} <base64url-json>`);
+            process.exit(2);
+        }
+        let body;
+        try {
+            const parsed = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new Error('not an object');
+            body = parsed;
+        }
+        catch {
+            console.error(`spex internal ${sub}: invalid base64url JSON`);
+            process.exit(2);
+        }
+        const { peerRpc } = await import('./machine-peer.js');
+        const request = sub === 'peer-accept' ? { ...body, op: 'accept' } : { ...body, op: 'drop' };
+        try {
+            console.log(JSON.stringify(await peerRpc(request)));
+        }
+        catch (error) {
+            console.error(`spex internal ${sub}: ${error.message}`);
+            process.exit(1);
+        }
+    }
+    else if (sub === 'trunk') {
+        // print the resolved source-of-truth branch (layout.ts mainBranch(): config override → the main
+        // checkout's current branch → 'main'). The pre-commit main-guard captures this so it blocks direct
+        // commits on whatever the repo's trunk is actually named, never a hardcoded 'main'. One value, one
+        // line; GET /api/settings exposes the same resolution (`.layout`).
+        const { mainBranch } = await import('@spexcode/spec-core');
+        console.log(mainBranch());
+    }
+    else if (sub === 'spec-governors') {
+        // Stable machine projection for spec-aware hooks: one real code: governor per row, with the live spec
+        // path the block reason can point at. Empty stdout means ungoverned (including related-only).
+        const file = process.argv[4];
+        if (!file) {
+            console.error('usage: spex internal spec-governors <path>');
+            process.exit(2);
+        }
+        const { specOwners, loadSpecsLite } = await import('@spexcode/spec-core');
+        const paths = new Map(loadSpecsLite().map((node) => [node.id, node.path]));
+        for (const owner of specOwners(file)) {
+            const path = paths.get(owner.id);
+            if (!path)
+                throw new Error(`governor '${owner.id}' has no live spec path`);
+            console.log(`${owner.id}\t${path}`);
+        }
+    }
+    else if (sub === 'shared-runtime-spawn') {
+        const [cwd, logFile, pidFile, receiptFile, command] = process.argv.slice(4, 9);
+        const args = process.argv.slice(9);
+        if (!cwd || !logFile || !pidFile || !receiptFile || !command) {
+            console.error('usage: spex internal shared-runtime-spawn <cwd> <log> <pid-file> <receipt-file> <command> [args...]');
+            process.exit(2);
+        }
+        const { spawnDetachedRuntime } = await import('./runtime-ownership.js');
+        const env = { ...process.env };
+        delete env.SPEXCODE_SESSION_ID;
+        const runtime = await spawnDetachedRuntime({ cwd, logFile, pidFile, receiptFile, command, args, env });
+        console.log(runtime.pid);
+    }
+    else if (sub === 'codex-generation-current' || sub === 'codex-generation-session') {
+        // Both launch spellings resolve ONE endpoint and print it as shell assignments. Starting a root is the same
+        // detached spawn either way — a session identity must never ride into the shared, project-scoped daemon.
+        const resume = sub === 'codex-generation-session';
+        const [root, ...rest] = process.argv.slice(4);
+        const [sessionId, threadId, sessionCommand] = rest;
+        const command = resume ? sessionCommand : rest[0];
+        if (!root || !command || (resume && (!sessionId || !threadId))) {
+            console.error(resume
+                ? 'usage: spex internal codex-generation-session <runtime-root> <session-id> <thread-id> <codex-command>'
+                : 'usage: spex internal codex-generation-current <runtime-root> <codex-command>');
+            process.exit(2);
+        }
+        const { ensureCodexCurrentGeneration, resolveCodexGenerationForResume } = await import('./codex-runtime-generations.js');
+        const { spawnDetachedRuntime } = await import('./runtime-ownership.js');
+        const { sessionIdentityEnvVars } = await import('./harness.js');
+        const env = { ...process.env };
+        for (const key of sessionIdentityEnvVars())
+            delete env[key];
+        const start = async (candidate) => {
+            await spawnDetachedRuntime({ cwd: root, logFile: candidate.logFile, pidFile: candidate.pidFile, receiptFile: candidate.receiptFile,
+                command, args: ['app-server', '--listen', `unix://${candidate.socketPath}`], env });
+        };
+        const endpoint = resume
+            ? await resolveCodexGenerationForResume(root, sessionId, threadId, start)
+            : await ensureCodexCurrentGeneration(root, start);
+        if (!endpoint) {
+            console.error(`no exact Codex generation binding for session ${sessionId} thread ${threadId}`);
+            process.exit(1);
+        }
+        const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+        console.log(`sock=${quote(endpoint.socketPath)}; pid=${quote(endpoint.pidFile)}; receipt=${quote(endpoint.receiptFile)}; log=${quote(endpoint.logFile)}; export SPEXCODE_CODEX_GENERATION=${quote(endpoint.id)}`);
+    }
+    else if (sub === 'codex-launch') {
+        // BACKEND-owned codex thread. On the shared per-project app-server: thread/start { cwd = this worktree }
+        // (codex loads that worktree's config/hooks/AGENTS.md), fire the launch prompt as the FIRST turn —
+        // materializing the rollout — then stage the id + exact-payload proof for the session lifecycle owner and
+        // print the thread id. The launch script then `resume`s it in the visible TUI.
+        const { codexStartThread, codexTurn, waitForCodexRollout, codexBinary, codexSupportsBypassHookTrust, codexLauncherThreadPolicy } = await import('./harness.js');
+        const { stageHarnessLaunchProof } = await import('./sessions.js');
+        const sock = process.argv[4], cwd = process.argv[5];
+        const prompt = process.argv.slice(6).join(' ');
+        if (!sock || !cwd) {
+            console.error('usage: spex internal codex-launch <sock> <cwd> [prompt...]');
+            process.exit(2);
+        }
+        // On the bypass-trust path (the codex install supports the flag → materialize skipped writeCodexTrust's hash),
+        // the thread the BACKEND owns must carry `bypass_hook_trust` in thread/start's config so the app-server fires
+        // the worktree's local hooks — mirror materialize's capability decision so the two stay in lockstep.
+        const launcherCmd = process.env.SPEXCODE_CODEX_CMD || 'codex';
+        const bypassHookTrust = codexSupportsBypassHookTrust(codexBinary(launcherCmd));
+        // The governed record id rides into the thread's own shell environment (shell_environment_policy.set), so
+        // every command this thread spawns knows which session it is — the codex equivalent of the launch-injected
+        // id claude gets. codex-launch is exactly where both ids are known ([[harness-adapter]]).
+        const ownId = process.env.SPEXCODE_SESSION_ID?.trim();
+        const r = await codexStartThread(sock, cwd, bypassHookTrust, ownId ? { SPEXCODE_SESSION_ID: ownId } : undefined, codexLauncherThreadPolicy(launcherCmd));
+        if (!r.ok) {
+            console.error(r.error);
+            process.exit(1);
+        }
+        if (prompt) {
+            const t = await codexTurn(sock, r.threadId, prompt, cwd);
+            if (!t.ok) {
+                console.error(t.error);
+                process.exit(1);
+            }
+            // The visible TUI resumes this thread from its ON-DISK rollout; a freshly-spawned app-server acks the turn
+            // but persists the rollout a few seconds LATE (verified live: the SAME thread's file lands at ~2-4s, not
+            // lost). WAIT for it to land BEFORE storing the id / printing it, else FAIL LOUD — never store a
+            // non-resumable harness_session_id (that permanently wedges every reopen). The 15s budget exceeds launch.sh's
+            // fast-fail threshold, so a real failure exits past it and the retry loop won't spray duplicate-prompt threads.
+            if (!await waitForCodexRollout(r.threadId, 20000)) {
+                console.error(`codex thread ${r.threadId} started but persisted no rollout within 20s — app-server not ready; not storing a non-resumable id`);
+                process.exit(1);
+            }
+        }
+        const sid = process.env.SPEXCODE_SESSION_ID;
+        if (sid)
+            stageHarnessLaunchProof(sid, r.threadId, prompt);
+        console.log(r.threadId);
+    }
+    else if (sub === 'opencode-capture') {
+        // opencode MINTS its own session id (no launch flag pins it), so the generated plugin's FIRST event calls
+        // this to store that id as harness_session_id on the governed record (SPEXCODE_SESSION_ID from the launch
+        // env, inherited by the opencode process → plugin). That is what lets reopen() resume the SAME
+        // conversation (`--session <id>`). A missing record/env is a clean no-op — a plugin loaded outside a
+        // governed launch has nothing to mark.
+        const { markHarnessSessionId } = await import('./sessions.js');
+        const ocid = process.argv[4];
+        if (!ocid) {
+            console.error('usage: spex internal opencode-capture <opencode-session-id>');
+            process.exit(2);
+        }
+        const sid = process.env.SPEXCODE_SESSION_ID;
+        console.log(sid && markHarnessSessionId(sid, ocid) ? `captured ${ocid}` : 'noop (no governed session record)');
+    }
+    else if (sub === 'claude-headless-run') {
+        const id = process.argv[4], runtimeDir = process.argv[5], claudeCmd = process.argv[6];
+        const divider = process.argv[7];
+        if (!id || !runtimeDir || !claudeCmd || divider !== '--') {
+            console.error('usage: spex internal claude-headless-run <session-id> <runtime-dir> <claude-cmd> -- [--session-id <id> <prompt> | --resume <id>]');
+            process.exit(2);
+        }
+        const { runClaudeHeadlessController } = await import('./claude-headless.js');
+        await runClaudeHeadlessController(id, runtimeDir, claudeCmd, process.argv.slice(8));
+    }
+    else if (sub === 'pi-headless-run') {
+        const id = process.argv[4], runtimeDir = process.argv[5], piCmd = process.argv[6];
+        const divider = process.argv[7];
+        if (!id || !runtimeDir || !piCmd || divider !== '--') {
+            console.error('usage: spex internal pi-headless-run <session-id> <runtime-dir> <pi-cmd> -- [--session-id <id> <prompt> | --session <id>]');
+            process.exit(2);
+        }
+        const { runPiHeadlessController } = await import('./pi-headless.js');
+        await runPiHeadlessController(id, runtimeDir, piCmd, process.argv.slice(8));
+    }
+    else if (sub === 'commit-surgery') {
+        // the pre-commit footprint anchor ([[commit-surgery]]): unconditional materialize + staged-index repair
+        // (strip our sentinel block from staged blobs, unstage HEAD-untracked generated artifacts). Called only
+        // by the planted pre-commit hook; repairs and proceeds, never rejects. Exit non-zero only on an internal
+        // error — the hook treats that as advisory (warn + continue), CI lint remains the real gate.
+        const { commitSurgery } = await import('./commit-surgery.js');
+        commitSurgery();
+    }
+    else if (sub === 'refresh-footprint') {
+        // the post-checkout / post-merge freshness anchor ([[commit-surgery]]): a quiet materialize after a git
+        // state transition (the only events that can move the materialize's inputs — .spec/.plugins arrive by commit,
+        // merge, or checkout). Best-effort and silent on success; hooks call it fire-and-forget.
+        const { materialize } = await import('./materialize.js');
+        try {
+            materialize();
+        }
+        catch (e) {
+            console.error(`spexcode: footprint refresh failed (${e.message})`);
+            process.exit(1);
+        }
+    }
+    else if (sub === 'codex-turn') {
+        // fire a follow-up turn on an OWNED thread over the per-project socket (the delivery channel, exposed for
+        // tests / scripts). steer-vs-start is chosen live from the thread read.
+        const { codexTurn } = await import('./harness.js');
+        const sock = process.argv[4], tid = process.argv[5], text = process.argv.slice(6).join(' ');
+        if (!sock || !tid || !text) {
+            console.error('usage: spex internal codex-turn <sock> <threadId> <text...>');
+            process.exit(2);
+        }
+        const r = await codexTurn(sock, tid, text);
+        if (r.ok) {
+            console.log('ok');
+        }
+        else {
+            console.error(r.error);
+            process.exit(1);
+        }
+    }
+    else if (sub === 'check-staged') {
+        // the pre-commit hook's eval backstop: a staged stray evidence blob or malformed eval.md rejects the
+        // commit. Logic lives in spec-eval; the hook shims here.
+        const { checkStaged } = await import('@spexcode/spec-eval/cli');
+        process.exit(checkStaged());
+    }
+    else if (sub === 'session-state') {
+        // a lifecycle hook authors the session's state: active|awaiting|parked|error|asking
+        // [--propose] [--note] [--session] — the machine face of the typeable done/park/ask declarations.
+        const { s, sess, mark, noRecord, noteEcho } = await stateKit();
+        const st = process.argv[4];
+        const ok = mark(() => s.markState(st, { proposal: flag('propose'), note: flag('note'), sessionId: sess }));
+        console.log(ok.ok ? `state -> ${st}${noteEcho(flag('note'))}` : ok.reason ?? noRecord());
+    }
+    else if (sub === 'session-fail') {
+        // StopFailure is one native source for the shared active-only turn-failure CAS. A declaration or explicit
+        // stop that landed first is authoritative, just as it is for Codex notifications and headless exits.
+        const { s, sess, mark } = await stateKit();
+        const failed = mark(() => s.markTurnFailure(sess, 'claude turn failed'));
+        console.log(failed.ok ? 'marked error' : failed.reason ?? 'noop (session is not live active)');
+    }
+    else if (sub === 'session-turn-fail') {
+        // Headless adapters report an ephemeral turn's non-zero exit through this one shared CAS. A declaration
+        // that landed before teardown wins, so a late child close can never erase an agent-authored state.
+        const sessionId = process.argv[4], harness = process.argv[5], exitCode = process.argv[6];
+        if (!sessionId || !harness || !exitCode) {
+            console.error('usage: spex internal session-turn-fail <session-id> <harness> <exit-code|signal>');
+            process.exit(2);
+        }
+        const { markHeadlessTurnFailure } = await import('./sessions.js');
+        console.log(markHeadlessTurnFailure(sessionId, harness, exitCode) ? `marked error (${harness} ${exitCode})` : 'noop (session is not live active)');
+    }
+    else if (sub === 'session-idle') {
+        // the Notification(idle_prompt) hook marks its session (--session from the payload) idle when claude waits
+        // at its prompt. INFERRED, so guarded active-only: it no-ops unless the current status is exactly `active`,
+        // never clobbering a deliberate awaiting/asking/parked/error declaration. Distinct from `session ask`
+        // (the agent deliberately asking the human) — idle is the undeclared stop the Stop gate missed.
+        const { s, sess, mark } = await stateKit();
+        const idled = mark(() => s.markIdle(sess));
+        console.log(idled.ok ? 'idle' : idled.reason ?? 'noop (no session record, or not active)');
+    }
+    else if (sub === 'commit-gate') {
+        // the Stop gate's deterministic commit check (from cwd = the worktree): exit 0 if the node branch is
+        // ready to declare done, else print the reason and exit 1. Takes the PROPOSAL being judged — `merge`
+        // additionally requires commits ahead of main, `nothing` only a clean tree (see mergeReadiness). Uses
+        // git() so the hook's exported GIT_DIR/GIT_INDEX_FILE don't misdirect repo discovery (see git.ts).
+        const { s } = await stateKit();
+        const kind = positionals(4)[0] === 'nothing' ? 'nothing' : 'merge';
+        const r = s.mergeReadiness(kind);
+        if (r.ready) {
+            console.log('ready');
+            process.exit(0);
+        }
+        console.log(r.reason);
+        process.exit(1);
+    }
+    else if (sub === 'hook-prompt') {
+        // The internal render seam shared by hook handlers and GuidanceCatalog. The hooks call it only on branches
+        // that already emit model-facing text; their hot no-op paths remain pure shell.
+        const name = positionals(4)[0];
+        if (!name) {
+            console.error('usage: spex internal hook-prompt <name> [--variant <name>] [--path <path>] [--owner <owners>] [--details <text>] [--cli <command>] [--propose <name>] [--reason <text>] [--count <n>] [--ids <ids>]');
+            process.exit(2);
+        }
+        const { HookPromptCatalog } = await import('./hook-prompts.js');
+        try {
+            console.log(new HookPromptCatalog().render(name, {
+                variant: flag('variant') ?? '',
+                path: flag('path') ?? '',
+                owner: flag('owner') ?? '',
+                details: flag('details') ?? '',
+                cli: flag('cli') ?? '',
+                proposal: flag('propose') ?? '',
+                reason: flag('reason') ?? '',
+                count: flag('count') ?? '',
+                ids: flag('ids') ?? '',
+            }));
+        }
+        catch (error) {
+            console.error(`spex internal hook-prompt: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(2);
+        }
+    }
+    else if (sub === 'nudge') {
+        // the post-merge hook prints the (toggle-aware) issue nudge for a merged node — never typed.
+        const { nudge } = await import('./localIssues.js');
+        const text = nudge(positionals(4)[0] || '');
+        if (text)
+            console.log(text);
+    }
+    else {
+        const { commandHelp } = await import('./help.js');
+        console.error(commandHelp('internal'));
+        process.exit(2);
+    }
+}
+else {
+    const { publicCommands } = await import('./help.js');
+    const suggestion = nearestPublicCommand(cmd, publicCommands());
+    console.error(`spex: unknown command '${cmd}'${suggestion ? ` — try: spex ${suggestion}` : ''} (try: spex help)`);
+    process.exit(2);
+}