osborn 0.9.249 → 0.9.251

package/dist/claude-llm.js

@@ -14,6 +14,7 @@ import { statusManager } from './status-manager.js';
 import { getResearchSystemPrompt, getDirectModeResearchPrompt, getGroundingBlock, getRecalledContextBlock } from './prompts.js';
 import { openStore, recall, storeExists, updateSessionStore, getStorePath } from './session-store.js';
 import { getEmbedder } from './embedder.js';
+import { launchCompactionLens } from './content/lens-launch.js';
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
 import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -2389,6 +2390,18 @@ class ClaudeLLMStream extends llm.LLMStream {
                                         catch (ucErr) {
                                             console.error('⚠️ PostCompact: USER_CONTEXT write failed:', ucErr instanceof Error ? ucErr.message : ucErr);
                                         }
+                                        // ── Section 6: CONTENT_LENS — detached background worker appends to <project>/content-profile.md ──
+                                        // Passes ONLY the session key (+ transcript_path/cwd); the worker derives everything else.
+                                        // ON by default; OSBORN_CONTENT_LENS=0|off|false|no disables. Spawn is sync + unref'd: never awaited.
+                                        try {
+                                            if (!['0', 'off', 'false', 'no'].includes((process.env.OSBORN_CONTENT_LENS || '').trim().toLowerCase())) {
+                                                const cl = launchCompactionLens({ sessionId: input?.session_id || sessionId, transcriptPath: input?.transcript_path, cwd: this.#opts.workingDirectory });
+                                                progress('Content lens', cl.status === 'spawned' ? 'background worker started' : cl.status);
+                                            }
+                                        }
+                                        catch (clErr) {
+                                            console.error('⚠️ PostCompact: CONTENT_LENS launch failed:', clErr instanceof Error ? clErr.message : clErr);
+                                        }
                                         this.#opts.onCompactionEvent?.({ type: 'compaction_complete', skillsWritten, skillNames });
                                         console.log(`🧠 PostCompact: complete — ${skillsWritten} skill file(s) written: [${skillNames.join(', ')}]`);
                                     }

package/dist/content/compaction-lens-worker.d.ts

@@ -0,0 +1,23 @@
+/**
+ * compaction-lens-worker.ts — DETACHED worker entry for the content lens.
+ *
+ * Two entries:
+ *   node compaction-lens-worker.js <argfile>
+ *       per-compaction (spawned by lens-launch.ts). The argfile (mode 0600,
+ *       deleted immediately after reading) carries only
+ *       { sessionId, transcriptPath?, cwd?, lockDir? }. INCREMENTAL: only
+ *       session.db rows newer than the per-session high-water mark.
+ *   node compaction-lens-worker.js --backfill <sessionId> [--cwd <dir>] [--max-windows N] [--out <path>]
+ *       BACKFILL: pages the whole session from row 0 (bounded by the per-run
+ *       cost/call cap). Takes the per-project lock itself. --out writes a review
+ *       copy to <path> instead of content-profile.md and leaves the HWM alone.
+ *   node compaction-lens-worker.js --library <sessionId> [--cwd <dir>] [--dry] [--out-dir <dir>]
+ *       LIBRARY step only (manual / dry run). Takes the per-project lock itself.
+ * Per-compaction runs do TWO independent, fail-open steps under one lock:
+ *   1. the content lens (content-profile.md + HWM), unchanged;
+ *   2. the library step (lens-library.ts): one period-map page for the period
+ *      that just ended + INDEX.md. A failure in either never stops the other.
+ * Fully self-contained: top-level try/catch, redacted log in the project dir,
+ * refreshes + releases the per-project lock, always exits.
+ */
+export {};

package/dist/content/compaction-lens-worker.js

@@ -0,0 +1,188 @@
+/**
+ * compaction-lens-worker.ts — DETACHED worker entry for the content lens.
+ *
+ * Two entries:
+ *   node compaction-lens-worker.js <argfile>
+ *       per-compaction (spawned by lens-launch.ts). The argfile (mode 0600,
+ *       deleted immediately after reading) carries only
+ *       { sessionId, transcriptPath?, cwd?, lockDir? }. INCREMENTAL: only
+ *       session.db rows newer than the per-session high-water mark.
+ *   node compaction-lens-worker.js --backfill <sessionId> [--cwd <dir>] [--max-windows N] [--out <path>]
+ *       BACKFILL: pages the whole session from row 0 (bounded by the per-run
+ *       cost/call cap). Takes the per-project lock itself. --out writes a review
+ *       copy to <path> instead of content-profile.md and leaves the HWM alone.
+ *   node compaction-lens-worker.js --library <sessionId> [--cwd <dir>] [--dry] [--out-dir <dir>]
+ *       LIBRARY step only (manual / dry run). Takes the per-project lock itself.
+ * Per-compaction runs do TWO independent, fail-open steps under one lock:
+ *   1. the content lens (content-profile.md + HWM), unchanged;
+ *   2. the library step (lens-library.ts): one period-map page for the period
+ *      that just ended + INDEX.md. A failure in either never stops the other.
+ * Fully self-contained: top-level try/catch, redacted log in the project dir,
+ * refreshes + releases the per-project lock, always exits.
+ */
+import { readFileSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { runCompactionLens } from './compaction-lens.js';
+import { resolveSessionDb } from './lens-db.js';
+import { acquireLock, refuseOutPath, releaseLock, resolveProjectDir, touchLock } from './lens-paths.js';
+import { logLine } from './lens-profile.js';
+import { runLibraryStep } from './lens-library.js';
+// ≤2 big windows + reduce at ≤6 min/call, then the library step (1 call ≤6 min + model meta).
+const INCREMENTAL_TIMEOUT_MS = 35 * 60_000;
+const BACKFILL_TIMEOUT_MS = 3 * 60 * 60_000;
+const LIBRARY_TIMEOUT_MS = 15 * 60_000;
+function argVal(argv, flag) {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+function parseJob(argv) {
+    if (argv[0] === '--library') {
+        const sessionId = argv[1];
+        if (!sessionId || sessionId.startsWith('--'))
+            throw new Error('usage: --library <sessionId> [--cwd <dir>] [--dry] [--out-dir <dir>]');
+        const cwd = argVal(argv, '--cwd');
+        const db = resolveSessionDb(sessionId, null, cwd);
+        const projectDir = db ? dirname(dirname(dirname(db))) : null;
+        const outDir = argv.includes('--out-dir') ? argVal(argv, '--out-dir') : undefined;
+        if (argv.includes('--out-dir') && (!outDir || outDir.startsWith('--')))
+            throw new Error('library: --out-dir requires a directory');
+        if (!projectDir || !acquireLock(projectDir))
+            throw new Error(`library: project dir ${projectDir ?? '(none)'} missing or locked`);
+        return {
+            opts: { sessionId, cwd, mode: 'incremental' },
+            kind: 'library',
+            library: { dry: argv.includes('--dry'), outDir },
+            lockDir: projectDir,
+            logDir: projectDir,
+            timeoutMs: LIBRARY_TIMEOUT_MS,
+        };
+    }
+    if (argv[0] === '--backfill') {
+        const sessionId = argv[1];
+        if (!sessionId)
+            throw new Error('usage: --backfill <sessionId> [--cwd <dir>] [--max-windows N] [--out <path>]');
+        const cwd = argVal(argv, '--cwd');
+        const db = resolveSessionDb(sessionId, null, cwd);
+        const projectDir = db ? dirname(dirname(dirname(db))) : cwd ? resolveProjectDir(undefined, cwd) : null;
+        // review copy: overwrite this file, never the profile, never move the HWM.
+        // Validated BEFORE the lock so a bad --out aborts without leaving a lock behind.
+        const outPath = argv.includes('--out') ? argVal(argv, '--out') : undefined;
+        if (argv.includes('--out')) {
+            const why = refuseOutPath(outPath, projectDir);
+            if (why)
+                throw Object.assign(new Error(`backfill: ${why}`), { logDir: projectDir });
+        }
+        if (!projectDir || !acquireLock(projectDir))
+            throw new Error(`backfill: project dir ${projectDir ?? '(none)'} missing or locked`);
+        const mw = Number(argVal(argv, '--max-windows'));
+        return {
+            opts: {
+                sessionId, cwd, mode: 'backfill', maxWindows: Number.isFinite(mw) && mw > 0 ? mw : undefined,
+                ...(outPath ? { outPath, updateHwm: false } : {}),
+            },
+            lockDir: projectDir,
+            logDir: projectDir,
+            timeoutMs: BACKFILL_TIMEOUT_MS,
+        };
+    }
+    const argFile = argv[0];
+    let payload = {};
+    try {
+        payload = JSON.parse(readFileSync(argFile, 'utf-8'));
+    }
+    finally {
+        try {
+            rmSync(argFile, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const lockDir = payload.lockDir || null;
+    const logDir = lockDir || resolveProjectDir(payload.transcriptPath, payload.cwd);
+    if (!payload.sessionId)
+        throw Object.assign(new Error('payload missing sessionId'), { lockDir, logDir });
+    return {
+        opts: { sessionId: payload.sessionId, transcriptPath: payload.transcriptPath, cwd: payload.cwd, mode: 'incremental' },
+        lockDir,
+        logDir,
+        timeoutMs: INCREMENTAL_TIMEOUT_MS,
+    };
+}
+async function main() {
+    let job = null;
+    let logDir = null;
+    let lockDir = null;
+    try {
+        try {
+            job = parseJob(process.argv.slice(2));
+        }
+        catch (err) {
+            lockDir = err?.lockDir ?? null;
+            logDir = err?.logDir ?? null;
+            throw err;
+        }
+        lockDir = job.lockDir;
+        logDir = job.logDir;
+        const sid = job.opts.sessionId.substring(0, 8);
+        const killer = setTimeout(() => {
+            logLine(logDir, `session ${sid}: hard timeout — exiting`);
+            if (lockDir)
+                releaseLock(lockDir);
+            process.exit(2);
+        }, job.timeoutMs);
+        killer.unref();
+        const t0 = Date.now();
+        let lensErr = null;
+        // Step 1 — content lens (skipped by the --library entry).
+        if (job.kind !== 'library') {
+            try {
+                const r = await runCompactionLens({
+                    ...job.opts,
+                    onWindow: () => lockDir && touchLock(lockDir),
+                    log: m => logLine(logDir, `session ${sid} [${job.opts.mode}]: ${m}`),
+                });
+                logDir = r.projectDir || logDir;
+                logLine(logDir, `session ${sid}: done status=${r.status} mode=${r.mode} rows=${r.records} windows=${r.windowsProcessed}/${r.windowsTotal} ` +
+                    `calls=${r.modelCalls} cost=$${r.costUsd.toFixed(4)} kept=${r.kept.angles}A/${r.kept.capabilities}C ` +
+                    `dropped=${r.mapDropped.angles + r.dropped.angles}A/${r.mapDropped.capabilities + r.dropped.capabilities}C ` +
+                    `notDone=${r.notDone} billing=${r.billingDropped} hwm=${r.hwmBefore}→${r.hwmAfter} ${Date.now() - t0}ms`);
+            }
+            catch (err) {
+                lensErr = err;
+                logLine(logDir, `worker error: ${err instanceof Error ? err.stack || err.message : String(err)}`);
+            }
+        }
+        // Step 2 — library page for the period that just ended (per-compaction + --library only; never backfill).
+        // runLibraryStep never throws; any failure is logged and the worker still exits cleanly.
+        if (job.opts.mode === 'incremental') {
+            if (lockDir)
+                touchLock(lockDir);
+            const lib = await runLibraryStep({
+                sessionId: job.opts.sessionId,
+                projectDir: lockDir,
+                cwd: job.opts.cwd,
+                ...job.library,
+                keepAlive: () => lockDir && touchLock(lockDir),
+                log: m => logLine(logDir, `session ${sid} [library]: ${m}`),
+            });
+            logLine(logDir, `session ${sid}: library status=${lib.status} cost=$${lib.costUsd.toFixed(4)}${lib.page ? ` page=${lib.page}` : ''}`);
+            if (job.kind === 'library')
+                process.stdout.write(`${JSON.stringify({ status: lib.status, page: lib.page, index: lib.index, period: lib.period, cost: lib.costUsd, errors: lib.errors })}\n`);
+        }
+        return lensErr ? 1 : 0;
+    }
+    catch (err) {
+        logLine(logDir, `worker error: ${err instanceof Error ? err.stack || err.message : String(err)}`);
+        if (err instanceof Error && /^(backfill|library):/.test(err.message))
+            process.stderr.write(`${err.message}\n`);
+        return 1;
+    }
+    finally {
+        if (lockDir)
+            releaseLock(lockDir);
+    }
+}
+main()
+    .then(code => process.exit(code))
+    .catch(() => process.exit(1));

package/dist/content/compaction-lens.d.ts

@@ -0,0 +1,106 @@
+/**
+ * compaction-lens.ts — the content-lens PIPELINE (runs inside the detached
+ * worker process, never in the live agent).
+ *
+ *  1. SOURCE = the session's recall store (session.db), conversation rows only
+ *     (user + assistant text), secret-sanitized + client-redacted (lens-db.ts)
+ *  2. incremental: rows newer than the per-session high-water mark;
+ *     backfill: the whole session from row 0
+ *  3. page IN ORDER in windows of ~25% of the model's context; MAP each window
+ *  4. extract ANGLES + CAPABILITIES (shipped | root-caused), verbatim quotes;
+ *     plans/speculation and billing angles dropped
+ *  5. DETERMINISTIC grounding check against the rows — unverifiable items dropped
+ *  6. REDUCE/merge across windows; grounding check again
+ *  7. HN gap check (fail-open), optional recording, client-redact the entry,
+ *     APPEND to <project>/content-profile.md (or a scratch file); advance HWM
+ */
+import { type QuoteIndex, type RawAngle, type RawCapability } from './lens-quotes.js';
+import { type FinalAngle, type FinalCapability } from './lens-profile.js';
+export interface LensRunOptions {
+    sessionId: string;
+    transcriptPath?: string;
+    cwd?: string;
+    /** incremental (default, per compaction) = rows after the HWM; backfill = whole session. */
+    mode?: 'incremental' | 'backfill';
+    /** Cap on windows processed this run (incremental default OSBORN_LENS_MAX_WINDOWS || 2). */
+    maxWindows?: number;
+    /** Override the starting row (exclusive). */
+    startAfterRowId?: number;
+    /** Write here (overwrite) instead of appending to content-profile.md. Never the profile/HWM file; forces no HWM update. */
+    outPath?: string;
+    /** Ignored (always false) when outPath is set. */
+    updateHwm?: boolean;
+    /** Called after each window (worker refreshes its lock). */
+    onWindow?: () => void;
+    /** Harness-only hook to tamper with candidates before the final grounding check. */
+    mutateCandidates?: (c: Candidates) => void;
+    log?: (msg: string) => void;
+}
+export interface WindowStat {
+    rows: number;
+    chars: number;
+    estTokens: number;
+    firstRowId: number;
+    lastRowId: number;
+}
+export interface LensRunReport {
+    status: 'no-key' | 'no-db' | 'model-unknown' | 'no-input' | 'nothing-survived' | 'written';
+    mode: 'incremental' | 'backfill';
+    projectDir: string | null;
+    dbPath: string | null;
+    model?: {
+        id: string;
+        contextLength: number;
+        promptPerM: number;
+        completionPerM: number;
+        verified: boolean;
+    };
+    windowTokens: number;
+    rowsRead: number;
+    records: number;
+    sanitizerDropped: number;
+    windowsTotal: number;
+    windowsProcessed: number;
+    windows: WindowStat[];
+    modelCalls: number;
+    modelFailures: number;
+    refused: number;
+    costUsd: number;
+    mapDropped: {
+        angles: number;
+        capabilities: number;
+    };
+    dropped: {
+        angles: number;
+        capabilities: number;
+    };
+    notDone: number;
+    billingDropped: number;
+    kept: {
+        angles: number;
+        capabilities: number;
+    };
+    hwmBefore: number;
+    hwmAfter: number;
+    redactTerms: number;
+    denylistLoaded: boolean;
+    recording: string | null;
+    angles: FinalAngle[];
+    capabilities: FinalCapability[];
+    outPath?: string;
+    entry?: string;
+}
+export type Candidates = {
+    angles: RawAngle[];
+    capabilities: RawCapability[];
+};
+/** Parse + done-vs-planned gate + billing exclusion (angles: title/why; capabilities: name/did/proof). */
+export declare function readCandidates(raw: string, maxA: number, maxC: number, r: Pick<LensRunReport, 'billingDropped' | 'notDone'>): Candidates;
+/** Grounding check; afterwards drops any item whose VERIFIED quote text is billing talk (counted in billingDropped). */
+export declare function ground(c: Candidates, idx: QuoteIndex, r: Pick<LensRunReport, 'billingDropped'>): {
+    c: Candidates;
+    dA: number;
+    dC: number;
+};
+/** Run the pipeline once. Throws only on unexpected errors (worker catches). */
+export declare function runCompactionLens(opts: LensRunOptions): Promise<LensRunReport>;

package/dist/content/compaction-lens.js

@@ -0,0 +1,222 @@
+/**
+ * compaction-lens.ts — the content-lens PIPELINE (runs inside the detached
+ * worker process, never in the live agent).
+ *
+ *  1. SOURCE = the session's recall store (session.db), conversation rows only
+ *     (user + assistant text), secret-sanitized + client-redacted (lens-db.ts)
+ *  2. incremental: rows newer than the per-session high-water mark;
+ *     backfill: the whole session from row 0
+ *  3. page IN ORDER in windows of ~25% of the model's context; MAP each window
+ *  4. extract ANGLES + CAPABILITIES (shipped | root-caused), verbatim quotes;
+ *     plans/speculation and billing angles dropped
+ *  5. DETERMINISTIC grounding check against the rows — unverifiable items dropped
+ *  6. REDUCE/merge across windows; grounding check again
+ *  7. HN gap check (fail-open), optional recording, client-redact the entry,
+ *     APPEND to <project>/content-profile.md (or a scratch file); advance HWM
+ */
+import { dirname } from 'node:path';
+import { loadConversationRows, packWindows, resolveSessionDb } from './lens-db.js';
+import { buildRecordIndex, explainQuote, parseJsonObject, readAngles, readCapabilities, splitByEvidence, verifyItems, } from './lens-quotes.js';
+import { Budget, chat, getModelInfo, mapPrompt, reducePrompt, windowTokensFor } from './lens-model.js';
+import { DENYLIST_FILE, hasBillingQuote, isBillingAngle, isBillingCapability, loadClientRedactor } from './lens-redact.js';
+import { gapCheck } from './lens-hn.js';
+import { alignRecording, findSessionRecording } from './lens-audio.js';
+import { appendProfile, formatEntry, writeScratch } from './lens-profile.js';
+import { findTranscriptBySessionId, isProjectDir, readHwm, refuseOutPath, resolveProjectDir, writeHwm } from './lens-paths.js';
+const LIMITS = {
+    map: { a: 4, c: 8 },
+    incremental: { a: 3, c: 6 },
+    backfill: { a: 8, c: 20 },
+};
+const envInt = (k, d) => {
+    const n = Math.floor(Number(process.env[k]));
+    return Number.isFinite(n) && n > 0 ? n : d;
+};
+/** Parse + done-vs-planned gate + billing exclusion (angles: title/why; capabilities: name/did/proof). */
+export function readCandidates(raw, maxA, maxC, r) {
+    const o = parseJsonObject(raw);
+    const angles = readAngles(o?.angles, maxA);
+    const { done, notDone } = splitByEvidence(readCapabilities(o?.capabilities, maxC));
+    r.notDone += notDone;
+    const keptA = angles.filter(a => !isBillingAngle(a));
+    const keptC = done.filter(c => !isBillingCapability(c));
+    r.billingDropped += angles.length - keptA.length + done.length - keptC.length;
+    return { angles: keptA, capabilities: keptC };
+}
+/** Grounding check; afterwards drops any item whose VERIFIED quote text is billing talk (counted in billingDropped). */
+export function ground(c, idx, r) {
+    const a = verifyItems(c.angles, idx);
+    const k = verifyItems(c.capabilities, idx);
+    const angles = a.kept.filter(x => !hasBillingQuote(x));
+    const capabilities = k.kept.filter(x => !hasBillingQuote(x));
+    r.billingDropped += a.kept.length - angles.length + k.kept.length - capabilities.length;
+    return { c: { angles, capabilities }, dA: a.dropped, dC: k.dropped };
+}
+/** Run the pipeline once. Throws only on unexpected errors (worker catches). */
+export async function runCompactionLens(opts) {
+    const log = opts.log ?? (() => { });
+    const mode = opts.mode ?? 'incremental';
+    let projectDir = resolveProjectDir(opts.transcriptPath, opts.cwd);
+    if (!projectDir) {
+        const t = findTranscriptBySessionId(opts.sessionId);
+        if (t && isProjectDir(dirname(t)))
+            projectDir = dirname(t);
+    }
+    const r = {
+        status: 'no-input', mode, projectDir, dbPath: null, windowTokens: 0, rowsRead: 0, records: 0, sanitizerDropped: 0,
+        windowsTotal: 0, windowsProcessed: 0, windows: [], modelCalls: 0, modelFailures: 0, refused: 0, costUsd: 0,
+        mapDropped: { angles: 0, capabilities: 0 }, dropped: { angles: 0, capabilities: 0 }, notDone: 0, billingDropped: 0,
+        kept: { angles: 0, capabilities: 0 }, hwmBefore: 0, hwmAfter: 0, redactTerms: 0, denylistLoaded: false, recording: null, angles: [], capabilities: [],
+    };
+    if (opts.outPath !== undefined) {
+        const why = refuseOutPath(opts.outPath, projectDir);
+        if (why)
+            throw new Error(`content lens: ${why}`);
+    }
+    const apiKey = process.env.OPENROUTER_API_KEY;
+    if (!apiKey)
+        return { ...r, status: 'no-key' };
+    r.dbPath = resolveSessionDb(opts.sessionId, projectDir, opts.cwd);
+    if (!r.dbPath)
+        return { ...r, status: 'no-db' };
+    if (!projectDir)
+        projectDir = r.projectDir = dirname(dirname(dirname(r.dbPath)));
+    const info = await getModelInfo(apiKey);
+    if (!info)
+        return { ...r, status: 'model-unknown' };
+    r.model = { id: info.id, contextLength: info.contextLength, promptPerM: info.promptPerTok * 1e6, completionPerM: info.completionPerTok * 1e6, verified: info.verified };
+    r.windowTokens = windowTokensFor(info);
+    r.hwmBefore = r.hwmAfter = readHwm(projectDir, opts.sessionId);
+    const start = opts.startAfterRowId ?? (mode === 'backfill' ? 0 : r.hwmBefore);
+    const redactor = loadClientRedactor(projectDir);
+    r.redactTerms = redactor.terms;
+    r.denylistLoaded = !!redactor.source;
+    if (!redactor.source)
+        log(`WARNING: no client denylist loaded (${DENYLIST_FILE} in project dir or OSBORN_LENS_DENYLIST) — shape-based redaction only`);
+    const load = loadConversationRows(r.dbPath, start, redactor.redact);
+    r.rowsRead = load.stats.rowsRead;
+    r.records = load.records.length;
+    r.sanitizerDropped = load.stats.dropped;
+    // A review copy (outPath) NEVER moves the HWM, whatever updateHwm says.
+    const updateHwm = opts.outPath !== undefined ? false : (opts.updateHwm ?? true);
+    const bumpHwm = (rowId) => {
+        if (!updateHwm || rowId <= r.hwmAfter)
+            return;
+        writeHwm(projectDir, opts.sessionId, rowId);
+        r.hwmAfter = rowId;
+    };
+    const all = packWindows(load.records, r.windowTokens);
+    r.windowsTotal = all.length;
+    const maxWindows = opts.maxWindows ?? (mode === 'backfill' ? all.length : envInt('OSBORN_LENS_MAX_WINDOWS', 2));
+    const todo = all.slice(0, maxWindows);
+    log(`db ${r.dbPath}: rows>${start} read=${r.rowsRead} kept=${r.records} → ${all.length} window(s) of ≤${r.windowTokens} tok; running ${todo.length}`);
+    if (!todo.length) {
+        bumpHwm(load.maxRowId); // everything new was sanitizer-dropped noise
+        return r;
+    }
+    // MAP — in order; stop at the first failure/refusal so the HWM never skips a window.
+    const budget = new Budget(info);
+    const pool = { angles: [], capabilities: [] };
+    const seen = [];
+    for (const w of todo) {
+        r.windows.push({ rows: w.records.length, chars: w.chars, estTokens: w.estTokens, firstRowId: w.firstRowId, lastRowId: w.lastRowId });
+        let res;
+        try {
+            res = await chat(budget, mapPrompt(w.text, w.index + 1, all.length, LIMITS.map.a, LIMITS.map.c), apiKey);
+        }
+        catch (err) {
+            log(`map ${w.index + 1}/${all.length} failed: ${err instanceof Error ? err.message : err}`);
+            break;
+        }
+        if (!res) {
+            log(`map ${w.index + 1}/${all.length}: budget cap reached ($${budget.spentUsd.toFixed(4)}/${budget.maxCostUsd}, ${budget.calls}/${budget.maxCalls} calls) — stopping`);
+            break;
+        }
+        seen.push(...w.records);
+        r.windowsProcessed++;
+        const parsed = readCandidates(res.content, LIMITS.map.a, LIMITS.map.c, r);
+        if (parsed.angles.length + parsed.capabilities.length === 0) {
+            log(`map ${w.index + 1}: no items parsed (provider=${res.provider}); reply head: ${res.content.slice(0, 300)}`);
+        }
+        const widx = buildRecordIndex(w.records);
+        if (process.env.OSBORN_LENS_DEBUG) {
+            for (const it of [...parsed.angles, ...parsed.capabilities]) {
+                for (const q of it.quotes) {
+                    const why = explainQuote(q, widx);
+                    if (why !== 'ok')
+                        log(`  quote fail [${why}] @${q?.timestamp} #${q?.row}: ${String(q?.text).slice(0, 120)}`);
+                }
+            }
+        }
+        const g = ground(parsed, widx, r);
+        r.mapDropped.angles += g.dA;
+        r.mapDropped.capabilities += g.dC;
+        pool.angles.push(...g.c.angles);
+        pool.capabilities.push(...g.c.capabilities);
+        log(`map ${w.index + 1}/${all.length}: ${w.records.length} rows ~${w.estTokens} tok, ${res.promptTokens}+${res.completionTokens} tok finish=${res.finish} $${res.costUsd.toFixed(4)}; kept ${g.c.angles.length}A/${g.c.capabilities.length}C dropped ${g.dA}A/${g.dC}C`);
+        opts.onWindow?.();
+    }
+    r.modelCalls = budget.calls;
+    if (!r.windowsProcessed) {
+        r.modelFailures = budget.failures;
+        r.refused = budget.refused;
+        r.costUsd = budget.spentUsd;
+        return { ...r, status: 'nothing-survived' };
+    }
+    const lim = LIMITS[mode];
+    const idx = buildRecordIndex(seen);
+    // REDUCE — merge across windows (skipped when one window already fits the caps).
+    let cands = pool;
+    const needReduce = r.windowsProcessed > 1 || pool.angles.length > lim.a || pool.capabilities.length > lim.c;
+    if (needReduce && pool.angles.length + pool.capabilities.length > 0) {
+        try {
+            const res = await chat(budget, reducePrompt(JSON.stringify(pool), lim.a, lim.c), apiKey, 12_000);
+            const out = res ? readCandidates(res.content, lim.a, lim.c, r) : null;
+            if (out && out.angles.length + out.capabilities.length > 0)
+                cands = out;
+            else
+                log(res ? 'reduce returned nothing — using grounded pool' : 'reduce refused by budget — using grounded pool');
+        }
+        catch (err) {
+            log(`reduce failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    cands = { angles: cands.angles.slice(0, lim.a), capabilities: cands.capabilities.slice(0, lim.c) };
+    r.modelCalls = budget.calls;
+    r.modelFailures = budget.failures;
+    r.refused = budget.refused;
+    r.costUsd = budget.spentUsd;
+    opts.mutateCandidates?.(cands);
+    // Final deterministic grounding check (no model).
+    const fin = ground(cands, idx, r);
+    r.dropped = { angles: fin.dA, capabilities: fin.dC };
+    r.kept = { angles: fin.c.angles.length, capabilities: fin.c.capabilities.length };
+    log(`calls ${r.modelCalls} $${r.costUsd.toFixed(4)}; final kept ${r.kept.angles}A/${r.kept.capabilities}C, dropped ${fin.dA}A/${fin.dC}C, notDone ${r.notDone}, billing ${r.billingDropped}`);
+    const covered = r.windowsProcessed === all.length ? load.maxRowId : todo[r.windowsProcessed - 1].lastRowId;
+    if (r.kept.angles + r.kept.capabilities === 0) {
+        bumpHwm(covered);
+        return { ...r, status: 'nothing-survived' };
+    }
+    for (const a of fin.c.angles) {
+        r.angles.push({ title: a.title, why: a.why, quotes: a.quotes, gap: await gapCheck(a.queries) });
+    }
+    r.capabilities = fin.c.capabilities.map(c => ({
+        name: c.name, did: c.did, evidence: c.evidence, proof: c.proof, quotes: c.quotes,
+    }));
+    const rec = findSessionRecording(opts.sessionId, projectDir);
+    const align = rec ? alignRecording(rec, seen[0]?.timestamp) : null;
+    r.recording = align?.path ?? null;
+    const entry = formatEntry(r.angles, r.capabilities, {
+        sessionId: opts.sessionId, source: 'recall-db', mode, model: info.id, records: seen.length,
+        rowRange: [seen[0].id, seen[seen.length - 1].id], windows: r.windowsProcessed, windowsTotal: all.length,
+        modelCalls: r.modelCalls, costUsd: r.costUsd, notDone: r.notDone, billingDropped: r.billingDropped, recording: align,
+        noDenylist: !r.denylistLoaded,
+        dropped: { angles: r.mapDropped.angles + r.dropped.angles, capabilities: r.mapDropped.capabilities + r.dropped.capabilities },
+    });
+    r.entry = redactor.redact(entry); // client redaction again on everything written
+    r.outPath = opts.outPath ? writeScratch(opts.outPath, r.entry) : appendProfile(projectDir, r.entry);
+    bumpHwm(covered);
+    r.status = 'written';
+    log(`wrote ${r.outPath}; hwm ${r.hwmBefore}→${r.hwmAfter}`);
+    return r;
+}

package/dist/content/lens-audio.d.ts

@@ -0,0 +1,38 @@
+/**
+ * lens-audio.ts — OPTIONAL, pluggable session-recording lookup (no paid calls).
+ *
+ * LiveKit egress is not enabled today, so this is a convention-based local
+ * lookup. Checks, in order:
+ *   1. <projectDir>/recordings/<sessionId>.<media-ext>
+ *   2. $OSBORN_RECORDINGS_DIR/<sessionId>.<media-ext>
+ * An optional sidecar <sessionId>.json ({ "startedAt": ISO | epoch-ms | "started_at": ns })
+ * pins the recording start exactly; without it the start is approximated by the
+ * first transcript record's timestamp and offsets are marked approximate.
+ */
+export interface SessionRecording {
+    path: string;
+    /** Recording start (epoch ms) if known from a sidecar; else null. */
+    startedAtMs: number | null;
+}
+export interface RecordingAlignment {
+    path: string;
+    startIso: string;
+    approximate: boolean;
+    basis: string;
+}
+/** Pluggable lookup. Returns null when no recording exists (the normal case today). */
+export declare function findSessionRecording(sessionId: string, projectDir: string | null): SessionRecording | null;
+/** Choose the alignment origin: sidecar start (exact) or first transcript record (approximate). */
+export declare function alignRecording(rec: SessionRecording, firstRecordIso: string | undefined): RecordingAlignment | null;
+/**
+ * OPTIONAL input adapter for recordings. Every lens stage (period map, clip,
+ * library, formats) works on the transcript alone; when an adapter returns an
+ * alignment, row ranges additionally get clip offsets, otherwise they stay rows only.
+ */
+export interface AudioAdapter {
+    align(sessionId: string, projectDir: string | null, firstRecordIso: string | undefined): RecordingAlignment | null;
+}
+/** Default adapter: the local convention lookup above (null today — no egress). */
+export declare const localRecordingAdapter: AudioAdapter;
+/** Clip offset "H:MM:SS" of a quote relative to the recording start; null if before start. */
+export declare function clipOffset(quoteIso: string, startIso: string): string | null;