@viloforge/vfkb 0.2.1

package/dist/lock.js

@@ -0,0 +1,158 @@
+// ADR-0040 (v2): a vfkb-native advisory lock for the read-decide-append critical
+// section. Held INTERNALLY by the engine around operations that read state before
+// writing (supersede, transition, fluid edits, provenance re-stamps) — never something
+// callers must remember to acquire. Scoped to one VFKB_DATA_DIR.
+//
+// Mechanism (ADR-0013: no native dep, so no real flock): a plain lockfile taken with
+// O_EXCL exclusive-create at <brain>/.lock, carrying {pid, at, session_id} so
+// contention is observable (ADR-0039's registry tells you who). Staleness: a holder
+// whose pid is dead, or older than STALE_MS, is broken (a crashed process must not
+// wedge every future engine op). Acquisition is a bounded retry loop; on timeout the
+// engine proceeds WITHOUT the lock (fail-open: liveness over strictness — the same
+// posture as the hooks; the pathological case is a >5s hold, which staleness already
+// bounds at 10s).
+//
+// Re-entrancy: node is single-threaded, so a process-local depth counter suffices —
+// should engine ops ever compose in-process, the inner op runs under the outer
+// acquisition instead of deadlocking on its own lockfile.
+//
+// Release is OWNER-CHECKED (review gate F1): the holder file carries a unique token;
+// release unlinks only if the file still holds OUR token. Without this, a holder whose
+// critical section outlives STALE_MS would unlink the NEXT holder's fresh lock and
+// admit an unbounded chain of overlapping writers.
+import { openSync, closeSync, writeSync, readFileSync, unlinkSync, mkdirSync, statSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { brainDir } from './storage.js';
+const STALE_MS = 10_000;
+const ACQUIRE_TIMEOUT_MS = 5_000;
+const RETRY_MS = 25;
+let depth = 0; // process-local re-entrancy (single-threaded)
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM = the process EXISTS but belongs to another user (shared brain dirs) —
+        // that is an alive holder, not a dead one (review gate F2).
+        return err.code === 'EPERM';
+    }
+}
+// Test-only injectable pause (ADR-0040 DoD): called by the engine INSIDE the critical
+// section, between the read and the append, so a test can deterministically force two
+// processes' read-decide-append sequences to overlap in time. No-op unless the env
+// knob is set; never set it outside a test.
+export function testHoldForRace() {
+    const ms = Number(process.env.VFKB_TEST_LOCK_HOLD_MS || 0);
+    if (ms > 0)
+        sleepSync(ms);
+}
+export function withBrainLock(fn) {
+    // Escape hatch for the DoD's must-fail arm ONLY (proves the race is real).
+    if (process.env.VFKB_LOCK_DISABLED === '1')
+        return fn();
+    if (depth > 0) {
+        depth++;
+        try {
+            return fn();
+        }
+        finally {
+            depth--;
+        }
+    }
+    const lockPath = join(brainDir(), '.lock');
+    const started = Date.now();
+    let contended = false;
+    // Unique per-acquisition token: release only unlinks a lock that is still OURS.
+    const ourContent = JSON.stringify({
+        pid: process.pid,
+        at: new Date().toISOString(),
+        session_id: process.env.KB_SESSION_ID,
+        token: randomBytes(6).toString('hex'),
+    });
+    for (;;) {
+        try {
+            mkdirSync(brainDir(), { recursive: true });
+            const fd = openSync(lockPath, 'wx'); // O_EXCL: atomic exclusive create
+            writeSync(fd, ourContent);
+            closeSync(fd);
+            break; // acquired
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            // Judge the holder. CAREFUL: a lockfile can legitimately be caught in the
+            // microsecond window between its exclusive-create and its content write —
+            // unparseable content is NOT evidence of staleness. Fall back to the file's
+            // mtime: a fresh-but-empty lock is waited on; only a demonstrably OLD or
+            // dead-holder lock is broken.
+            let holder;
+            let raw = '';
+            try {
+                raw = readFileSync(lockPath, 'utf8');
+                holder = JSON.parse(raw);
+            }
+            catch {
+                holder = undefined;
+            }
+            let age;
+            if (holder?.at) {
+                age = Date.now() - Date.parse(holder.at);
+            }
+            else {
+                try {
+                    age = Date.now() - statSync(lockPath).mtimeMs;
+                }
+                catch {
+                    continue; // lock vanished between EEXIST and stat → retry acquisition now
+                }
+            }
+            const dead = typeof holder?.pid === 'number' && !pidAlive(holder.pid);
+            if (dead || age > STALE_MS) {
+                // Confirm before breaking: re-read; only unlink if the content is still the
+                // same lock we judged stale (shrinks the window where a waiter could break a
+                // JUST-acquired fresh lock; not perfectly atomic without flock — accepted,
+                // documented ADR-0013 constraint).
+                try {
+                    if (readFileSync(lockPath, 'utf8') !== raw)
+                        continue;
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    /* raced with the holder's own release — loop retries either way */
+                }
+                process.stderr.write(`vfkb: broke a stale brain lock (pid ${holder?.pid ?? '?'}${holder?.session_id ? `, session ${holder.session_id}` : ''})\n`);
+                continue;
+            }
+            if (Date.now() - started > ACQUIRE_TIMEOUT_MS) {
+                process.stderr.write(`vfkb: brain lock busy >${ACQUIRE_TIMEOUT_MS}ms (pid ${holder?.pid ?? '?'}${holder?.session_id ? `, session ${holder.session_id}` : ''}) — proceeding without the lock (fail-open)\n`);
+                return fn();
+            }
+            contended = true;
+            sleepSync(RETRY_MS);
+        }
+    }
+    if (contended) {
+        process.stderr.write('vfkb: brain lock acquired after contention\n');
+    }
+    depth = 1;
+    try {
+        return fn();
+    }
+    finally {
+        depth = 0;
+        try {
+            // Owner-checked release (F1): if a waiter judged us stale and took over, the
+            // file now carries THEIR token — leave it alone rather than freeing their lock.
+            if (readFileSync(lockPath, 'utf8') === ourContent)
+                unlinkSync(lockPath);
+        }
+        catch {
+            /* already broken as stale by a waiter — nothing to release */
+        }
+    }
+}

package/dist/manifest.js

@@ -0,0 +1,38 @@
+// FR-4 (ADR-0030) — the brain↔engine version stamp: .vfkb/manifest.json.
+//
+// A small COMMITTED file (ADR-0030 locks it as committed, distinct from the
+// derived/gitignored index-meta.json) recording which engine a brain targets, so a
+// consumer can't silently bind to a stale/incompatible engine. Engine-written only
+// (the write-gate applies); never hand-edited.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { SCHEMA_VERSION, ENGINE_VERSION, ENGINE_COMMIT } from './version.js';
+export function manifestPath(brainDir) {
+    return join(brainDir, 'manifest.json');
+}
+export function currentManifest() {
+    return { schema_version: SCHEMA_VERSION, engine_version: ENGINE_VERSION, engine_commit: ENGINE_COMMIT };
+}
+export function readManifest(brainDir) {
+    const p = manifestPath(brainDir);
+    if (!existsSync(p))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+// Write the stamp if absent or stale. Returns 'created' | 'updated' | 'skipped'.
+export function writeManifest(brainDir) {
+    const p = manifestPath(brainDir);
+    const existed = existsSync(p);
+    const cur = readManifest(brainDir);
+    const next = currentManifest();
+    if (cur && JSON.stringify(cur) === JSON.stringify(next))
+        return 'skipped';
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(next, null, 2) + '\n');
+    return existed ? 'updated' : 'created';
+}

package/dist/mcp-server.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// vfkb MCP server — the cross-harness PULL baseline (D5a / ADR-0015). A tight set
+// of scoped tools over the same engine the auto-layer faces use. Uses the OFFICIAL
+// @modelcontextprotocol/sdk (verified contract — not a hand-rolled JSON-RPC). The
+// engine stays zero-dep; this face opts into the SDK.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { addEntry, deriveTrust, readAll, renderContext, renderContextMap, renderResume, supersede, transitionDecision, } from './engine.js';
+import { query, queryExplained } from './read.js';
+import { brainDir, defaultProject } from './storage.js';
+import { ENGINE_VERSION } from './version.js';
+// Default page size for the read tools. An MCP tool result has a hard token
+// budget; an unbounded `query()` returns the whole candidate pool (up to ~200
+// full entries → ~130k chars), which overflows and errors the call. Cap the
+// pull-face here so a broad query degrades to "freshest relevant top-N", never
+// a hard error. Callers can still ask for a larger explicit `limit`.
+const SEARCH_DEFAULT_LIMIT = 25;
+const ENTRY_TYPE = z.enum(['fact', 'decision', 'gotcha', 'pattern', 'link']);
+const ZONE = z.enum(['incoming', 'established', 'archive']);
+const STATUS = z.enum(['proposed', 'accepted', 'deprecated', 'superseded']);
+const ROLE = z.enum(['architect', 'pm', 'executor', 'judge', 'human', 'init', 'import']);
+function line(e) {
+    const adr = typeof e.adr_no === 'number' ? ` ADR-${String(e.adr_no).padStart(4, '0')}` : '';
+    const st = e.status ? `/${e.status}` : '';
+    // ADR-0042 §3: a structural contradiction reference is surfaced on every read line.
+    const contra = e.refs?.contradicts?.length ? ` ⚔ contradicts ${e.refs.contradicts.join(',')}` : '';
+    return `${e.id} [${e.type} ${deriveTrust(e.author.role)}/${e.provenance.status}${st}${adr}]${contra} ${e.text}`;
+}
+function text(s) {
+    return { content: [{ type: 'text', text: s }] };
+}
+// RFC-002: render an empty search as a cause-distinguished, honest no-match. The
+// engine returns structured truth (the diagnosis); this face turns it into words +
+// the agent contract — an empty result is NOT a licence to answer from model priors.
+function renderNoMatch(d, q) {
+    const subject = q ? `“${q}”` : 'that filter';
+    const contract = 'No recorded entry was found — do NOT present model-prior knowledge as if it were recorded. Say none was found, or rephrase/broaden.';
+    switch (d.reason) {
+        case 'empty_topic':
+            return `(no matches) — nothing recorded matches ${subject}. ${contract}`;
+        case 'no_match': {
+            const b = d.belowFloor;
+            const hint = b
+                ? ` Closest below the relevance floor (LOW CONFIDENCE — matched ${b.matched}/${b.queryTerms} terms, NOT a confirmed answer): ${line(b.entry)}`
+                : '';
+            return `(no matches) — recorded entries share wording with ${subject} but none cleared the relevance floor.${hint} ${contract}`;
+        }
+        case 'all_filtered': {
+            const parts = Object.entries(d.filteredOut ?? {})
+                .map(([k, v]) => `${v} ${k}`)
+                .join(', ');
+            const stale = (d.filteredOut?.stale ?? 0) + (d.filteredOut?.superseded ?? 0);
+            const staleNote = stale
+                ? ` ${stale} match(es) exist but are STALE/SUPERSEDED — the recorded knowledge here is out of date; pass include_stale/include_superseded to inspect it.`
+                : '';
+            return `(no matches) — ${d.candidates} candidate(s) matched ${subject} but were filtered out (${parts}).${staleNote} ${contract}`;
+        }
+    }
+}
+function tags(csv) {
+    return csv ? csv.split(',').map((t) => t.trim()).filter(Boolean) : undefined;
+}
+// In the fleet, who wrote an entry must be stamped by the HARNESS, not self-reported
+// by the model (VERIFIED = observed, not asserted — applied to provenance). When the
+// pod sets VFKB_ROLE, it is authoritative and overrides any model-supplied `role`.
+// Outside the fleet (no env), the tool param / per-tool default applies as before.
+function envRole() {
+    const p = ROLE.safeParse(process.env.VFKB_ROLE);
+    return p.success ? p.data : undefined;
+}
+// Render defaults resolve the real project name via the shared derivation
+// (VFKB_PROJECT, else the brain dir's owning repo, else $CLAUDE_PROJECT_DIR/cwd)
+// — the engine-wide successor of this server's Track 9 Q0 local fix.
+const projectName = defaultProject;
+const server = new McpServer({ name: 'vfkb', version: ENGINE_VERSION });
+server.registerTool('kb_search', {
+    description: 'Search and filter project knowledge. Returns the freshest relevant entries (stale/superseded excluded by default). ' +
+        'Pass verified=true to get ONLY human-verified knowledge (excludes unverified agent-authored entries) — the trust filter. ' +
+        'An empty result is reported as an honest, cause-distinguished no-match (nothing recorded / below relevance floor / all matches filtered as stale) — it means no recorded entry was found, NOT a licence to answer from model priors as if recorded.',
+    inputSchema: {
+        text: z.string().optional().describe('free-text query'),
+        type: ENTRY_TYPE.optional(),
+        zone: ZONE.optional(),
+        status: STATUS.optional().describe('effective decision status'),
+        tags: z.string().optional().describe('comma-separated; entry must have ALL'),
+        author_role: ROLE.optional(),
+        verified: z
+            .boolean()
+            .optional()
+            .describe('true → return ONLY verified knowledge (provenance verified); excludes unverified/agent-authored entries'),
+        limit: z.number().int().positive().optional(),
+        include_stale: z.boolean().optional(),
+        include_superseded: z.boolean().optional(),
+    },
+}, async (a) => {
+    const { results, diagnosis } = queryExplained({
+        text: a.text,
+        type: a.type,
+        zone: a.zone,
+        status: a.status,
+        tags: tags(a.tags),
+        authorRole: a.author_role,
+        verifiedOnly: a.verified,
+        limit: a.limit ?? SEARCH_DEFAULT_LIMIT,
+        includeStale: a.include_stale,
+        includeSuperseded: a.include_superseded,
+    });
+    return text(results.length ? results.map(line).join('\n') : renderNoMatch(diagnosis, a.text));
+});
+server.registerTool('kb_list', {
+    description: 'List entries by structural filter (no text search).',
+    inputSchema: {
+        type: ENTRY_TYPE.optional(),
+        zone: ZONE.optional(),
+        limit: z.number().int().positive().optional(),
+    },
+}, async (a) => {
+    const r = query({ type: a.type, zone: a.zone, limit: a.limit ?? SEARCH_DEFAULT_LIMIT });
+    return text(r.length ? r.map(line).join('\n') : '(empty)');
+});
+server.registerTool('kb_get', {
+    description: 'Fetch a single entry by id (full JSON).',
+    inputSchema: { id: z.string() },
+}, async ({ id }) => {
+    const e = readAll().find((x) => x.id === id);
+    return text(e ? JSON.stringify(e, null, 2) : `no such entry: ${id}`);
+});
+server.registerTool('kb_map', {
+    description: 'The derived Context Map — what knowledge exists and how to navigate it.',
+    inputSchema: {},
+}, async () => text(renderContextMap()));
+server.registerTool('kb_context', {
+    description: "The project context document — the agent's first read. Orients you to the project: " +
+        'its job-to-be-done, architecture, tech profile, conventions, the load-bearing decisions, ' +
+        'and links. Read this BEFORE acting on an unfamiliar project. Assembled from the authored ' +
+        'context spine + the live Constitution/Map/decisions (always current).',
+    inputSchema: {},
+}, async () => text(renderContext(projectName())));
+server.registerTool('kb_add', {
+    description: 'Add an entry. Fluid types (fact/gotcha/pattern/link) are editable; decisions are immutable (supersede to change). New decisions default to status=proposed (an RFC).',
+    inputSchema: {
+        type: ENTRY_TYPE,
+        text: z.string(),
+        why: z.string().optional().describe('rationale; stored structurally AND folded into the text as a "Why: …" line (esp. for decisions)'),
+        tags: z.string().optional().describe('comma-separated'),
+        path: z
+            .string()
+            .optional()
+            .describe('link target (path or URL) for type=link — folded into the text as "<text> → <path>" ' +
+            '(link entries have no structural target field); rejected for other types'),
+        contradicts: z.string().optional().describe('comma-separated ids of entries this one contradicts (structural reference, ADR-0042)'),
+        role: ROLE.optional().describe('author role; defaults to executor (agent)'),
+        status: STATUS.optional().describe('decision family only'),
+        constitutional: z.boolean().optional().describe('decision family only (ADR-0008)'),
+    },
+}, async (a) => {
+    if (a.path !== undefined && a.type !== 'link') {
+        throw new Error(`kb_add: 'path' is only valid with type=link (got type=${a.type})`);
+    }
+    if (a.path !== undefined && !a.path.trim()) {
+        // An empty target would silently record a link pointing nowhere — the
+        // exact instance-5 failure this parameter exists to prevent.
+        throw new Error("kb_add: 'path' must be a non-empty path or URL");
+    }
+    const body = a.path !== undefined ? `${a.text.trim()} → ${a.path.trim()}` : a.text;
+    const e = addEntry(a.type, body, {
+        role: envRole() ?? a.role ?? 'executor',
+        why: a.why,
+        tags: tags(a.tags),
+        contradicts: tags(a.contradicts),
+        status: a.status,
+        constitutional: a.constitutional,
+    });
+    return text(`added ${line(e)}`);
+});
+server.registerTool('kb_supersede', {
+    description: 'Supersede a decision with a new one (additive edge; the old is never edited and stops being injected).',
+    inputSchema: {
+        old_id: z.string(),
+        text: z.string(),
+        why: z
+            .string()
+            .optional()
+            .describe('rationale for the new decision; stored structurally AND folded into its text as a "Why: …" line'),
+        role: ROLE.optional(),
+    },
+}, async (a) => {
+    const e = supersede(a.old_id, a.text, { role: envRole() ?? a.role ?? 'architect', why: a.why });
+    return text(`superseded ${a.old_id} -> ${line(e)}`);
+});
+server.registerTool('kb_transition', {
+    description: 'Transition a decision through its lifecycle (proposed -> accepted -> deprecated). Content is preserved; `superseded` is set by kb_supersede, not here.',
+    inputSchema: { id: z.string(), status: z.enum(['proposed', 'accepted', 'deprecated']) },
+}, async (a) => {
+    const e = transitionDecision(a.id, a.status);
+    return text(`transitioned ${line(e)}`);
+});
+server.registerTool('kb_resume', {
+    description: 'Session-continuity resume (ADR-0020): the prior session’s derived digest (what was added/superseded/injected/captured — recomputed from the brain, so never stale) + the live knowledge bundle. Pull this to see where the last session left off.',
+    inputSchema: {},
+}, async () => text(renderResume(projectName())));
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the protocol channel — never write to it. Log to stderr.
+    // brainDir() resolves VFKB_DATA_DIR (canonical) → VFKB_DIR (deprecated alias) → ~/.vfkb.
+    process.stderr.write(`vfkb MCP server up (v${ENGINE_VERSION}, brain: ${brainDir()})\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`vfkb MCP fatal: ${err}\n`);
+    process.exit(1);
+});

package/dist/pi-extension.js

@@ -0,0 +1,117 @@
+// vfkb Pi face — the in-process TS extension (ADR-0015 cross-harness auto-layer).
+// One engine, two faces: this is the Pi side; src/cli.ts + hooks are the Claude
+// Code side. Same engine.ts underneath (LSP — every tier calls the same code).
+//
+// Contracts copied verbatim from the verified mykb spike (src/extension/*):
+//   before_agent_start -> { systemPrompt } : APPEND the bundle (Tier A inject)
+//   context            -> { messages:[{role:'custom',...}] } : per-turn (Tier C, Pi-only)
+//   tool_call          -> { toolName, input } : gate brain writes (pre-execution block)
+//   tool_execution_end -> { toolName, result, isError } : capture WITH result (Tier B, D-iv)
+//   session_shutdown   -> git save
+import { mkdirSync } from 'node:fs';
+import { brainDir, captureToolCall, currentInjectableIds, renderContextDelta, renderResume, } from './engine.js';
+import { SessionState } from './session.js';
+import { defaultProject } from './storage.js';
+import { isBrainWrite, GATING_REASON } from './gating.js';
+import { save } from './git.js';
+function project() {
+    return defaultProject();
+}
+// Reduce a pi tool result (AgentToolResult-ish: { content:[{text}], details } | string |
+// object) to a bounded text summary for capture. classifyToolOutcome caps length; here we
+// just extract the most useful string.
+function resultText(r) {
+    if (r == null)
+        return '';
+    if (typeof r === 'string')
+        return r;
+    if (typeof r === 'object') {
+        const o = r;
+        if (Array.isArray(o.content)) {
+            return o.content
+                .map((c) => (c && typeof c.text === 'string' ? c.text : ''))
+                .join(' ')
+                .trim();
+        }
+        return JSON.stringify(o);
+    }
+    return String(r);
+}
+export default function (pi) {
+    mkdirSync(brainDir(), { recursive: true });
+    const session = SessionState.load(); // isolated by KB_SESSION_ID (L4)
+    pi.on('session_start', async () => {
+        mkdirSync(brainDir(), { recursive: true });
+    });
+    // Tier A — session-start injection. The payload is the RESUME render (ADR-0020 pt 5):
+    // the prior-session continuity digest + the live knowledge bundle, both derived at
+    // render time. Parity with the claude SessionStart hook (`hook session-start`), which
+    // already injects renderResume — the pi half previously injected only the bundle, so
+    // cross-session continuity was undelivered here. Mark the bundle's entries injected so
+    // the per-turn delta won't repeat them.
+    pi.on('before_agent_start', async (...args) => {
+        const e = args[0] || {};
+        const current = e.systemPrompt || '';
+        const resume = renderResume(project(), session);
+        session.markInjected(currentInjectableIds());
+        session.save();
+        return { systemPrompt: current + '\n\n' + resume };
+    });
+    // Tier C — per-turn delta (Pi-only). Inject ONLY entries new since the last turn
+    // (session-deduped); skip when nothing changed.
+    pi.on('context', async (...args) => {
+        const event = args[0];
+        const messages = event?.messages ?? [];
+        const delta = renderContextDelta(session, project());
+        session.save();
+        if (!delta)
+            return undefined; // no-op turn
+        return { messages: [{ role: 'custom', content: delta }, ...messages] };
+    });
+    // Tool-gating (pre-execution). Gate brain-file writes here — the block MUST happen
+    // before the tool runs, so a blocked write never reaches tool_execution_end and is
+    // never captured. Capture itself moved to tool_execution_end (D-iv): tool_call has no
+    // result, so capturing here recorded every failure as capture:ok and the distiller
+    // could never act on a LIVE pi failure (the 2026-06-27 finding).
+    pi.on('tool_call', async (...args) => {
+        const e = args[0] || {};
+        if (isBrainWrite(e.toolName, e.input)) {
+            return { block: true, reason: GATING_REASON }; // refuse direct brain edits
+        }
+        return undefined;
+    });
+    // Correlate start→end by toolCallId so the capture keeps the call's INPUT (the end event
+    // carries result+isError but not args). Bounded: entries removed on end.
+    const pendingArgs = new Map();
+    pi.on('tool_execution_start', async (...args) => {
+        const e = args[0] || {};
+        if (e.toolCallId)
+            pendingArgs.set(e.toolCallId, e.args);
+        return undefined;
+    });
+    // Tier-B capture (D-iv) — fires AFTER the tool runs, with the result + pi's authoritative
+    // isError flag. Feed classifyToolOutcome the isError signal so a real failed call records
+    // as capture:error → the distiller turns it into a candidate gotcha (live auto-distill).
+    pi.on('tool_execution_end', async (...args) => {
+        const e = args[0] || {};
+        if (!e.toolName)
+            return undefined;
+        const input = e.toolCallId ? pendingArgs.get(e.toolCallId) : undefined;
+        if (e.toolCallId)
+            pendingArgs.delete(e.toolCallId);
+        const summary = resultText(e.result);
+        const tool_result = e.isError ? { isError: true, error: summary } : { isError: false, result: summary };
+        captureToolCall({ tool_name: e.toolName, tool_input: input, tool_result, call_id: e.toolCallId });
+        return undefined;
+    });
+    // Persist + commit the brain at session end.
+    pi.on('session_shutdown', async () => {
+        session.save();
+        try {
+            save('vfkb: session changes', 'agent');
+        }
+        catch {
+            /* non-git brain or git unavailable → skip */
+        }
+    });
+}

package/dist/pi-mcp-bridge.js

@@ -0,0 +1,94 @@
+// vfkb pi MCP bridge — gives pi genuine MCP capability (on par with Claude Code).
+//
+// pi ships NO MCP by design (its README: "build an extension that adds MCP support").
+// This is that extension: it reads a Claude-compatible mcpServers config, connects to
+// each (stdio) MCP server with the official @modelcontextprotocol/sdk client, lists
+// their tools, and registers each as a native pi tool named `mcp__<server>__<tool>`
+// (matching Claude Code's naming) that proxies to the server.
+//
+// Config (env VFKB_MCP_CONFIG = path to JSON), Claude-compatible:
+//   { "mcpServers": { "vfkb": { "command": "node", "args": ["…/dist/mcp-server.js"],
+//                                 "env": { "VFKB_DIR": "…" } } } }
+//
+// Load it like any pi extension:  pi -e dist/pi-mcp-bridge.js
+//
+// Connection model: CONNECT-PER-CALL. We connect once at load only to list tools (then
+// close that connection), and each tool `execute` opens → calls → closes its own
+// connection. This guarantees no MCP child process / stdio pipe lingers to keep pi's
+// event loop alive — so `pi -p` exits cleanly (a persistent connection made it hang).
+// Top-level await is safe: pi loads extensions via `await jiti.import(...)`, so module
+// evaluation (incl. discovery) completes before the default export is invoked.
+import { readFileSync, existsSync } from 'node:fs';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+async function connect(spec) {
+    const transport = new StdioClientTransport({
+        command: spec.command,
+        args: spec.args ?? [],
+        env: { ...process.env, ...(spec.env ?? {}) },
+    });
+    const client = new Client({ name: 'vfkb-pi-bridge', version: '0.0.0' });
+    await client.connect(transport);
+    return client;
+}
+function toContent(r) {
+    const content = (r.content ?? []).map((c) => ({
+        type: 'text',
+        text: typeof c.text === 'string' ? c.text : JSON.stringify(c),
+    }));
+    return { content: content.length ? content : [{ type: 'text', text: '(no content)' }], details: {} };
+}
+function readConfig() {
+    const p = process.env.VFKB_MCP_CONFIG;
+    if (!p || !existsSync(p))
+        return {};
+    try {
+        return (JSON.parse(readFileSync(p, 'utf8')).mcpServers ?? {});
+    }
+    catch {
+        return {};
+    }
+}
+async function discover() {
+    const defs = [];
+    for (const [name, spec] of Object.entries(readConfig())) {
+        let client;
+        try {
+            client = await connect(spec);
+            const { tools } = await client.listTools();
+            for (const t of tools) {
+                const toolName = t.name;
+                defs.push({
+                    name: `mcp__${name}__${toolName}`,
+                    label: toolName,
+                    description: t.description ?? `MCP tool ${toolName} on ${name}`,
+                    parameters: t.inputSchema ?? { type: 'object', properties: {} },
+                    // connect-per-call: open, call, close — nothing lingers.
+                    execute: async (_id, params) => {
+                        const c = await connect(spec);
+                        try {
+                            return toContent((await c.callTool({ name: toolName, arguments: params ?? {} })));
+                        }
+                        finally {
+                            await c.close().catch(() => { });
+                        }
+                    },
+                });
+            }
+            process.stderr.write(`vfkb-pi-bridge: bridged '${name}' (${tools.length} tools)\n`);
+        }
+        catch (e) {
+            process.stderr.write(`vfkb-pi-bridge: failed to bridge '${name}': ${e.message}\n`);
+        }
+        finally {
+            await client?.close().catch(() => { }); // close the discovery connection
+        }
+    }
+    return defs;
+}
+// Top-level await: completes before pi invokes the default export (loader awaits import).
+const DEFS = await discover();
+export default function (pi) {
+    for (const d of DEFS)
+        pi.registerTool(d);
+}

package/dist/pi-types.js

@@ -0,0 +1,6 @@
+// Minimal Pi extension types. The real types come from
+// @mariozechner/pi-coding-agent at runtime; these stubs are copied from the
+// VERIFIED mykb spike contract (src/extension/pi-types.ts + hooks/*), NOT
+// re-derived — mykb L7: hand-written Pi stubs were wrong and silently dropped
+// injection for weeks. Only the surface vfkb's Phase-0 face uses is included.
+export {};