osborn 0.9.249 → 0.9.251

package/dist/content/lens-model.js

@@ -0,0 +1,193 @@
+/**
+ * lens-model.ts — OpenRouter model calls for the content lens (map-reduce).
+ * OpenRouter ONLY — never the Claude subscription / Anthropic SDK.
+ *
+ * Model: big-window, env-overridable (OSBORN_CONTENT_LENS_MODEL). Default
+ * minimax/minimax-m3 — verified 2026-10-05 via GET /api/v1/models:
+ * context_length 1,048,576, $0.30/M prompt, $1.20/M completion (top provider
+ * 524,288 ctx). Window = 25% of the model's context_length, looked up live so an
+ * override is sized correctly; the constants below are only the fallback.
+ *
+ * Credit is limited, so every run has a HARD cap on calls AND dollars
+ * (OSBORN_LENS_MAX_CALLS / OSBORN_LENS_MAX_COST_USD). A call is refused up front
+ * if its worst-case cost would cross the cap; actual cost comes from OpenRouter's
+ * usage accounting when present.
+ */
+const OPENROUTER = 'https://openrouter.ai/api/v1';
+export const DEFAULT_MODEL = 'minimax/minimax-m3';
+const DEFAULT_MODEL_INFO = { contextLength: 1_048_576, promptPerTok: 0.3e-6, completionPerTok: 1.2e-6 };
+export const WINDOW_FRACTION = 0.25;
+const CALL_TIMEOUT_MS = 6 * 60_000;
+const META_TIMEOUT_MS = 15_000;
+const envNum = (k, d) => {
+    const n = Number(process.env[k]);
+    return Number.isFinite(n) && n > 0 ? n : d;
+};
+export const lensModel = () => (process.env.OSBORN_CONTENT_LENS_MODEL || '').trim() || DEFAULT_MODEL;
+/** Live context length + price. Null for an unknown overridden model (can't enforce the cost cap). */
+export async function getModelInfo(apiKey, id = lensModel()) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), META_TIMEOUT_MS);
+    try {
+        const resp = await fetch(`${OPENROUTER}/models`, { signal: ctrl.signal, headers: { Authorization: `Bearer ${apiKey}` } });
+        if (resp.ok) {
+            const data = await resp.json();
+            const m = (data?.data ?? []).find((x) => x?.id === id);
+            const p = Number(m?.pricing?.prompt);
+            const c = Number(m?.pricing?.completion);
+            if (m && m.context_length > 0 && p >= 0 && c >= 0) {
+                return { id, contextLength: m.context_length, promptPerTok: p, completionPerTok: c, verified: true };
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return id === DEFAULT_MODEL ? { id, ...DEFAULT_MODEL_INFO, verified: false } : null;
+}
+export const windowTokensFor = (info) => Math.floor(info.contextLength * WINDOW_FRACTION);
+export class Budget {
+    info;
+    calls = 0;
+    failures = 0;
+    spentUsd = 0;
+    refused = 0;
+    maxCalls;
+    maxCostUsd;
+    /** caps override the env/default caps (e.g. the period map's own $0.50 hard cap). */
+    constructor(info, caps = {}) {
+        this.info = info;
+        this.maxCalls = caps.maxCalls ?? envNum('OSBORN_LENS_MAX_CALLS', 14);
+        this.maxCostUsd = caps.maxCostUsd ?? envNum('OSBORN_LENS_MAX_COST_USD', 1.25);
+    }
+    estimate(promptTokens, maxOut) {
+        return promptTokens * this.info.promptPerTok + maxOut * this.info.completionPerTok;
+    }
+    /** Reserve one call if both caps allow its worst case. */
+    take(promptTokens, maxOut) {
+        if (this.calls >= this.maxCalls || this.spentUsd + this.estimate(promptTokens, maxOut) > this.maxCostUsd) {
+            this.refused++;
+            return false;
+        }
+        this.calls++;
+        return true;
+    }
+}
+const SYSTEM = 'You read engineering work transcripts between a person (user) and their AI coding assistant (assistant). ' +
+    'You never invent facts. You quote ONLY verbatim text that appears in the transcript. Reply with one JSON object only.';
+const QUOTE_RULES = 'QUOTES: every item needs 1-3 quotes. Each quote = {"text": exact verbatim substring (12-300 chars) copied character-for-character ' +
+    'from ONE record, "timestamp": that record\'s exact timestamp from its [#row | timestamp | speaker] header, "row": that record\'s row number ' +
+    '(digits only), "speaker": "user"|"assistant"}. Do not paraphrase, merge, or fix typos inside quotes. ' +
+    'ONE contiguous span: no ellipses ("..."/"…"), no skipped words, no joined sentences — if it is too long, quote a shorter span. ' +
+    'Never quote secrets, keys, tokens, emails, or private personal details.';
+function itemRules(maxA, maxC) {
+    return (`ANGLES (0-${maxA}): things a builder could post publicly — {"title", "why" (one line: why postable), "quotes", ` +
+        '"queries": 1-2 short Hacker News search queries (2-5 words) to check if this is already covered}. ' +
+        'NEVER produce items about personal invoicing, retainers, refunds owed, overdue payments, contract/rate negotiation, or money ' +
+        'owed to or by the person — not content material. Billing as ENGINEERING is fine (Stripe/payment webhooks or API integrations, ' +
+        'billing APIs, payment gateways, ads-API spend/budgets/spend caps/pricing, token pricing, rate limits, wallet holds).\n' +
+        'Client/customer details are already masked as tags like [client], [founder], [brand], [ad account], [amount]: keep the tags, ' +
+        'never guess or reintroduce real names, client companies, IDs or amounts. Refer to client companies as "[client]" or ' +
+        '"a marketing-platform client". Frame client work as the technical lesson.\n' +
+        `CAPABILITIES (0-${maxC}): what this person DEMONSTRABLY did. Two kinds count, tag each with "evidence":\n` +
+        '  - "shipped": built / deployed / merged / verified working — the quotes show it was DONE (tests passed, deployed, confirmed working).\n' +
+        '  - "root-caused": debugging where the root cause was actually FOUND or PROVEN (e.g. "found the missing x-forwarded-host header ' +
+        'causing WS 1006"), even if no fix shipped yet.\n' +
+        '  EXCLUDE: plans, proposals, TODOs, "we could/should/will", ideas, unresolved speculation, things only discussed. ' +
+        'If the quotes only show intent or a hypothesis, leave it out.\n' +
+        '  Each = {"name": SPECIFIC capability (what + where + the non-obvious detail), e.g. "debugged Meta IG ad-authorization failing ' +
+        'silently unless page is business-owned" — NOT generic labels like "debugging", "api-integration", "node-development"; ' +
+        '"evidence": "shipped"|"root-caused", "did": one line on what was done/found, "proof": one line naming which quote shows it was ' +
+        'done/found, "quotes"}.\nReturn empty arrays if nothing qualifies.');
+}
+/**
+ * Transcript FIRST, instructions AFTER: measured on minimax-m3 with a ~257k-token
+ * window, instructions-before-transcript returned {"angles":[],"capabilities":[]}
+ * (the task gets lost in a long context); the query belongs at the end.
+ */
+export function mapPrompt(window, part, total, maxA, maxC) {
+    return [
+        `Below is transcript window ${part}/${total} of one long engineering work session (chronological, conversation only). ` +
+            'Read all of it; your task follows after the transcript.',
+        '<transcript>',
+        window,
+        '</transcript>',
+        `TASK: extract candidate angles and capabilities from the transcript window above (${part}/${total}). ` +
+            'A window this long normally contains several real accomplishments and root-caused bugs — scan the whole window, ' +
+            'beginning to end, before answering. Return empty arrays only if there truly is nothing done/proven.',
+        itemRules(maxA, maxC),
+        QUOTE_RULES,
+        'Output ONLY: {"angles": [...], "capabilities": [...]}',
+    ].join('\n\n');
+}
+export function reducePrompt(candidatesJson, maxA, maxC) {
+    return [
+        'Below are candidate angles and capabilities extracted window-by-window from ONE work session (quotes already verified). ' +
+            `Merge duplicates (same work = one item, keep the most specific name), keep the strongest: at most ${maxA} angles and ${maxC} ` +
+            'capabilities. Re-check every capability: drop it unless its quotes show it was shipped/verified or a root cause was proven.',
+        itemRules(maxA, maxC),
+        'Keep each item\'s quotes EXACTLY as given (copy text, timestamp and row unchanged); you may drop quotes, never edit them.',
+        'Output: {"angles": [...], "capabilities": [...]}',
+        '<candidates>',
+        candidatesJson,
+        '</candidates>',
+    ].join('\n\n');
+}
+/** One chat call. Returns null when the budget refuses; throws on HTTP/timeout errors. */
+export async function chat(budget, user, apiKey, maxOut = 16_000) {
+    const estPrompt = Math.ceil((SYSTEM.length + user.length) / 4);
+    if (!budget.take(estPrompt, maxOut))
+        return null;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), CALL_TIMEOUT_MS);
+    try {
+        const resp = await fetch(`${OPENROUTER}/chat/completions`, {
+            method: 'POST',
+            signal: ctrl.signal,
+            headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                model: budget.info.id,
+                temperature: 0.1,
+                max_tokens: maxOut,
+                // Reasoning OFF: measured on minimax-m3, effort:'low' still burned ~5k hidden
+                // tokens of a 6k cap (finish=length, truncated JSON); enabled:false → 0, finish=stop.
+                reasoning: { enabled: false },
+                usage: { include: true },
+                // Cheapest provider that fits the prompt (OpenRouter skips too-small contexts).
+                provider: { sort: 'price' },
+                messages: [
+                    { role: 'system', content: SYSTEM },
+                    { role: 'user', content: user },
+                ],
+            }),
+        });
+        if (!resp.ok)
+            throw new Error(`OpenRouter HTTP ${resp.status}`);
+        const data = await resp.json();
+        const pt = Number(data?.usage?.prompt_tokens) || estPrompt;
+        const ct = Number(data?.usage?.completion_tokens) || 0;
+        const reported = Number(data?.usage?.cost);
+        const cost = Number.isFinite(reported) && reported > 0 ? reported : pt * budget.info.promptPerTok + ct * budget.info.completionPerTok;
+        budget.spentUsd += cost;
+        return {
+            content: String(data?.choices?.[0]?.message?.content ?? ''),
+            finish: String(data?.choices?.[0]?.finish_reason ?? ''),
+            provider: String(data?.provider ?? ''),
+            promptTokens: pt,
+            completionTokens: ct,
+            costUsd: cost,
+        };
+    }
+    catch (err) {
+        budget.failures++;
+        // A failed/timed-out call may still bill: charge the worst case so the cap stays hard.
+        budget.spentUsd += budget.estimate(estPrompt, maxOut);
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * lens-paths.ts — LIGHT path + lock helpers shared by the hook-side launcher
+ * and the background worker. node: builtins only (safe to import in the live agent).
+ */
+export declare const PROFILE_FILE = "content-profile.md";
+export declare const LOCK_FILE = ".content-lens.lock";
+export declare const LOG_FILE = "content-lens.log";
+export declare const LOCK_TTL_MS: number;
+export declare function claudeDir(): string;
+/** Same slug rule as session-access.ts projectPathToSlug(). */
+export declare function slugDir(cwd: string): string;
+/** True if `dir` is a project dir: strictly under <claudeDir>/projects/ and not a subagents dir. */
+export declare function isProjectDir(dir: string): boolean;
+/**
+ * The transcript's project dir (guarded), else the cwd slug fallback, else null.
+ * A sub-agent transcript (…/<sid>/subagents/x.jsonl) never qualifies.
+ */
+export declare function resolveProjectDir(transcriptPath?: string, cwd?: string): string | null;
+/** Locate `<claudeDir>/projects/<any>/<sessionId>.jsonl` (project-scoped). */
+export declare function findTranscriptBySessionId(sessionId: string, preferDir?: string | null): string | null;
+/**
+ * Acquire the per-project lock. Returns false if a FRESH (<15 min) lock exists.
+ * Stale locks are replaced. Exclusive-create avoids a check-then-write race.
+ */
+export declare function acquireLock(projectDir: string, now?: number): boolean;
+export declare function releaseLock(projectDir: string): void;
+/** Refresh the lock's mtime so a long (backfill) run isn't treated as stale. */
+export declare function touchLock(projectDir: string): void;
+export declare const sessionIdFromPath: (p: string) => string;
+export declare const HWM_FILE = ".content-lens-hwm.json";
+export interface HwmEntry {
+    lastRowId: number;
+    lastTs?: string;
+    updatedAt: string;
+}
+export declare function readHwm(projectDir: string | null, sessionId: string): number;
+/**
+ * A review --out path must never be the profile or the HWM file (of this or any
+ * project; symlinks resolved). Returns a reason string when refused, else null.
+ */
+export declare function refuseOutPath(outPath: string | undefined, projectDir?: string | null): string | null;
+/** Monotonic: never moves the mark backwards. Atomic write via rename. */
+export declare function writeHwm(projectDir: string, sessionId: string, lastRowId: number, lastTs?: string): void;

package/dist/content/lens-paths.js

@@ -0,0 +1,166 @@
+/**
+ * lens-paths.ts — LIGHT path + lock helpers shared by the hook-side launcher
+ * and the background worker. node: builtins only (safe to import in the live agent).
+ */
+import { closeSync, existsSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, utimesSync, writeFileSync, writeSync, } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+export const PROFILE_FILE = 'content-profile.md';
+export const LOCK_FILE = '.content-lens.lock';
+export const LOG_FILE = 'content-lens.log';
+export const LOCK_TTL_MS = 15 * 60_000;
+export function claudeDir() {
+    return process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+}
+/** Same slug rule as session-access.ts projectPathToSlug(). */
+export function slugDir(cwd) {
+    return join(claudeDir(), 'projects', cwd.replace(/\//g, '-'));
+}
+/** True if `dir` is a project dir: strictly under <claudeDir>/projects/ and not a subagents dir. */
+export function isProjectDir(dir) {
+    const root = resolve(claudeDir(), 'projects') + sep;
+    const d = resolve(dir);
+    if (!d.startsWith(root))
+        return false;
+    return !d.slice(root.length).split(sep).includes('subagents');
+}
+/**
+ * The transcript's project dir (guarded), else the cwd slug fallback, else null.
+ * A sub-agent transcript (…/<sid>/subagents/x.jsonl) never qualifies.
+ */
+export function resolveProjectDir(transcriptPath, cwd) {
+    if (transcriptPath && transcriptPath.endsWith('.jsonl')) {
+        const d = dirname(resolve(transcriptPath));
+        if (isProjectDir(d))
+            return d;
+    }
+    if (cwd)
+        return slugDir(cwd);
+    return null;
+}
+const SID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+/** Locate `<claudeDir>/projects/<any>/<sessionId>.jsonl` (project-scoped). */
+export function findTranscriptBySessionId(sessionId, preferDir) {
+    if (!sessionId || !SID_RE.test(sessionId))
+        return null;
+    const name = `${sessionId}.jsonl`;
+    if (preferDir && existsSync(join(preferDir, name)))
+        return join(preferDir, name);
+    const root = join(claudeDir(), 'projects');
+    try {
+        for (const ent of readdirSync(root, { withFileTypes: true })) {
+            if (!ent.isDirectory())
+                continue;
+            const p = join(root, ent.name, name);
+            if (existsSync(p))
+                return p;
+        }
+    }
+    catch {
+        /* no projects dir */
+    }
+    return null;
+}
+/**
+ * Acquire the per-project lock. Returns false if a FRESH (<15 min) lock exists.
+ * Stale locks are replaced. Exclusive-create avoids a check-then-write race.
+ */
+export function acquireLock(projectDir, now = Date.now()) {
+    const p = join(projectDir, LOCK_FILE);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(p, 'wx', 0o600);
+            writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date(now).toISOString() }));
+            closeSync(fd);
+            return true;
+        }
+        catch (e) {
+            if (e?.code !== 'EEXIST')
+                return false;
+            try {
+                if (now - statSync(p).mtimeMs < LOCK_TTL_MS)
+                    return false;
+                rmSync(p, { force: true }); // stale → replace once
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    return false;
+}
+export function releaseLock(projectDir) {
+    try {
+        rmSync(join(projectDir, LOCK_FILE), { force: true });
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Refresh the lock's mtime so a long (backfill) run isn't treated as stale. */
+export function touchLock(projectDir) {
+    try {
+        const now = new Date();
+        utimesSync(join(projectDir, LOCK_FILE), now, now);
+    }
+    catch {
+        /* ignore */
+    }
+}
+export const sessionIdFromPath = (p) => basename(p, '.jsonl');
+// ── Per-session high-water mark (last session.db content.id the profile covers) ──
+export const HWM_FILE = '.content-lens-hwm.json';
+function readHwmFile(projectDir) {
+    try {
+        const o = JSON.parse(readFileSync(join(projectDir, HWM_FILE), 'utf-8'));
+        return o && typeof o === 'object' && !Array.isArray(o) ? o : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function readHwm(projectDir, sessionId) {
+    if (!projectDir)
+        return 0;
+    const n = Number(readHwmFile(projectDir)[sessionId]?.lastRowId);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+}
+/**
+ * A review --out path must never be the profile or the HWM file (of this or any
+ * project; symlinks resolved). Returns a reason string when refused, else null.
+ */
+export function refuseOutPath(outPath, projectDir) {
+    if (typeof outPath !== 'string' || !outPath.trim() || outPath.startsWith('--'))
+        return '--out requires a file path';
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return resolve(p);
+        }
+    };
+    const abs = resolve(outPath);
+    const targets = new Set([abs, real(abs)]);
+    for (const name of [PROFILE_FILE, HWM_FILE]) {
+        if ([...targets].some(t => basename(t) === name))
+            return `--out must not be ${name}`;
+        if (projectDir) {
+            const p = join(projectDir, name);
+            if (targets.has(resolve(p)) || targets.has(real(p)))
+                return `--out must not be ${name}`;
+        }
+    }
+    return null;
+}
+/** Monotonic: never moves the mark backwards. Atomic write via rename. */
+export function writeHwm(projectDir, sessionId, lastRowId, lastTs) {
+    const all = readHwmFile(projectDir);
+    if ((all[sessionId]?.lastRowId ?? 0) >= lastRowId)
+        return;
+    all[sessionId] = { lastRowId, lastTs, updatedAt: new Date().toISOString() };
+    const p = join(projectDir, HWM_FILE);
+    const tmp = `${p}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(all, null, 2), { mode: 0o600 });
+    renameSync(tmp, p);
+}

package/dist/content/lens-period-block.d.ts

@@ -0,0 +1,63 @@
+/**
+ * lens-period-block.ts — the PERIOD MAP's input: ONE raw, sequential block of
+ * conversation (no sweep of small windows, no summaries). Pure + deterministic.
+ *
+ * Default block = everything since the most recent compaction boundary of the
+ * session (the compaction trigger; boundaries from lens-period-boundaries'
+ * readCompactionBoundaries — the boundary row itself is kept, minus its stripped
+ * <session_tail> replay, because the user's words that followed the compaction
+ * live in it). Alternatively a time range (--since / --until).
+ *
+ * Cap = maxTokens (callers pass 25% of the model's live context length). When the
+ * block is larger, the MOST RECENT rows that fit are kept and the left-out
+ * stretch is reported.
+ *
+ * Records arrive already stripped of injected context (lens-strip.ts),
+ * sanitized and secret + client redacted (lens-db.ts loadConversationRows).
+ */
+import { type DbRecord } from './lens-db.js';
+export interface BlockOptions {
+    /** content.ids of compaction seams, ascending. */
+    boundaries: number[];
+    /** Explicit start row (inclusive); overrides the boundary default. */
+    fromRowId?: number;
+    /** Explicit end row (inclusive); only applies together with fromRowId. */
+    toRowId?: number;
+    /** Time range (ms epoch); when set, overrides the boundary default. */
+    sinceMs?: number;
+    untilMs?: number;
+    maxTokens: number;
+}
+export interface PeriodBlock {
+    records: DbRecord[];
+    text: string;
+    chars: number;
+    estTokens: number;
+    firstRowId: number;
+    lastRowId: number;
+    from: string;
+    to: string;
+    /** How the start was chosen. */
+    basis: string;
+    /** Rows in the selected period that did not fit the cap (oldest end), or null. */
+    leftOut: {
+        rows: number;
+        estTokens: number;
+        firstRowId: number;
+        lastRowId: number;
+        from: string;
+        to: string;
+    } | null;
+    /** Rows in the period before capping. */
+    periodRows: number;
+}
+/**
+ * Start row for the default block: the most recent compaction seam at or before
+ * the last loaded record (seams past the end of `records` are ignored), or null
+ * when there is none. The seam is returned however few rows follow it — there is
+ * no minimum-rows fallback to an earlier seam.
+ */
+export declare function lastBoundaryStart(records: DbRecord[], boundaries: number[]): number | null;
+/** "24h", "90m", "2d", or an ISO timestamp → ms epoch (relative to now). NaN when unparseable. */
+export declare function parseSince(v: string, now?: number): number;
+export declare function selectBlock(all: DbRecord[], o: BlockOptions): PeriodBlock | null;

package/dist/content/lens-period-block.js

@@ -0,0 +1,99 @@
+/**
+ * lens-period-block.ts — the PERIOD MAP's input: ONE raw, sequential block of
+ * conversation (no sweep of small windows, no summaries). Pure + deterministic.
+ *
+ * Default block = everything since the most recent compaction boundary of the
+ * session (the compaction trigger; boundaries from lens-period-boundaries'
+ * readCompactionBoundaries — the boundary row itself is kept, minus its stripped
+ * <session_tail> replay, because the user's words that followed the compaction
+ * live in it). Alternatively a time range (--since / --until).
+ *
+ * Cap = maxTokens (callers pass 25% of the model's live context length). When the
+ * block is larger, the MOST RECENT rows that fit are kept and the left-out
+ * stretch is reported.
+ *
+ * Records arrive already stripped of injected context (lens-strip.ts),
+ * sanitized and secret + client redacted (lens-db.ts loadConversationRows).
+ */
+import { estimateTokens, recordView } from './lens-db.js';
+/**
+ * Start row for the default block: the most recent compaction seam at or before
+ * the last loaded record (seams past the end of `records` are ignored), or null
+ * when there is none. The seam is returned however few rows follow it — there is
+ * no minimum-rows fallback to an earlier seam.
+ */
+export function lastBoundaryStart(records, boundaries) {
+    const lastId = records.length ? records[records.length - 1].id : 0;
+    const seams = boundaries.filter(b => b <= lastId).sort((a, b) => a - b);
+    return seams.length ? seams[seams.length - 1] : null;
+}
+/** "24h", "90m", "2d", or an ISO timestamp → ms epoch (relative to now). NaN when unparseable. */
+export function parseSince(v, now = Date.now()) {
+    const m = v.trim().match(/^(\d+(?:\.\d+)?)\s*(m|h|d)$/i);
+    if (m)
+        return now - Number(m[1]) * { m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2].toLowerCase()];
+    return Date.parse(v);
+}
+export function selectBlock(all, o) {
+    let period;
+    let basis;
+    if (o.sinceMs !== undefined || o.untilMs !== undefined) {
+        const lo = o.sinceMs ?? -Infinity;
+        const hi = o.untilMs ?? Infinity;
+        period = all.filter(r => {
+            const t = Date.parse(r.timestamp);
+            return t >= lo && t <= hi;
+        });
+        basis = `time range ${Number.isFinite(lo) ? new Date(lo).toISOString() : 'start'} → ${Number.isFinite(hi) ? new Date(hi).toISOString() : 'now'}`;
+    }
+    else if (o.fromRowId !== undefined) {
+        const to = o.toRowId ?? Infinity;
+        period = all.filter(r => r.id >= o.fromRowId && r.id <= to);
+        basis = Number.isFinite(to) ? `rows #${o.fromRowId}–#${to}` : `from row #${o.fromRowId}`;
+    }
+    else {
+        const start = lastBoundaryStart(all, o.boundaries);
+        period = start === null ? all : all.filter(r => r.id >= start);
+        basis = start === null ? 'whole session (no compaction boundary found)' : `since the last compaction boundary (row #${start})`;
+    }
+    if (!period.length)
+        return null;
+    const views = period.map(recordView);
+    const maxChars = o.maxTokens * 4;
+    // Walk back from the newest row; keep what fits.
+    let used = 0;
+    let firstKept = period.length;
+    for (let i = period.length - 1; i >= 0; i--) {
+        const c = views[i].length + 2;
+        if (used + c > maxChars && firstKept < period.length)
+            break;
+        used += c;
+        firstKept = i;
+    }
+    const kept = period.slice(firstKept);
+    const dropped = period.slice(0, firstKept);
+    const text = views.slice(firstKept).join('\n\n');
+    const droppedChars = views.slice(0, firstKept).reduce((s, v) => s + v.length + 2, 0);
+    return {
+        records: kept,
+        text,
+        chars: text.length,
+        estTokens: estimateTokens(text.length),
+        firstRowId: kept[0].id,
+        lastRowId: kept[kept.length - 1].id,
+        from: kept[0].timestamp,
+        to: kept[kept.length - 1].timestamp,
+        basis,
+        periodRows: period.length,
+        leftOut: dropped.length
+            ? {
+                rows: dropped.length,
+                estTokens: estimateTokens(droppedChars),
+                firstRowId: dropped[0].id,
+                lastRowId: dropped[dropped.length - 1].id,
+                from: dropped[0].timestamp,
+                to: dropped[dropped.length - 1].timestamp,
+            }
+            : null,
+    };
+}

package/dist/content/lens-period-boundaries.d.ts

@@ -0,0 +1,13 @@
+/**
+ * lens-period-boundaries.ts — compaction seams in the raw session.db store
+ * (read-only). Owned by the period map; the clipper re-exports it.
+ *
+ * A seam is a main-session user row that STARTS with compaction evidence: a
+ * <session_tail …> replay block, "Conversation compacted", or the
+ * "(This session is being) continued from a previous conversation" lead.
+ * A mention of those phrases later in a genuine utterance is not a seam.
+ */
+/** True when a user row's text begins with compaction evidence. Pure. */
+export declare function isCompactionBoundaryHead(text: string): boolean;
+/** content.ids of compaction seams, ascending. */
+export declare function readCompactionBoundaries(dbPath: string): number[];

package/dist/content/lens-period-boundaries.js

@@ -0,0 +1,40 @@
+/**
+ * lens-period-boundaries.ts — compaction seams in the raw session.db store
+ * (read-only). Owned by the period map; the clipper re-exports it.
+ *
+ * A seam is a main-session user row that STARTS with compaction evidence: a
+ * <session_tail …> replay block, "Conversation compacted", or the
+ * "(This session is being) continued from a previous conversation" lead.
+ * A mention of those phrases later in a genuine utterance is not a seam.
+ */
+import { brotliDecompressSync } from 'node:zlib';
+import Database from 'better-sqlite3';
+const BOUNDARY_HEAD_RE = /^\s*(?:\[time:[^\]]*\]\s*)?(?:<session_tail\b[^>]*>|Conversation compacted\b|(?:This session is being )?continued from a previous conversation)/i;
+/** True when a user row's text begins with compaction evidence. Pure. */
+export function isCompactionBoundaryHead(text) {
+    return BOUNDARY_HEAD_RE.test(text ?? '');
+}
+/** content.ids of compaction seams, ascending. */
+export function readCompactionBoundaries(dbPath) {
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    try {
+        db.pragma('busy_timeout = 5000');
+        const out = [];
+        const stmt = db.prepare(`SELECT id, blob FROM content WHERE msg_type = 'user' AND source = 'main' ORDER BY id`);
+        for (const r of stmt.iterate()) {
+            let head = '';
+            try {
+                head = brotliDecompressSync(r.blob).toString('utf-8').slice(0, 400);
+            }
+            catch {
+                continue;
+            }
+            if (isCompactionBoundaryHead(head))
+                out.push(r.id);
+        }
+        return out;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/content/lens-period-render.d.ts

@@ -0,0 +1,28 @@
+/**
+ * lens-period-render.ts — Markdown review output for a period-map run. Pure.
+ * high_leverage is rendered FIRST (strongest content candidates). The caller
+ * redacts the final string again (secrets + client) before writing it.
+ */
+import type { PeriodBlock } from './lens-period-block.js';
+import type { PeriodMap } from './lens-period.js';
+export interface PeriodRunReport {
+    sessionId: string;
+    model: string;
+    contextLength: number;
+    capTokens: number;
+    block: Omit<PeriodBlock, 'records' | 'text'> | null;
+    stripped: Record<string, number>;
+    rowsRead: number;
+    rowsKeptInSession: number;
+    map: PeriodMap | null;
+    calls: number;
+    promptTokens: number;
+    completionTokens: number;
+    costUsd: number;
+    capUsd: number;
+    finish: string;
+    provider: string;
+    audio: string;
+    errors: string[];
+}
+export declare function renderPeriodMd(r: PeriodRunReport): string;