@viloforge/vfkb 0.2.1

package/dist/read.js

@@ -0,0 +1,112 @@
+// vfkb read layer (Phase 3). Filtered/searched retrieval — the D5c filters
+// (status/zone/type/tags/author.role) over the storage kernel, with the ADR-0012
+// tiered reranker applied. Consumed by the CLI and (Phase 4) the MCP read tools.
+import { effectiveStatus, heuristicCompare, isInjectable, readAll, rerank, supersededIds, } from './engine.js';
+import { queryTermCount, selectIndex } from './index-store.js';
+// RFC-001: an explicit text query keeps only candidates that match at least this
+// fraction of the query's distinct terms. Default = 1/3 with a `>=` test, so a
+// 1–2 term query reduces to the existing score>0 (1/1, 1/2 ≥ 1/3) and a 3-term
+// query still admits a single strong match (1/3 ≥ 1/3), while the "1 common term
+// out of 8" noise that buried the devops-kb answer (1/8 < 1/3) is dropped.
+// Conservative by design: it can only remove genuine non-matches, never reorder or
+// drop a real top hit. Injection/listing carry no text → no floor (ADR-0016).
+export const DEFAULT_MIN_TERM_RATIO = 1 / 3;
+function arr(v) {
+    if (v === undefined)
+        return undefined;
+    return Array.isArray(v) ? v : [v];
+}
+// The single pipeline. `query` returns just the entries (unchanged contract);
+// `queryExplained` returns the entries plus, when empty, why (RFC-002).
+function run(opts = {}) {
+    const all = readAll();
+    const superseded = supersededIds(all);
+    // Stage 1 (ADR-0012): term-overlap candidates when text is given, else all.
+    // Capture the relevance score per id so Stage 2 can keep it as the primary
+    // sort key for search (without a query there is no score → score 0 → the
+    // heuristic order stands, which is what list/injection want).
+    const hasText = !!(opts.text && opts.text.trim());
+    const scored = hasText ? selectIndex().searchScored(opts.text, 200) : [];
+    // RFC-001 relevance floor: drop candidates matching < minTermRatio of the query's
+    // distinct terms, before Stage 2 / the limit. Applies only to explicit search;
+    // listing/injection have no text and skip this entirely.
+    const minRatio = opts.minTermRatio ?? DEFAULT_MIN_TERM_RATIO;
+    const qTerms = hasText ? queryTermCount(opts.text) : 0;
+    const floored = hasText && qTerms > 0 && minRatio > 0
+        ? scored.filter((s) => s.matched / qTerms >= minRatio)
+        : scored;
+    const scoreOf = new Map(floored.map((s) => [s.entry.id, s.score]));
+    const candidates = hasText ? floored.map((s) => s.entry) : all;
+    const types = arr(opts.type);
+    const zones = arr(opts.zone);
+    const statuses = arr(opts.status);
+    const roles = arr(opts.authorRole);
+    // Tally the reason each candidate is dropped (first failing reason wins — same
+    // keep/drop decision as before, now also classified for RFC-002).
+    const filteredOut = {};
+    const filtered = candidates.filter((e) => {
+        let reason = null;
+        if (types && !types.includes(e.type))
+            reason = 'type';
+        else if (zones && !zones.includes(e.zone))
+            reason = 'zone';
+        else if (roles && !roles.includes(e.author.role))
+            reason = 'role';
+        else if (opts.verifiedOnly && e.provenance.status !== 'verified')
+            reason = 'provenance';
+        else if (opts.tags && !opts.tags.every((t) => e.tags.includes(t)))
+            reason = 'tags';
+        else if (statuses) {
+            const eff = effectiveStatus(e, superseded);
+            if (!eff || !statuses.includes(eff))
+                reason = 'status';
+        }
+        // Supersession edge and freshness are handled separately from the D5c filters
+        // so the include_* flags are independent.
+        if (!reason && superseded.has(e.id) && !opts.includeSuperseded)
+            reason = 'superseded';
+        if (!reason && !opts.includeStale && !isInjectable(e))
+            reason = 'stale'; // freshness gate
+        if (reason) {
+            filteredOut[reason] = (filteredOut[reason] ?? 0) + 1;
+            return false;
+        }
+        return true;
+    });
+    // Stage 2 (ADR-0012): for an explicit text query, RELEVANCE is the primary key
+    // and the heuristic tier (type/trust/recency) is only the tiebreak among
+    // equally-relevant entries — so a relevant entry is never buried by a fresher,
+    // higher-trust, but barely-relevant one. Without a query, fall back to the pure
+    // heuristic order (the injection bundle / `kb_list` ordering).
+    const ranked = hasText
+        ? [...filtered].sort((a, b) => {
+            const s = (scoreOf.get(b.id) ?? 0) - (scoreOf.get(a.id) ?? 0);
+            return s !== 0 ? s : heuristicCompare(a, b);
+        })
+        : rerank(filtered);
+    const results = opts.limit ? ranked.slice(0, opts.limit) : ranked;
+    if (results.length > 0)
+        return { results };
+    // Empty (RFC-002): classify deterministically from the stage counts.
+    let diagnosis;
+    if (candidates.length > 0) {
+        // Candidates survived text + floor but the filters / ADR-0005 gate removed them.
+        diagnosis = { reason: 'all_filtered', candidates: candidates.length, filteredOut };
+    }
+    else if (hasText && scored.length > 0) {
+        // There were lexical matches, but none cleared the relevance floor (near-miss).
+        const b = scored[0];
+        diagnosis = { reason: 'no_match', candidates: 0, belowFloor: { entry: b.entry, matched: b.matched, queryTerms: qTerms } };
+    }
+    else {
+        // No lexical overlap at all (or a structural query with nothing in scope).
+        diagnosis = { reason: 'empty_topic', candidates: 0 };
+    }
+    return { results, diagnosis };
+}
+export function query(opts = {}) {
+    return run(opts).results;
+}
+export function queryExplained(opts = {}) {
+    return run(opts);
+}

package/dist/secrets.js

@@ -0,0 +1,36 @@
+// No-secrets write-time lint (D6e). The brain is git-committed (low-trust), so
+// secrets must never land in it. Named, high-signal patterns (low false-positive) —
+// not generic entropy. Checked at addEntry; explicit adds throw, passive captures
+// skip (handled by the caller).
+const PATTERNS = [
+    { kind: 'private-key-block', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+    { kind: 'aws-access-key-id', re: /\bAKIA[0-9A-Z]{16}\b/ },
+    { kind: 'github-token', re: /\bghp_[A-Za-z0-9]{36}\b/ },
+    { kind: 'github-pat', re: /\bgithub_pat_[A-Za-z0-9_]{22,}\b/ },
+    { kind: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+    { kind: 'gcp-api-key', re: /\bAIza[0-9A-Za-z\-_]{35}\b/ },
+    // Azure storage account key (the base64 value in a connection string / SAS) — the
+    // highest-likelihood secret for this Azure-ops substrate. AccountKey isn't an
+    // api[_-]?key, so the generic assigned-secret rule below misses it.
+    { kind: 'azure-storage-key', re: /\bAccountKey=[A-Za-z0-9+/]{30,}={0,2}/ },
+    { kind: 'bearer-token', re: /\bBearer\s+[A-Za-z0-9._~+/\-]{20,}=*\b/ },
+    {
+        kind: 'assigned-secret',
+        re: /\b(?:api[_-]?key|secret|token|password|passwd|pwd)\b\s*[:=]\s*['"]?[A-Za-z0-9_\-./+]{16,}/i,
+    },
+];
+export function detectSecrets(text) {
+    const hits = [];
+    for (const p of PATTERNS)
+        if (p.re.test(text))
+            hits.push({ kind: p.kind });
+    return hits;
+}
+export function assertNoSecrets(text) {
+    const hits = detectSecrets(text);
+    if (hits.length > 0) {
+        // Never echo the offending text — just the matched kind(s).
+        throw new Error(`refusing to store: looks like a secret (${hits.map((h) => h.kind).join(', ')}). ` +
+            `The brain is git-committed — keep secrets out (D6e).`);
+    }
+}

package/dist/session-end.js

@@ -0,0 +1,183 @@
+// Session-end continuity — GAP 2 (RFC-011 / ADR-0033): auto-commit the brain so
+// `/exit` is safe by default. The committed brain (`.vfkb/entries.jsonl`, ADR-0019)
+// ships INSIDE the surrounding project repo, so this is NOT git.ts:save() (which
+// runs a standalone brain repo with `git add -A`). Here we commit ONE pathspec into
+// the project repo, on the CURRENT branch, NEVER on the default branch (decision
+// 34f2f2da: branch + PR-first), and we must never sweep in the operator's other
+// staged files (so a pathspec-`--only` commit, not a bare `git commit`).
+//
+// Fail-open throughout: a SessionEnd hook cannot block exit and must never throw.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { addEntry } from './engine.js';
+const realGit = (args, cwd) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+// Repo-relative path to the brain file, POSIX-normalized. git's `HEAD:<path>` tree
+// lookup needs forward slashes even on Windows (path.join yields `\` there) — without
+// this, the lookup fails, headCount→0, and every existing entry is treated as "new".
+// Matches the convention in stop-reminder.ts (relative(...).replace(/\\/g,'/')).
+export function brainEntriesRelPath(dataDir) {
+    return join(dataDir, 'entries.jsonl').replace(/\\/g, '/');
+}
+function tryGit(git, args, cwd) {
+    try {
+        return git(args, cwd).trim();
+    }
+    catch {
+        return null;
+    }
+}
+// Count added lines (≈ new JSONL entries) for the brain file, working tree + index.
+function countAdded(git, cwd, path) {
+    let added = 0;
+    for (const base of [['diff'], ['diff', '--cached']]) {
+        const out = tryGit(git, [...base, '--numstat', '--', path], cwd);
+        if (!out)
+            continue;
+        for (const line of out.split('\n')) {
+            const n = Number(line.split('\t')[0]);
+            if (Number.isFinite(n))
+                added += n;
+        }
+    }
+    return added;
+}
+// Entries appended to the brain since HEAD (append-only, ADR-0019): the lines beyond
+// the committed line count — the same git-HEAD-delta signal stop-reminder.ts uses, so
+// it needs NO session state (KB_SESSION_ID is unset in the live wiring — gotcha e8f324dc).
+function newEntriesSinceHead(git, cwd, repoRelEntries, absEntries) {
+    let lines;
+    try {
+        lines = readFileSync(absEntries, 'utf8').split('\n').filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+    let headCount = 0;
+    const head = tryGit(git, ['show', `HEAD:${repoRelEntries}`], cwd);
+    if (head !== null)
+        headCount = head.split('\n').filter(Boolean).length;
+    return lines
+        .slice(headCount)
+        .map((l) => {
+        try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((e) => e !== null);
+}
+const isHandoff = (e) => (e.tags ?? []).some((t) => t === 'handoff' || t === 'next');
+const oneLine = (s) => (s || '').replace(/\s+/g, ' ').trim();
+// GAP 1 (B2 floor, ADR-0033 follow-on): when a session recorded knowledge but left no
+// explicit handoff, write a minimal, honest fallback that ENUMERATES the session's new
+// entries — deterministic (no transcript NLP), so a fresh clone always gets a committed
+// pointer to the session's contribution. Surfaces via the knowledge bundle (it is a
+// committed `fact`, independent of session records). Tagged `auto` to distinguish it
+// from an agent-authored handoff. Writes through the engine (correct envelope); the
+// engine resolves the brain via VFKB_DATA_DIR, so point it at the resolved dir for the call.
+function writeAutoHandoff(absBrain, fresh, sessionId) {
+    const CAP = 12;
+    const list = fresh
+        .slice(0, CAP)
+        .map((e) => `${e.id ?? '?'} [${e.type ?? '?'}] ${oneLine(e.text ?? '').slice(0, 70)}`)
+        .join('; ');
+    const more = fresh.length > CAP ? ` (+${fresh.length - CAP} more)` : '';
+    const n = fresh.length;
+    const text = `Auto-handoff (session-end): no explicit handoff was recorded, but this session added ` +
+        `${n} brain entr${n === 1 ? 'y' : 'ies'} since the last commit — ${list}${more}. ` +
+        'Next session: review these and record an explicit `next:` if continuing.';
+    const prev = process.env.VFKB_DATA_DIR;
+    process.env.VFKB_DATA_DIR = absBrain;
+    try {
+        addEntry('fact', text, {
+            role: 'executor',
+            zone: 'established',
+            tags: ['handoff', 'next', 'auto'],
+            sessionId, // ADR-0039: attribute the fallback handoff to the ending session
+        });
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.VFKB_DATA_DIR;
+        else
+            process.env.VFKB_DATA_DIR = prev;
+    }
+}
+// The repo's default branch (e.g. "main"/"master"), best-effort; falls back to "main".
+function defaultBranch(git, cwd) {
+    const ref = tryGit(git, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], cwd);
+    if (ref && ref.startsWith('origin/'))
+        return ref.slice('origin/'.length);
+    return 'main';
+}
+export function runSessionEnd(opts = {}) {
+    const git = opts.git ?? realGit;
+    const cwd = opts.cwd || process.cwd();
+    const dataDir = opts.dataDir || process.env.VFKB_DATA_DIR || process.env.VFKB_DIR || '.vfkb';
+    const sessionId = opts.sessionId ?? process.env.KB_SESSION_ID;
+    const entries = brainEntriesRelPath(dataDir);
+    try {
+        // 1) Must be inside a git work tree (committed-brain model). Otherwise no-op.
+        if (tryGit(git, ['rev-parse', '--is-inside-work-tree'], cwd) !== 'true') {
+            return { committed: false, reason: 'not-a-repo' };
+        }
+        // 2) Nothing staged or unstaged for the brain file → nothing to do (silent).
+        const status = tryGit(git, ['status', '--porcelain', '--', entries], cwd);
+        if (!status)
+            return { committed: false, reason: 'brain-clean' };
+        const tag = sessionId ? `, session ${sessionId.slice(0, 8)}` : '';
+        // 3) Branch guard — never commit on a detached HEAD or the default branch.
+        const branch = tryGit(git, ['symbolic-ref', '--short', '-q', 'HEAD'], cwd) || '';
+        const def = defaultBranch(git, cwd);
+        if (!branch) {
+            const added = countAdded(git, cwd, entries);
+            return {
+                committed: false,
+                reason: 'detached-head',
+                added,
+                systemMessage: `vfkb: ${added} new brain entr${added === 1 ? 'y' : 'ies'} uncommitted (detached HEAD) — check out a branch and commit to preserve continuity.`,
+            };
+        }
+        if (branch === def || branch === 'main' || branch === 'master') {
+            const added = countAdded(git, cwd, entries);
+            return {
+                committed: false,
+                reason: 'on-default-branch',
+                branch,
+                added,
+                systemMessage: `vfkb: ${added} new brain entr${added === 1 ? 'y' : 'ies'} on \`${branch}\` left uncommitted — branch + commit to preserve continuity (vfkb never auto-commits the default branch).`,
+            };
+        }
+        // 4) GAP 1 (B2 floor): guarantee a committed handoff exists. If the session left no
+        //    handoff/next entry among its new-since-HEAD entries, write a fallback that
+        //    enumerates them — BEFORE the commit, so it ships in the same commit.
+        const absBrain = isAbsolute(dataDir) ? dataDir : join(cwd, dataDir);
+        const fresh = newEntriesSinceHead(git, cwd, entries, join(absBrain, 'entries.jsonl'));
+        let autoHandoff = false;
+        if (fresh.length > 0 && !fresh.some(isHandoff)) {
+            try {
+                writeAutoHandoff(absBrain, fresh, sessionId);
+                autoHandoff = true;
+            }
+            catch {
+                /* handoff is best-effort; never let it block the commit */
+            }
+        }
+        // 5) Pathspec-scoped commit. Stage ONLY the brain file (leaves any other staged
+        //    files alone), then commit with `--only` so even pre-staged files are NOT
+        //    swept into this auto-commit.
+        const added = countAdded(git, cwd, entries);
+        const message = `chore(brain): session-end auto-commit (${added} new entr${added === 1 ? 'y' : 'ies'}${tag})`;
+        git(['add', '--', entries], cwd);
+        // `-m` MUST precede `--`; everything after `--` is treated as a pathspec.
+        git(['commit', '-o', '-m', message, '--', entries], cwd);
+        return { committed: true, reason: 'committed', branch, added, message, autoHandoff };
+    }
+    catch {
+        // Any git failure (no identity, hook rejection, …) → fail-open, never block exit.
+        return { committed: false, reason: 'error' };
+    }
+}

package/dist/session-end.test.js

@@ -0,0 +1,149 @@
+// GAP-2 deterministic gate (RFC-011 / ADR-0033, ADR-0029 proof for the auto-commit
+// mechanism): the SessionEnd hook auto-commits the brain into the SURROUNDING repo,
+// on a topic branch, scoped to entries.jsonl, NEVER on the default branch, and never
+// sweeping in the operator's pre-staged files. Runs against a real throwaway git repo
+// (the mechanism is git behaviour, so we exercise real git — not a mock).
+import { describe, it, expect, beforeEach } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runSessionEnd, brainEntriesRelPath } from './session-end.js';
+let repo;
+const git = (args, cwd = repo) => execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+const ENTRIES = '.vfkb/entries.jsonl';
+function addEntry(line = '{"id":"x","type":"fact","text":"t"}') {
+    appendFileSync(join(repo, ENTRIES), line + '\n');
+}
+// A handoff-tagged entry suppresses the B2 auto-handoff — use it to keep the
+// GAP-2 commit-mechanics tests isolated from the GAP-1 (B2) behaviour.
+const HANDOFF_ENTRY = '{"id":"h","type":"fact","text":"next: do the thing","tags":["handoff"]}';
+const readEntries = () => readFileSync(join(repo, ENTRIES), 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => JSON.parse(l));
+beforeEach(() => {
+    repo = mkdtempSync(join(tmpdir(), 'vfkb-se-'));
+    git(['init', '-q', '-b', 'main']);
+    git(['config', 'user.name', 'Test']);
+    git(['config', 'user.email', 'test@example.com']);
+    git(['config', 'commit.gpgsign', 'false']);
+    mkdirSync(join(repo, '.vfkb'), { recursive: true });
+    writeFileSync(join(repo, ENTRIES), '');
+    writeFileSync(join(repo, 'README.md'), '# repo\n');
+    git(['add', '-A']);
+    git(['commit', '-q', '-m', 'init']);
+});
+describe('brainEntriesRelPath — POSIX normalization for git HEAD: lookup', () => {
+    it('passes posix paths through unchanged', () => {
+        expect(brainEntriesRelPath('.vfkb')).toBe('.vfkb/entries.jsonl');
+    });
+    it('normalizes backslashes to forward slashes (the Windows git HEAD: bug)', () => {
+        // simulates a win32 path.join result / a backslash-containing dataDir
+        expect(brainEntriesRelPath('sub\\.vfkb')).toBe('sub/.vfkb/entries.jsonl');
+    });
+});
+describe('SessionEnd auto-commit (GAP 2)', () => {
+    it('commits ONLY entries.jsonl on a topic branch, attribution-free message', () => {
+        git(['checkout', '-q', '-b', 'feat/work']);
+        addEntry(HANDOFF_ENTRY); // handoff present → no B2 auto-handoff, keeps added=1
+        const r = runSessionEnd({ cwd: repo, dataDir: '.vfkb', sessionId: 'abcd1234efgh' });
+        expect(r.committed).toBe(true);
+        expect(r.reason).toBe('committed');
+        expect(r.branch).toBe('feat/work');
+        expect(r.added).toBe(1);
+        // The HEAD commit touches only the brain file.
+        const files = git(['show', '--name-only', '--pretty=format:', 'HEAD']).split('\n').filter(Boolean);
+        expect(files).toEqual([ENTRIES]);
+        const msg = git(['log', '-1', '--pretty=%B']);
+        expect(msg).toContain('chore(brain): session-end auto-commit');
+        expect(msg).toContain('session abcd1234'); // short id
+        // No AI attribution anywhere in the message.
+        expect(msg.toLowerCase()).not.toContain('claude');
+        expect(msg).not.toContain('Co-Authored-By');
+        expect(msg).not.toContain('🤖');
+    });
+    it('NEVER commits on the default branch (main) — warns instead', () => {
+        addEntry(); // still on main
+        const head = git(['rev-parse', 'HEAD']);
+        const r = runSessionEnd({ cwd: repo, dataDir: '.vfkb' });
+        expect(r.committed).toBe(false);
+        expect(r.reason).toBe('on-default-branch');
+        expect(r.systemMessage).toContain('main');
+        expect(r.systemMessage).toContain('branch + commit');
+        expect(git(['rev-parse', 'HEAD'])).toBe(head); // no new commit
+        expect(git(['status', '--porcelain', '--', ENTRIES])).not.toBe(''); // still dirty
+    });
+    it('does NOT sweep in the operator\'s pre-staged files (pathspec --only)', () => {
+        git(['checkout', '-q', '-b', 'feat/work']);
+        // Operator has staged their own file for a separate commit.
+        writeFileSync(join(repo, 'src.txt'), 'operator work\n');
+        git(['add', 'src.txt']);
+        addEntry(HANDOFF_ENTRY); // isolate from B2
+        const r = runSessionEnd({ cwd: repo, dataDir: '.vfkb' });
+        expect(r.committed).toBe(true);
+        // The auto-commit must contain ONLY entries.jsonl, not src.txt.
+        const files = git(['show', '--name-only', '--pretty=format:', 'HEAD']).split('\n').filter(Boolean);
+        expect(files).toEqual([ENTRIES]);
+        // src.txt is still staged (untouched), not committed.
+        expect(git(['diff', '--cached', '--name-only'])).toBe('src.txt');
+    });
+    it('is a no-op when the brain is clean', () => {
+        git(['checkout', '-q', '-b', 'feat/work']);
+        const head = git(['rev-parse', 'HEAD']);
+        const r = runSessionEnd({ cwd: repo, dataDir: '.vfkb' });
+        expect(r.committed).toBe(false);
+        expect(r.reason).toBe('brain-clean');
+        expect(git(['rev-parse', 'HEAD'])).toBe(head);
+    });
+    it('warns and does not commit on a detached HEAD', () => {
+        git(['checkout', '-q', '-b', 'feat/work']);
+        addEntry();
+        git(['add', '-A']);
+        git(['commit', '-q', '-m', 'pin']);
+        git(['checkout', '-q', '--detach']);
+        addEntry();
+        const r = runSessionEnd({ cwd: repo, dataDir: '.vfkb' });
+        expect(r.committed).toBe(false);
+        expect(r.reason).toBe('detached-head');
+        expect(r.systemMessage).toContain('detached HEAD');
+    });
+    it('is a no-op (not-a-repo) outside a git work tree', () => {
+        const bare = mkdtempSync(join(tmpdir(), 'vfkb-nogit-'));
+        mkdirSync(join(bare, '.vfkb'), { recursive: true });
+        writeFileSync(join(bare, ENTRIES), '{"id":"x"}\n');
+        const r = runSessionEnd({ cwd: bare, dataDir: '.vfkb' });
+        expect(r.committed).toBe(false);
+        expect(r.reason).toBe('not-a-repo');
+    });
+    // GAP 1 (B2 deterministic floor): when a session records knowledge but no handoff,
+    // SessionEnd writes a fallback handoff enumerating the new entries, then commits it.
+    it('writes & commits an auto-handoff when the session left none (B2)', () => {
+        git(['checkout', '-q', '-b', 'feat/work']);
+        addEntry('{"id":"k1","type":"decision","text":"chose approach X over Y"}');
+        addEntry('{"id":"k2","type":"gotcha","text":"watch out for Z"}');
+        const r = runSessionEnd({ cwd: repo, dataDir: '.vfkb' });
+        expect(r.committed).toBe(true);
+        expect(r.autoHandoff).toBe(true);
+        const entries = readEntries();
+        const auto = entries.find((e) => (e.tags ?? []).includes('auto'));
+        expect(auto).toBeDefined();
+        expect(auto.tags).toEqual(expect.arrayContaining(['handoff', 'next', 'auto']));
+        // It enumerates the session's real entries (so a fresh clone has a pointer).
+        expect(auto.text).toContain('k1');
+        expect(auto.text).toContain('k2');
+        // It is COMMITTED (survives a fresh clone), in a commit touching only the brain.
+        const files = git(['show', '--name-only', '--pretty=format:', 'HEAD']).split('\n').filter(Boolean);
+        expect(files).toEqual([ENTRIES]);
+        expect(git(['status', '--porcelain', '--', ENTRIES])).toBe(''); // fully committed
+    });
+    it('does NOT write an auto-handoff when the session already recorded one (B2)', () => {
+        git(['checkout', '-q', '-b', 'feat/work']);
+        addEntry('{"id":"k1","type":"fact","text":"some work"}');
+        addEntry(HANDOFF_ENTRY); // agent authored a real handoff this session
+        const r = runSessionEnd({ cwd: repo, dataDir: '.vfkb' });
+        expect(r.committed).toBe(true);
+        expect(r.autoHandoff).toBe(false);
+        expect(readEntries().some((e) => (e.tags ?? []).includes('auto'))).toBe(false);
+    });
+});

package/dist/session.js

@@ -0,0 +1,157 @@
+// Per-session state, isolated by session id (mykb L4: a single global pointer
+// let concurrent sessions clobber each other). State lives under <brain>/.sessions/
+// <id>.json — under the brain mount (survives container restart), NOT /tmp. Without
+// a session id, state is in-memory only (single-session default; nothing to clobber).
+//
+// ADR-0039 (v2 session backbone): the id normally comes from the HARNESS — Claude Code
+// delivers `session_id` on every hook's stdin JSON, and the hooks thread it here via
+// effectiveSessionId(). KB_SESSION_ID is an optional OVERRIDE (for harnesses that
+// can't supply stdin the same way), not the only path. Verified 2026-07-06 (CLI
+// v2.1.201): the stdin id is stable across `claude -p --resume` turns of one
+// conversation, so records keyed on it accumulate correctly.
+//
+// ADR-0020 (session-continuity): each session's file is ONE record in an append-only
+// log (per-session-id → never clobbered across sessions). The record carries the
+// SIGNALS of the session (injected/captured ids, turn count, timestamps, an optional
+// asserted operator note + asserted caller signals) — NOT a prose summary. The resume
+// DIGEST is DERIVED from these signals against the live brain at render time
+// (engine.renderResume), so it cannot go stale.
+import { spawnSync } from 'node:child_process';
+import { storageBackend } from './backend.js';
+function now() {
+    return new Date().toISOString();
+}
+// ADR-0039: resolve the effective session id for a hook invocation.
+// KB_SESSION_ID (when set) OVERRIDES the harness-supplied stdin id.
+export function effectiveSessionId(payloadId) {
+    return process.env.KB_SESSION_ID || payloadId || undefined;
+}
+// Best-effort git branch at session start (identity surface, ADR-0039). The hooks run
+// at the session cwd (the repo); outside a work tree this is undefined, never a throw.
+function currentBranch() {
+    try {
+        const r = spawnSync('git', ['symbolic-ref', '--short', '-q', 'HEAD'], {
+            encoding: 'utf8',
+            timeout: 2000,
+        });
+        const b = (r.stdout || '').trim();
+        return r.status === 0 && b ? b : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export class SessionState {
+    data;
+    injected = new Set();
+    captured = new Set();
+    persisted; // false → ephemeral, in-memory only
+    sessionId;
+    constructor(persisted, sessionId) {
+        this.persisted = persisted && !!sessionId;
+        this.sessionId = sessionId;
+        const ts = now();
+        this.data = {
+            sessionId,
+            startedAt: ts,
+            lastAt: ts,
+            turnCount: 0,
+            injectedIds: [],
+            capturedIds: [],
+            // Identity surface (ADR-0039) — stamped at record creation, best-effort.
+            agentRole: process.env.VFKB_AGENT_ROLE || undefined,
+            agentLabel: process.env.VFKB_AGENT_LABEL || undefined,
+            branch: currentBranch(),
+            pid: process.pid,
+        };
+        const raw = this.persisted && sessionId ? storageBackend().readSessionRecord(sessionId) : null;
+        if (raw !== null) {
+            try {
+                const loaded = JSON.parse(raw);
+                this.data = {
+                    sessionId,
+                    startedAt: loaded.startedAt ?? ts,
+                    lastAt: loaded.lastAt ?? ts,
+                    turnCount: loaded.turnCount ?? 0,
+                    injectedIds: loaded.injectedIds ?? [],
+                    capturedIds: loaded.capturedIds ?? [],
+                    note: loaded.note,
+                    signals: loaded.signals,
+                    // preserve the CREATION-time identity; never restamp on later loads
+                    agentRole: loaded.agentRole,
+                    agentLabel: loaded.agentLabel,
+                    branch: loaded.branch,
+                    pid: loaded.pid,
+                };
+                this.injected = new Set(this.data.injectedIds);
+                this.captured = new Set(this.data.capturedIds);
+            }
+            catch {
+                /* corrupt session file → start fresh */
+            }
+        }
+    }
+    static load(sessionId = process.env.KB_SESSION_ID) {
+        if (!sessionId)
+            return new SessionState(false); // ephemeral, in-memory only
+        return new SessionState(true, sessionId); // keyed storage via the backend (ADR-0044)
+    }
+    // The CONCURRENT-SESSION REGISTRY (ADR-0039 §4): every persisted session record
+    // against this brain, newest-first by lastAt. This is the surface other mechanisms
+    // consult to ask "which other sessions are/were active against this brain" —
+    // e.g. ADR-0040's lock logs its holder against it, and a future contradiction
+    // check can scope "concurrent" by [startedAt, lastAt] overlap. Append-only: one
+    // file per session id, never a shared mutable singleton.
+    static records() {
+        const be = storageBackend();
+        const out = [];
+        for (const id of be.listSessionIds()) {
+            try {
+                const raw = be.readSessionRecord(id);
+                if (raw !== null)
+                    out.push(JSON.parse(raw));
+            }
+            catch {
+                /* skip a corrupt record */
+            }
+        }
+        return out.sort((a, b) => (b.lastAt ?? '').localeCompare(a.lastAt ?? ''));
+    }
+    isInjected(id) {
+        return this.injected.has(id);
+    }
+    markInjected(ids) {
+        for (const id of ids)
+            this.injected.add(id);
+    }
+    recordCaptured(id) {
+        this.captured.add(id);
+    }
+    get capturedIds() {
+        return [...this.captured];
+    }
+    setNote(text) {
+        this.data.note = text;
+    }
+    addSignal(label, value) {
+        (this.data.signals ??= []).push({ label, value });
+    }
+    bumpTurn() {
+        this.data.turnCount++;
+    }
+    get turnCount() {
+        return this.data.turnCount;
+    }
+    get startedAt() {
+        return this.data.startedAt;
+    }
+    save() {
+        if (!this.persisted || !this.sessionId)
+            return; // ephemeral
+        this.data.sessionId = this.sessionId;
+        this.data.lastAt = now();
+        this.data.injectedIds = [...this.injected];
+        this.data.capturedIds = [...this.captured];
+        storageBackend().writeSessionRecord(this.sessionId, JSON.stringify(this.data));
+    }
+}