@viloforge/vfkb 0.2.1

package/dist/cli.js

@@ -0,0 +1,635 @@
+#!/usr/bin/env node
+// vfkb thin CLI — the face the Claude Code hooks call (ADR-0015 Tier A/B).
+// `hook session-start` / `hook post-tool-use` carry the harness JSON contract.
+import { addEntry, captureToolCall, readAll, renderContext, renderContextBundle, renderContextMap, renderNaiveDump, renderResume, initContextSpine, supersede, deriveTrust, } from './engine.js';
+import { SessionState, effectiveSessionId } from './session.js';
+import { defaultProject } from './storage.js';
+import { runExport } from './export.js';
+import { promote, archive, mergeDuplicate, findLexicalDuplicates, promoteIfCorroborated, eligibleForPromotion, } from './curator.js';
+import { distill } from './distiller.js';
+import { recordSignal, tally } from './counters.js';
+import { queryExplained } from './read.js';
+import { isBrainWrite, GATING_REASON } from './gating.js';
+import { decideStop, gatherStopContext } from './stop-reminder.js';
+import { save } from './git.js';
+import { runSessionEnd } from './session-end.js';
+import { initProject, approvalNotice } from './init.js';
+import { runDoctor, renderDoctor, checkNpmCurrency } from './doctor.js';
+import { ENGINE_VERSION } from './version.js';
+import { fromMykb, fromAdr, fromMarkdown, resolveMykbArea } from './import.js';
+import { parseArgs, flagValue, flagList, flagInt, UsageError } from './args.js';
+import { ENTRY_TYPES, DECISION_STATUSES } from './types.js';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+// The package's OWN version, read from ITS OWN package.json at runtime — never
+// hardcoded (ADR-0057 step 1). Resolved relative to this module file so it works
+// from dist/cli.js inside an `npm i -g` install: bin -> dist/cli.js, package.json
+// is one level up from dist/, in both the tsc dev build and the packed tarball.
+function packageVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+    return pkg.version || '0.0.0';
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        if (process.stdin.isTTY)
+            return resolve('');
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (c) => (data += c));
+        process.stdin.on('end', () => resolve(data));
+        // Guard: if nothing arrives, don't hang forever.
+        setTimeout(() => resolve(data), 2000).unref?.();
+    });
+}
+// Positional flag lookup for the HOOK subcommands only — hooks stay fail-open
+// (never error a harness session over argv), so they bypass the strict parser.
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+function argsOf(sub, rest) {
+    return [sub, ...rest].filter((a) => a !== undefined);
+}
+function entryType(verb, raw) {
+    if (!raw || !ENTRY_TYPES.includes(raw)) {
+        throw new UsageError(`${verb}: unknown entry type '${raw ?? ''}' — expected ${ENTRY_TYPES.join('|')}`);
+    }
+    return raw;
+}
+async function main() {
+    try {
+        await dispatch();
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            process.stderr.write(`error: ${err.message}\n${USAGE}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+}
+const USAGE = 'usage: vfkb <add|list|search|query|map|context|context init|resume|resume-note|curate|distill|save|' +
+    'export|import|init|doctor|supersede|context-block|context-block-naive|--version|' +
+    'hook session-start|hook pre-tool-use|hook post-tool-use|hook stop|hook session-end>\n';
+async function dispatch() {
+    const [cmd, sub, ...rest] = process.argv.slice(2);
+    if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    // --version / -v / version: the package's own version, nothing else on stdout
+    // (ADR-0057 step 1 — needed by the install proof, RFC-030's update check, and
+    // every future bug report).
+    if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
+        process.stdout.write(`${packageVersion()}\n`);
+        return;
+    }
+    // --- add <type> <text> [--role] [--tag a,b] [--why …] [--status] [--prov-status] [--valid-until] ---
+    if (cmd === 'add') {
+        const p = parseArgs('add', argsOf(sub, rest), {
+            role: 'value',
+            tag: 'value',
+            why: 'value',
+            contradicts: 'value',
+            status: 'value',
+            'prov-status': 'value',
+            'valid-until': 'value',
+            zone: 'value',
+            constitutional: 'boolean',
+        });
+        const type = entryType('add', p.positionals[0]);
+        const textArg = p.positionals.slice(1).join(' ').trim();
+        if (!textArg)
+            throw new UsageError('add: missing entry text');
+        const role = flagValue(p, 'role') || 'executor';
+        try {
+            const e = addEntry(type, textArg, {
+                role,
+                why: flagValue(p, 'why'),
+                tags: flagList(p, 'tag') ?? [],
+                contradicts: flagList(p, 'contradicts'),
+                status: flagValue(p, 'status'),
+                provStatus: flagValue(p, 'prov-status'),
+                validUntil: flagValue(p, 'valid-until'),
+                zone: flagValue(p, 'zone'),
+                constitutional: p.flags.get('constitutional') === true,
+            });
+            process.stdout.write(`${e.id}\t[${e.type} ${deriveTrust(e.author.role)}]\t${e.text}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err.message}\n`);
+            process.exit(1);
+        }
+        return;
+    }
+    // export <agents-md|okf> [--out <path>] — ADR-0047 brain export projections:
+    // deterministic, generated-marked, never auto-committed publish artifacts.
+    if (cmd === 'export') {
+        const p = parseArgs('export', rest, { out: 'value' });
+        if (p.positionals.length > 0) {
+            throw new UsageError(`export: unexpected argument '${p.positionals[0]}'`);
+        }
+        try {
+            process.stdout.write(runExport(sub, { out: flagValue(p, 'out') }) + '\n');
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err.message}\n`);
+            process.exit(1);
+        }
+        return;
+    }
+    // init [project]: FR-1 (ADR-0030) — idempotently scaffold THIS repo (cwd) as a
+    // vfkb consumer (portable $VFKB_HOME wiring + .gitignore + empty brain + snippet).
+    if (cmd === 'init') {
+        const p = parseArgs('init', argsOf(sub, rest), {});
+        if (p.positionals.length > 1)
+            throw new UsageError('init: at most one [project] argument');
+        const root = process.cwd();
+        const project = p.positionals[0] || process.env.VFKB_PROJECT;
+        const changes = initProject(root, { project });
+        const resolved = project || root.split(/[/\\]/).filter(Boolean).pop() || 'project';
+        for (const c of changes)
+            process.stdout.write(`${c.action}\t${c.path}\n`);
+        process.stdout.write('\n' + approvalNotice(resolved) + '\n');
+        return;
+    }
+    // import: FR-3 (ADR-0030) — migrate existing knowledge into the brain (lossy,
+    // role=import). --from-mykb <area> | --from-adr [dir] | --from-markdown <file>.
+    if (cmd === 'import') {
+        const p = parseArgs('import', argsOf(sub, rest), {
+            'from-adr': 'optional-value',
+            'from-markdown': 'value',
+            'from-mykb': 'value',
+        });
+        if (p.positionals.length > 0) {
+            throw new UsageError(`import: unexpected argument '${p.positionals[0]}'`);
+        }
+        const results = [];
+        try {
+            if (p.flags.has('from-adr'))
+                results.push(...fromAdr(flagValue(p, 'from-adr') || 'docs/adr'));
+            const md = flagValue(p, 'from-markdown');
+            if (md)
+                results.push(...fromMarkdown(md));
+            const mykb = flagValue(p, 'from-mykb');
+            if (mykb)
+                results.push(...fromMykb(resolveMykbArea(mykb)));
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err.message}\n`);
+            process.exit(1);
+        }
+        if (results.length === 0) {
+            process.stderr.write('import: nothing imported — pass --from-mykb <area> | --from-adr [dir] | --from-markdown <file>\n');
+            process.exit(1);
+        }
+        for (const r of results)
+            process.stdout.write(`${r.id}\t${r.type}\t${r.text.split('\n')[0].slice(0, 80)}\n`);
+        process.stdout.write(`\nimported ${results.length} entr${results.length === 1 ? 'y' : 'ies'} (role=import, unverified)\n`);
+        return;
+    }
+    // doctor: FR-4 (ADR-0030) — diagnose brain↔engine compat + wiring health.
+    // --check-remote (ADR-0058/RFC-030): opt-in npm currency line; plain `doctor`
+    // stays fully offline (no fetch call, byte-identical output to pre-ADR-0058).
+    if (cmd === 'doctor') {
+        const pd = parseArgs('doctor', argsOf(sub, rest), { 'check-remote': 'boolean' });
+        if (pd.positionals.length > 0) {
+            throw new UsageError(`doctor: unexpected argument '${pd.positionals[0]}'`);
+        }
+        const brainDir = process.env.VFKB_DATA_DIR || process.env.VFKB_DIR || '.vfkb';
+        const report = runDoctor({ root: process.cwd(), brainDir, env: process.env });
+        if (pd.flags.get('check-remote') === true) {
+            const npm = await checkNpmCurrency({ brainDir, installedVersion: ENGINE_VERSION });
+            report.checks.push({ name: 'npm currency', status: npm.status, detail: npm.detail });
+            report.ok = !report.checks.some((c) => c.status === 'fail');
+        }
+        process.stdout.write(renderDoctor(report) + '\n');
+        if (!report.ok)
+            process.exit(1);
+        return;
+    }
+    // list [--type t] [--tag a,b] [--status s] [--limit N] — raw dump with structural
+    // filters (issue #95 fix (a)). Tag semantics mirror read.ts: entry carries ALL of
+    // them. --limit keeps the MOST RECENT N (append order tail).
+    if (cmd === 'list') {
+        const p = parseArgs('list', argsOf(sub, rest), {
+            type: 'value',
+            tag: 'value',
+            status: 'value',
+            limit: 'value',
+        });
+        if (p.positionals.length > 0) {
+            throw new UsageError(`list: unexpected argument '${p.positionals[0]}' (list takes only flags)`);
+        }
+        const type = flagValue(p, 'type');
+        if (type)
+            entryType('list --type', type);
+        const tags = flagList(p, 'tag');
+        const status = flagValue(p, 'status');
+        if (status && !DECISION_STATUSES.includes(status)) {
+            throw new UsageError(`list: unknown --status '${status}' — expected ${DECISION_STATUSES.join('|')}`);
+        }
+        const limit = flagInt(p, 'limit');
+        let entries = readAll();
+        if (type)
+            entries = entries.filter((e) => e.type === type);
+        if (tags)
+            entries = entries.filter((e) => tags.every((t) => e.tags.includes(t)));
+        if (status)
+            entries = entries.filter((e) => e.status === status);
+        if (limit !== undefined)
+            entries = entries.slice(-limit);
+        for (const e of entries) {
+            process.stdout.write(`${e.id}\t${e.type}\t${deriveTrust(e.author.role)}\t${e.provenance.status}\t${e.text}\n`);
+        }
+        return;
+    }
+    if (cmd === 'context-block') {
+        const p = parseArgs('context-block', argsOf(sub, rest), {});
+        if (p.positionals.length > 1)
+            throw new UsageError('context-block: at most one [project] argument');
+        process.stdout.write(renderContextBundle(p.positionals[0] || defaultProject()));
+        return;
+    }
+    if (cmd === 'map') {
+        const p = parseArgs('map', argsOf(sub, rest), {});
+        if (p.positionals.length > 0)
+            throw new UsageError(`map: unexpected argument '${p.positionals[0]}'`);
+        process.stdout.write(renderContextMap() + '\n');
+        return;
+    }
+    // context [project] | context init: the project context doc (D-ii / ADR-0025) — the
+    // assembled "agent's first read" (authored spine + derived Constitution/Map/decisions).
+    // `init` scaffolds the authored spine (<brain>/context.md) if absent.
+    if (cmd === 'context') {
+        const p = parseArgs('context', argsOf(sub, rest), {});
+        if (p.positionals.length > 1)
+            throw new UsageError('context: at most one [init|project] argument');
+        if (p.positionals[0] === 'init') {
+            const { created, path } = initContextSpine();
+            process.stdout.write(`${created ? 'created' : 'exists'}\t${path}\n`);
+            return;
+        }
+        process.stdout.write(renderContext(p.positionals[0] || defaultProject()));
+        return;
+    }
+    // resume [project]: the session-continuity render (ADR-0020) — prior-session
+    // digest (derived) + the live knowledge bundle. The MCP-pull-floor / CLI face.
+    if (cmd === 'resume') {
+        const p = parseArgs('resume', argsOf(sub, rest), {});
+        if (p.positionals.length > 1)
+            throw new UsageError('resume: at most one [project] argument');
+        process.stdout.write(renderResume(p.positionals[0] || defaultProject(), SessionState.load()) + '\n');
+        return;
+    }
+    // curate: ACE curator maintenance (ADR-0021) — deltas only, NEVER rewrites text.
+    //   curate dups                       list exact lexical duplicate pairs (proposal only)
+    //   curate promote <id>               incoming -> established
+    //   curate archive <id>               retire out of the injection set
+    //   curate merge <loserId> <winnerId> archive the loser, keep the winner
+    //   curate signal <id> <helpful|harmful>  record an append-only corroboration signal
+    //   curate promote-auto <id>          promote ONLY if corroborated (>=N signals)
+    if (cmd === 'curate') {
+        const p = parseArgs('curate', argsOf(sub, rest), {});
+        const [action, id1, id2] = p.positionals;
+        const need = (n, usage) => {
+            if (p.positionals.length - 1 !== n)
+                throw new UsageError(`usage: vfkb curate ${usage}`);
+        };
+        try {
+            if (action === 'dups') {
+                need(0, 'dups');
+                const dups = findLexicalDuplicates();
+                for (const d of dups)
+                    process.stdout.write(`DUP\tloser=${d.loser}\twinner=${d.winner}\n`);
+                if (dups.length === 0)
+                    process.stdout.write('no exact lexical duplicates\n');
+            }
+            else if (action === 'signal') {
+                need(2, 'signal <id> <helpful|harmful>');
+                if (id2 !== 'helpful' && id2 !== 'harmful') {
+                    process.stderr.write('usage: vfkb curate signal <id> <helpful|harmful>\n');
+                    process.exit(1);
+                }
+                recordSignal(id1, id2, 'operator');
+                const t = tally(id1);
+                process.stdout.write(`signal ${id2} -> ${id1} (helpful ${t.helpful} / harmful ${t.harmful} / net ${t.net}` +
+                    `${eligibleForPromotion(id1) ? ', promotable' : ''})\n`);
+            }
+            else if (action === 'promote-auto') {
+                need(1, 'promote-auto <id>');
+                const e = promoteIfCorroborated(id1);
+                process.stdout.write(`promoted (corroborated) ${e.id} -> ${e.zone}\n`);
+            }
+            else if (action === 'promote') {
+                need(1, 'promote <id>');
+                const e = promote(id1);
+                process.stdout.write(`promoted ${e.id} -> ${e.zone}\n`);
+            }
+            else if (action === 'archive') {
+                need(1, 'archive <id>');
+                const e = archive(id1);
+                process.stdout.write(`archived ${e.id}\n`);
+            }
+            else if (action === 'merge') {
+                need(2, 'merge <loser> <winner>');
+                mergeDuplicate(id1, id2);
+                process.stdout.write(`merged ${id1} -> ${id2} (loser archived)\n`);
+            }
+            else {
+                process.stderr.write('usage: vfkb curate <dups|promote <id>|promote-auto <id>|archive <id>|merge <loser> <winner>|signal <id> <helpful|harmful>>\n');
+                process.exit(1);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err.message}\n`);
+            process.exit(1);
+        }
+        return;
+    }
+    // distill: auto-distill write side (ADR-0021) — turn this session's captured failures
+    // into CANDIDATE gotchas in incoming/unverified (containment). Recurrence corroborates
+    // an existing candidate instead of duplicating. Deterministic; never touches the
+    // trusted set. With KB_SESSION_ID, restricts to the session's captured ids; else all.
+    if (cmd === 'distill') {
+        const pd = parseArgs('distill', argsOf(sub, rest), {});
+        if (pd.positionals.length > 0) {
+            throw new UsageError(`distill: unexpected argument '${pd.positionals[0]}'`);
+        }
+        const session = SessionState.load();
+        const ids = session.capturedIds;
+        const { created, corroborated } = distill(ids.length ? ids : undefined);
+        // Distilling IS session activity — advance the record so the just-written lessons
+        // fall inside this session's [startedAt, lastAt] window (M3: the next session's
+        // resume digest derives "learned this session" from that window). No-op when ephemeral.
+        session.save();
+        for (const e of created)
+            process.stdout.write(`CANDIDATE\t${e.id}\tincoming/unverified\t${e.text}\n`);
+        for (const id of corroborated)
+            process.stdout.write(`CORROBORATED\t${id}\t${tally(id).net} net\n`);
+        if (created.length === 0 && corroborated.length === 0) {
+            process.stdout.write('no distillable failure signals\n');
+        }
+        return;
+    }
+    // resume-note <text...>: attach an ASSERTED operator intent ("next: …") to the
+    // current session's record. Persists only with KB_SESSION_ID (else ephemeral).
+    if (cmd === 'resume-note') {
+        const p = parseArgs('resume-note', argsOf(sub, rest), {});
+        const session = SessionState.load();
+        const note = p.positionals.join(' ').trim();
+        if (!note) {
+            process.stderr.write('usage: vfkb resume-note <text>\n');
+            process.exit(1);
+        }
+        session.setNote(note);
+        session.save();
+        process.stdout.write(session.sessionId
+            ? `noted for session ${session.sessionId}: ${note}\n`
+            : `note set (ephemeral — set KB_SESSION_ID to persist): ${note}\n`);
+        return;
+    }
+    // context-block-naive: mykb-v1-style flat unfiltered dump (L4 contrast baseline).
+    // --limit N truncates load-order (oldest-first) to N entries (reproduces the
+    // budget-drops-newest incident).
+    if (cmd === 'context-block-naive') {
+        const p = parseArgs('context-block-naive', argsOf(sub, rest), { limit: 'value' });
+        if (p.positionals.length > 1)
+            throw new UsageError('context-block-naive: at most one [project] argument');
+        const lim = flagInt(p, 'limit');
+        process.stdout.write(renderNaiveDump(p.positionals[0] || defaultProject(), undefined, lim));
+        return;
+    }
+    // supersede <oldId> <text...> [--role r] [--why w]
+    if (cmd === 'supersede') {
+        if (!sub || sub.startsWith('--')) {
+            throw new UsageError('usage: vfkb supersede <oldId> <text…> [--role r] [--why w]');
+        }
+        const p = parseArgs('supersede', rest, { role: 'value', why: 'value' });
+        const newText = p.positionals.join(' ').trim();
+        if (!newText)
+            throw new UsageError('supersede: missing new text');
+        try {
+            const e = supersede(sub, newText, {
+                role: flagValue(p, 'role') || 'human',
+                why: flagValue(p, 'why'),
+            });
+            process.stdout.write(`${e.id}\tsupersedes ${sub}\t${e.text}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err.message}\n`);
+            process.exit(1);
+        }
+        return;
+    }
+    // search/query: vfkb search <text> [--type t] [--tag a,b] [--zone z] [--status s]
+    //               [--role r] [--verified] [--limit N] [--stale] [--superseded]
+    if (cmd === 'search' || cmd === 'query') {
+        const p = parseArgs(cmd, argsOf(sub, rest), {
+            type: 'value',
+            tag: 'value',
+            zone: 'value',
+            status: 'value',
+            role: 'value',
+            limit: 'value',
+            verified: 'boolean',
+            stale: 'boolean',
+            superseded: 'boolean',
+        });
+        const text = p.positionals.join(' ');
+        const { results, diagnosis } = queryExplained({
+            text: text || undefined,
+            type: flagValue(p, 'type'),
+            zone: flagValue(p, 'zone'),
+            status: flagValue(p, 'status'),
+            tags: flagList(p, 'tag'),
+            authorRole: flagValue(p, 'role'),
+            verifiedOnly: p.flags.get('verified') === true,
+            limit: flagInt(p, 'limit'),
+            includeStale: p.flags.get('stale') === true,
+            includeSuperseded: p.flags.get('superseded') === true,
+        });
+        for (const e of results) {
+            const contra = e.refs?.contradicts?.length ? `\t⚔ contradicts ${e.refs.contradicts.join(',')}` : '';
+            process.stdout.write(`${e.id}\t${e.type}\t${deriveTrust(e.author.role)}\t${e.text}${contra}\n`);
+        }
+        // RFC-002: an empty result is reported with its cause, not silence — so the
+        // human/agent reading the CLI knows "no recorded entry" vs "all matches stale".
+        if (results.length === 0 && diagnosis) {
+            const extra = diagnosis.reason === 'all_filtered'
+                ? ` (${diagnosis.candidates} filtered: ${Object.entries(diagnosis.filteredOut ?? {})
+                    .map(([k, v]) => `${v} ${k}`)
+                    .join(', ')})`
+                : diagnosis.reason === 'no_match' && diagnosis.belowFloor
+                    ? ` (closest below floor, low confidence: ${diagnosis.belowFloor.entry.text})`
+                    : '';
+            process.stdout.write(`NO-MATCH\t${diagnosis.reason}\tno recorded entry found${extra}\n`);
+        }
+        return;
+    }
+    // Hook subcommands are exempt from strict flag parsing BY DESIGN (issue #95):
+    // the harness contract is fail-open — a hook must never error a session over
+    // an unrecognized argv, so unknown flags here are ignored, not rejected.
+    if (cmd === 'hook') {
+        if (sub === 'session-start') {
+            const raw = await readStdin();
+            let payloadId;
+            try {
+                const p = JSON.parse(raw || '{}');
+                if (typeof p.session_id === 'string')
+                    payloadId = p.session_id;
+            }
+            catch {
+                /* malformed → no harness id; env override may still apply */
+            }
+            const project = defaultProject();
+            // --naive = the mykb-v1-style flat dump (L4 contrast baseline only); --limit N truncates it.
+            const lim = flag(rest, 'limit');
+            // The Tier-A payload is the RESUME render (ADR-0020): prior-session digest +
+            // the live knowledge bundle, both derived. Persist this session's record so the
+            // NEXT session can resume from it (append-only). ADR-0039: the id comes from the
+            // hook's own stdin (KB_SESSION_ID is an optional override) — no harness wiring needed.
+            const session = SessionState.load(effectiveSessionId(payloadId));
+            const additionalContext = rest.includes('--naive')
+                ? renderNaiveDump(project, undefined, lim ? Number(lim) : undefined)
+                : renderResume(project, session);
+            session.save();
+            process.stdout.write(JSON.stringify({
+                hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext },
+            }));
+            return;
+        }
+        if (sub === 'post-tool-use') {
+            const raw = await readStdin();
+            try {
+                const payload = JSON.parse(raw || '{}');
+                const sessionId = effectiveSessionId(typeof payload.session_id === 'string' ? payload.session_id : undefined);
+                const captured = captureToolCall({
+                    tool_name: payload.tool_name,
+                    tool_input: payload.tool_input,
+                    // Claude Code's PostToolUse payload carries the result under `tool_response`
+                    // ({stdout,stderr,…}), NOT `tool_result` (verified 2026-06-27). Without this
+                    // fallback the result was dropped → every live capture classified `ok` → no
+                    // capture:error → the distiller never fired on a real claude failure (D-iv,
+                    // the claude analog of the pi tool_call-has-no-result gap). The host-side
+                    // synthetic seam feeds `tool_result`, so it keeps precedence.
+                    tool_result: payload.tool_result ?? payload.tool_response,
+                    call_id: payload.call_id || payload.tool_use_id,
+                    session_id: sessionId,
+                });
+                // record the captured id into the session log (Tier-B → continuity signal).
+                if (captured) {
+                    const session = SessionState.load(sessionId);
+                    session.recordCaptured(captured.id);
+                    session.save();
+                }
+            }
+            catch {
+                /* malformed payload: capture nothing, never block the tool (exit 0) */
+            }
+            process.stdout.write('{}');
+            return;
+        }
+        // Stop — conditional end-of-turn decision-capture reminder (RFC-008 / ADR-0027).
+        // Verified contract (CLI v2.1.195): emit decision:block + additionalContext to
+        // continue the turn; `stop_hook_active` is the native loop guard (never block twice).
+        if (sub === 'stop') {
+            const raw = await readStdin();
+            let input = {};
+            try {
+                input = JSON.parse(raw || '{}');
+            }
+            catch {
+                /* malformed → fail-open: allow the stop, never wedge the turn */
+            }
+            // Native loop guard first (cheap, git-free): our own re-entry → allow the stop.
+            if (input.stop_hook_active) {
+                process.stdout.write('{}');
+                return;
+            }
+            // ADR-0039: a real (non-re-entry) Stop = one turn ended — accumulate it on the
+            // session record so continuity signals survive across `--resume` turns.
+            try {
+                const session = SessionState.load(effectiveSessionId(typeof input.session_id === 'string' ? input.session_id : undefined));
+                session.bumpTurn();
+                session.save();
+            }
+            catch {
+                /* session bookkeeping must never wedge the turn */
+            }
+            const d = decideStop({ stop_hook_active: false }, gatherStopContext());
+            process.stdout.write(d.block
+                ? JSON.stringify({
+                    hookSpecificOutput: {
+                        hookEventName: 'Stop',
+                        decision: 'block',
+                        additionalContext: d.reminder,
+                    },
+                })
+                : '{}');
+            return;
+        }
+        // SessionEnd — GAP 2 (RFC-011 / ADR-0033): auto-commit the brain so `/exit` is
+        // safe by default. Cannot block exit / inject context (verified contract, gotcha
+        // f0e913b97824) → fire-and-forget; only a `systemMessage` (the main-branch warning)
+        // is surfaced. Fail-open: never throw, always exit 0.
+        if (sub === 'session-end') {
+            const raw = await readStdin();
+            let cwd;
+            let sessionId;
+            try {
+                const payload = JSON.parse(raw || '{}');
+                if (typeof payload.cwd === 'string')
+                    cwd = payload.cwd;
+                if (typeof payload.session_id === 'string')
+                    sessionId = payload.session_id;
+            }
+            catch {
+                /* malformed → fall back to process.cwd()/env */
+            }
+            let systemMessage;
+            try {
+                const r = runSessionEnd({ cwd, sessionId: effectiveSessionId(sessionId) });
+                systemMessage = r.systemMessage;
+            }
+            catch {
+                /* fail-open: never block exit */
+            }
+            process.stdout.write(systemMessage ? JSON.stringify({ systemMessage }) : '{}');
+            return;
+        }
+        // PreToolUse gating — deny direct writes to the brain (force engine writes).
+        if (sub === 'pre-tool-use') {
+            const raw = await readStdin();
+            try {
+                const payload = JSON.parse(raw || '{}');
+                if (isBrainWrite(payload.tool_name, payload.tool_input)) {
+                    process.stdout.write(JSON.stringify({
+                        hookSpecificOutput: {
+                            hookEventName: 'PreToolUse',
+                            permissionDecision: 'deny',
+                            permissionDecisionReason: GATING_REASON,
+                        },
+                    }));
+                    return;
+                }
+            }
+            catch {
+                /* malformed → allow (fail-open: never wedge the harness) */
+            }
+            process.stdout.write('{}');
+            return;
+        }
+    }
+    if (cmd === 'save') {
+        const p = parseArgs('save', argsOf(sub, rest), {});
+        const r = save(p.positionals.join(' ').trim() || undefined);
+        process.stdout.write((r.committed ? 'committed: ' : 'no-op: ') + r.message + '\n');
+        return;
+    }
+    process.stderr.write(USAGE);
+    process.exit(1);
+}
+main();