osborn 0.9.249 → 0.9.251

package/dist/content/lens-db.js

@@ -0,0 +1,170 @@
+/**
+ * lens-db.ts — the content lens's SOURCE: the per-session recall store
+ * (`session.db`, the same SQLite file `osborn-recall` queries), keyed by session ID.
+ *
+ *   <claudeDir>/projects/<slug>/osb/<sessionId>/session.db
+ *     content(id INTEGER PK, source TEXT, line_num, byte_offset, ts TEXT,
+ *             msg_type TEXT, model, git_branch, cwd, tool_name, blob BLOB)
+ *   blob = brotli-compressed full text (session-store.ts compress()).
+ *   id is append-only and chronological; source = 'main' | 'agent-<id8>'.
+ *
+ * CONVERSATION ONLY: msg_type IN ('user','assistant'); thinking / tool_use /
+ * tool_result rows are never read. Default source is the main thread only
+ * (sub-agent rows are the orchestrator's prompts + agent chatter, not the
+ * conversation); OSBORN_LENS_INCLUDE_SUBAGENTS=1 widens it.
+ *
+ * Every pulled row goes through the same sanitizer as before (drops harness
+ * wrappers like <session_tail>/[EMERGENCY STOP], unwraps [INTERRUPTED]/[CONTEXT]
+ * to the user's actual words) and then a second redaction pass in assistant
+ * mode ({assistant:true}, i.e. incl. the high-entropy fallback) for BOTH speakers,
+ * then the optional client/customer redactor (names, IDs, emails, billing amounts).
+ * Opened read-only; never writes to the store.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { brotliDecompressSync } from 'node:zlib';
+import Database from 'better-sqlite3';
+import { redactSecrets, sanitizeRecord } from './transcript-sanitizer.js';
+import { claudeDir, slugDir } from './lens-paths.js';
+import { stripInjected } from './lens-strip.js';
+const bump = (m, k) => (m[k] = (m[k] ?? 0) + 1);
+const SID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+export const CHARS_PER_TOKEN = 4;
+/** A single huge row (pasted logs etc.) is clipped in the VIEW only; verification uses full text. */
+const MAX_RECORD_VIEW_CHARS = 20_000;
+/**
+ * Resolve session.db for a session id: <projectDir>/osb/<sid>/session.db, then
+ * the cwd slug, then a scan of every project's osb dir (same layout as
+ * session-store.ts getStorePath / recall-cli listStores).
+ */
+export function resolveSessionDb(sessionId, projectDir, cwd) {
+    if (!sessionId || !SID_RE.test(sessionId))
+        return null;
+    const candidates = [];
+    if (projectDir)
+        candidates.push(join(projectDir, 'osb', sessionId, 'session.db'));
+    if (cwd)
+        candidates.push(join(slugDir(cwd), 'osb', sessionId, 'session.db'));
+    for (const p of candidates)
+        if (existsSync(p) && statSync(p).size > 0)
+            return p;
+    const root = join(claudeDir(), 'projects');
+    try {
+        for (const ent of readdirSync(root, { withFileTypes: true })) {
+            if (!ent.isDirectory())
+                continue;
+            const p = join(root, ent.name, 'osb', sessionId, 'session.db');
+            if (existsSync(p) && statSync(p).size > 0)
+                return p;
+        }
+    }
+    catch {
+        /* no projects dir */
+    }
+    return null;
+}
+export function includeSubagents() {
+    return ['1', 'true', 'yes', 'on'].includes((process.env.OSBORN_LENS_INCLUDE_SUBAGENTS ?? '').trim().toLowerCase());
+}
+/**
+ * Read conversation rows with id > afterRowId, in id order, sanitized.
+ * Throws if the DB can't be opened (caller logs + exits).
+ */
+export function loadConversationRows(dbPath, afterRowId = 0, clientRedact, throughRowId) {
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    try {
+        db.pragma('busy_timeout = 5000');
+        const where = includeSubagents() ? '' : `AND source = 'main'`;
+        const upper = Number.isFinite(throughRowId) ? `AND id <= ${Math.floor(throughRowId)}` : '';
+        const stmt = db.prepare(`SELECT id, ts, msg_type, blob FROM content
+       WHERE id > ? ${upper} AND msg_type IN ('user', 'assistant') ${where}
+       ORDER BY id`);
+        const out = { dbPath, records: [], maxRowId: afterRowId, stats: { rowsRead: 0, dropped: 0, unwrapped: 0, chars: 0, stripped: {} } };
+        for (const row of stmt.iterate(afterRowId)) {
+            out.stats.rowsRead++;
+            if (row.id > out.maxRowId)
+                out.maxRowId = row.id;
+            let raw;
+            try {
+                raw = brotliDecompressSync(row.blob).toString('utf-8');
+            }
+            catch {
+                out.stats.dropped++;
+                continue;
+            }
+            const speaker = row.msg_type === 'assistant' ? 'assistant' : 'user';
+            // Injected / summarised context (session tails, recall blocks, reminders,
+            // compaction summaries, silent control rows…) goes first — lens-strip.ts.
+            const st = stripInjected(raw, speaker);
+            for (const k of st.kinds)
+                bump(out.stats.stripped, k);
+            if (st.text === null) {
+                out.stats.dropped++;
+                continue;
+            }
+            const lead = st.text.replace(/^\[time:[^\]]*\]\s*/, '').trimStart();
+            const { record, action } = sanitizeRecord({ text: st.text, timestamp: row.ts ?? '', speaker });
+            if (!record || !record.timestamp) {
+                bump(out.stats.stripped, `harness-other:${(lead.match(/^(\[[A-Za-z][^\]\n]{0,40}\]|<[a-z-]+>)/)?.[1] ?? 'empty/other')}`);
+                out.stats.dropped++;
+                continue;
+            }
+            if (action === 'unwrap') {
+                out.stats.unwrapped++;
+                bump(out.stats.stripped, lead.startsWith('[CONTEXT]') ? 'context-unwrapped' : 'interrupted-unwrapped');
+            }
+            // Second pass: assistant-mode redaction for every row, both speakers; then
+            // client/customer redaction (lens-redact.ts) — all before any model sees it.
+            let text = redactSecrets(record.text, { assistant: true });
+            if (clientRedact)
+                text = clientRedact(text);
+            if (!text.trim()) {
+                out.stats.dropped++;
+                continue;
+            }
+            out.records.push({ id: row.id, timestamp: record.timestamp, speaker, text });
+            out.stats.chars += text.length;
+        }
+        return out;
+    }
+    finally {
+        db.close();
+    }
+}
+/** Record as the model sees it: header with row id, exact timestamp, speaker. */
+export function recordView(r) {
+    const t = r.text.length > MAX_RECORD_VIEW_CHARS ? r.text.slice(0, MAX_RECORD_VIEW_CHARS) + ' …[clipped]' : r.text;
+    return `[#${r.id} | ${r.timestamp} | ${r.speaker}]\n${t}`;
+}
+export const estimateTokens = (chars) => Math.ceil(chars / CHARS_PER_TOKEN);
+/** Pack records IN ORDER into windows of ≤ windowTokens (estimated at CHARS_PER_TOKEN). */
+export function packWindows(records, windowTokens) {
+    const maxChars = Math.max(10_000, windowTokens * CHARS_PER_TOKEN);
+    const windows = [];
+    let cur = { views: [], recs: [], chars: 0 };
+    const flush = () => {
+        if (!cur.recs.length)
+            return;
+        const text = cur.views.join('\n\n');
+        windows.push({
+            index: windows.length,
+            text,
+            records: cur.recs,
+            firstRowId: cur.recs[0].id,
+            lastRowId: cur.recs[cur.recs.length - 1].id,
+            chars: text.length,
+            estTokens: estimateTokens(text.length),
+        });
+        cur = { views: [], recs: [], chars: 0 };
+    };
+    for (const r of records) {
+        const v = recordView(r);
+        if (cur.chars + v.length + 2 > maxChars && cur.recs.length)
+            flush();
+        cur.views.push(v);
+        cur.recs.push(r);
+        cur.chars += v.length + 2;
+    }
+    flush();
+    return windows;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * lens-hn.ts — GAP CHECK via the keyless Hacker News Algolia API.
+ * Fail-open: any network error → { reachable: false }, never throws.
+ */
+export interface HnStory {
+    title: string;
+    points: number;
+    num_comments: number;
+    url: string;
+}
+export interface GapEvidence {
+    queries: string[];
+    reachable: boolean;
+    stories: HnStory[];
+    note: string;
+}
+/** Deterministic demand-vs-supply note from the HN results (no model). */
+export declare function gapNote(stories: HnStory[], totalHits: number): string;
+export declare function gapCheck(queries: string[]): Promise<GapEvidence>;

package/dist/content/lens-hn.js

@@ -0,0 +1,69 @@
+/**
+ * lens-hn.ts — GAP CHECK via the keyless Hacker News Algolia API.
+ * Fail-open: any network error → { reachable: false }, never throws.
+ */
+const HN_SEARCH = 'https://hn.algolia.com/api/v1/search';
+const HN_TIMEOUT_MS = 10_000;
+async function searchHn(query) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), HN_TIMEOUT_MS);
+    try {
+        const url = `${HN_SEARCH}?query=${encodeURIComponent(query)}&tags=story&hitsPerPage=10`;
+        const resp = await fetch(url, { signal: ctrl.signal });
+        if (!resp.ok)
+            throw new Error(`HN HTTP ${resp.status}`);
+        const data = await resp.json();
+        const hits = Array.isArray(data?.hits) ? data.hits : [];
+        return hits
+            .filter(h => h?.objectID && typeof h?.title === 'string')
+            .map(h => ({
+            title: String(h.title),
+            points: Number(h.points) || 0,
+            num_comments: Number(h.num_comments) || 0,
+            url: `https://news.ycombinator.com/item?id=${encodeURIComponent(String(h.objectID))}`,
+        }));
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Deterministic demand-vs-supply note from the HN results (no model). */
+export function gapNote(stories, totalHits) {
+    if (totalHits === 0)
+        return 'Supply: no matching HN stories found — open lane, but demand is unproven.';
+    const top = stories[0];
+    const demand = top.points >= 200 || top.num_comments >= 100 ? 'high' : top.points >= 30 ? 'moderate' : 'low';
+    const supply = totalHits >= 15 ? 'crowded' : totalHits >= 5 ? 'some coverage' : 'thin';
+    return (`Demand ${demand} (top related story ${top.points} pts / ${top.num_comments} comments); ` +
+        `supply ${supply} (${totalHits} related stories across queries). ` +
+        (supply !== 'crowded' && demand !== 'low'
+            ? 'Likely gap: interest exists, few first-hand build write-ups.'
+            : supply === 'crowded'
+                ? 'Needs a distinct first-hand angle to stand out.'
+                : 'Niche: post for credibility rather than reach.'));
+}
+export async function gapCheck(queries) {
+    const qs = queries.map(q => q.trim()).filter(Boolean).slice(0, 2);
+    if (qs.length === 0)
+        return { queries: [], reachable: false, stories: [], note: 'No search queries emitted.' };
+    const seen = new Map();
+    let ok = false;
+    for (const q of qs) {
+        try {
+            for (const s of await searchHn(q))
+                if (!seen.has(s.url))
+                    seen.set(s.url, s);
+            ok = true;
+        }
+        catch {
+            /* fail-open */
+        }
+    }
+    if (!ok)
+        return { queries: qs, reachable: false, stories: [], note: 'HN unreachable — gap not checked.' };
+    // Keep Algolia relevance order (sorting by points surfaces loosely-related hits);
+    // the demand note reads the strongest of the top-3 relevant stories.
+    const all = [...seen.values()];
+    const top = all.slice(0, 3);
+    return { queries: qs, reachable: true, stories: top, note: gapNote([...top].sort((a, b) => b.points - a.points), all.length) };
+}

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

@@ -0,0 +1,67 @@
+/**
+ * lens-ingest.ts — sends a published library page to the cloud content library
+ * as a private DRAFT through the Supabase RPC `public.content_ingest(p_token,
+ * p_payload)` (migration 007). This is the module behind the ingest seam in
+ * lens-library.ts.
+ *
+ * - Auth: the machine's per-user OSBORN_SYNC_TOKEN is the credential. The RPC
+ *   resolves the owner server-side. PostgREST is called with the PUBLIC anon key
+ *   (shipped by the frontend by design). A service key is never used: any key
+ *   whose JWT role isn't "anon" is refused.
+ * - Fail-open: never throws. Times out after ~10s. Logs outcomes only (never the
+ *   token, URL query, headers or body).
+ * - Opt-out: OSBORN_CONTENT_INGEST=0. OSBORN_CONTENT_LENS=0 disables it too.
+ * - Never sends a status. The server forces draft anyway.
+ * - Idempotent: content_hash = sha256(sessionId, startRowId, page markdown), so
+ *   re-runs upsert instead of duplicating.
+ */
+export declare const INGEST_MAX_BYTES: number;
+export declare const INGEST_TIMEOUT_MS = 10000;
+export type IngestStatus = 'ok' | 'error' | 'skipped' | 'oversize';
+export interface IngestState {
+    status: IngestStatus;
+    /** 'disabled' | 'no-token' | 'no-url' | 'no-key' | 'http-500' | 'timeout' | 'network' | 'oversize' ... */
+    reason?: string;
+    contentHash: string;
+    httpStatus?: number;
+    id?: string;
+    at: string;
+}
+/** The minimal page shape ingest needs (fresh pages and manifest retries both map to it). */
+export interface IngestPage {
+    sessionId: string;
+    startRowId: number;
+    endRowId: number;
+    index: number;
+    closedBy: number | 'compaction' | null;
+    file: string;
+    /** The page exactly as written to disk (already redacted by the library step). */
+    markdown: string;
+}
+export interface IngestOptions {
+    /** Re-redaction applied to every text field before sending (client redactor + redactSecrets). */
+    scrub?: (s: string) => string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    log?: (m: string) => void;
+}
+export declare function isIngestEnabled(): boolean;
+/** True only for keys safe to send from a machine: anon JWTs or sb_publishable_ keys. */
+export declare function isAnonKey(key: string): boolean;
+export type IngestConfig = {
+    ok: true;
+    url: string;
+    anonKey: string;
+    token: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function resolveIngestConfig(): IngestConfig;
+export declare function contentHashFor(p: Pick<IngestPage, 'sessionId' | 'startRowId' | 'markdown'>): string;
+/** Map a page to the content_ingest payload. Never includes status/published_at/owner. */
+export declare function buildIngestPayload(p: IngestPage, scrub?: (s: string) => string): Record<string, unknown>;
+/** POST one page to content_ingest. Never throws; returns the state to record in the manifest. */
+export declare function ingestPage(p: IngestPage, o?: IngestOptions): Promise<IngestState>;
+/** Does this manifest entry still need an ingest attempt? */
+export declare function needsIngest(state: IngestState | undefined, currentHash: string): boolean;

package/dist/content/lens-ingest.js

@@ -0,0 +1,155 @@
+/**
+ * lens-ingest.ts — sends a published library page to the cloud content library
+ * as a private DRAFT through the Supabase RPC `public.content_ingest(p_token,
+ * p_payload)` (migration 007). This is the module behind the ingest seam in
+ * lens-library.ts.
+ *
+ * - Auth: the machine's per-user OSBORN_SYNC_TOKEN is the credential. The RPC
+ *   resolves the owner server-side. PostgREST is called with the PUBLIC anon key
+ *   (shipped by the frontend by design). A service key is never used: any key
+ *   whose JWT role isn't "anon" is refused.
+ * - Fail-open: never throws. Times out after ~10s. Logs outcomes only (never the
+ *   token, URL query, headers or body).
+ * - Opt-out: OSBORN_CONTENT_INGEST=0. OSBORN_CONTENT_LENS=0 disables it too.
+ * - Never sends a status. The server forces draft anyway.
+ * - Idempotent: content_hash = sha256(sessionId, startRowId, page markdown), so
+ *   re-runs upsert instead of duplicating.
+ */
+import { createHash } from 'node:crypto';
+import { isContentLensEnabled } from './lens-launch.js';
+import { parsePage } from './lens-library-index.js';
+/** Public project values the frontend ships (NEXT_PUBLIC_*). The anon key is public by design. */
+const DEFAULT_SUPABASE_URL = 'https://frzbawsadhmmltokvexj.supabase.co';
+const DEFAULT_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImZyemJhd3NhZGhtbWx0b2t2ZXhqIiwicm9sZSI6ImFub24iLCJpYXQiOjE2Nzg3MzgxMjcsImV4cCI6MTk5NDMxNDEyN30.KAHO-apaXL3G7mBTZ17r8GN0vXoOZIL7d_HzKr7hJjc';
+export const INGEST_MAX_BYTES = 250 * 1024;
+export const INGEST_TIMEOUT_MS = 10_000;
+const OFF = ['0', 'off', 'false', 'no'];
+export function isIngestEnabled() {
+    if (!isContentLensEnabled())
+        return false;
+    return !OFF.includes((process.env.OSBORN_CONTENT_INGEST ?? '').trim().toLowerCase());
+}
+/** True only for keys safe to send from a machine: anon JWTs or sb_publishable_ keys. */
+export function isAnonKey(key) {
+    if (key.startsWith('sb_publishable_'))
+        return true;
+    const parts = key.split('.');
+    if (parts.length !== 3)
+        return false;
+    try {
+        return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'))?.role === 'anon';
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveIngestConfig() {
+    if (!isIngestEnabled())
+        return { ok: false, reason: 'disabled' };
+    const token = (process.env.OSBORN_SYNC_TOKEN ?? '').trim();
+    if (!token)
+        return { ok: false, reason: 'no-token' };
+    const e = process.env;
+    const url = (e.OSBORN_SUPABASE_URL ?? e.SUPABASE_URL ?? e.NEXT_PUBLIC_SUPABASE_URL ?? DEFAULT_SUPABASE_URL).trim().replace(/\/+$/, '');
+    if (!/^https:\/\/[^/?#]+$/.test(url))
+        return { ok: false, reason: 'no-url' };
+    const anonKey = [e.OSBORN_SUPABASE_ANON_KEY, e.SUPABASE_ANON_KEY, e.NEXT_PUBLIC_SUPABASE_ANON_KEY, DEFAULT_ANON_KEY]
+        .map(k => (k ?? '').trim())
+        .find(k => k && isAnonKey(k));
+    if (!anonKey)
+        return { ok: false, reason: 'no-key' };
+    return { ok: true, url, anonKey, token };
+}
+export function contentHashFor(p) {
+    return createHash('sha256').update(`${p.sessionId}\n${p.startRowId}\n${p.markdown}`).digest('hex');
+}
+const clip = (s, n) => (s.length > n ? s.slice(0, n - 1).trimEnd() + '…' : s);
+const SESSION_ID_RE = /^[a-zA-Z0-9._-]{1,128}$/;
+/** Map a page to the content_ingest payload. Never includes status/published_at/owner. */
+export function buildIngestPayload(p, scrub = s => s) {
+    const summary = parsePage(p.file, p.markdown);
+    const nn = String(p.index).padStart(2, '0');
+    const goal = summary.goal && summary.goal !== '(no verified goal)' ? summary.goal : '';
+    const title = clip(scrub(goal ? `Period ${nn}: ${goal}` : `Period ${nn}`), 200);
+    const hook = clip(scrub(summary.topItem ?? goal ?? ''), 280);
+    return {
+        type: 'text_post',
+        title,
+        hook: hook || null,
+        body: scrub(p.markdown),
+        source_session_id: SESSION_ID_RE.test(p.sessionId) ? p.sessionId : null,
+        source_anchors: { start_row_id: p.startRowId, end_row_id: p.endRowId, closed_by: p.closedBy, period_index: p.index, file: p.file },
+        source_kind: 'library_page',
+        content_hash: contentHashFor(p),
+    };
+}
+/** POST one page to content_ingest. Never throws; returns the state to record in the manifest. */
+export async function ingestPage(p, o = {}) {
+    const log = o.log ?? (() => { });
+    const at = new Date().toISOString();
+    let contentHash = '';
+    const tag = `library: ingest period ${p.index} (#${p.startRowId})`;
+    try {
+        contentHash = contentHashFor(p);
+        const cfg = resolveIngestConfig();
+        if (!cfg.ok)
+            return { status: 'skipped', reason: cfg.reason, contentHash, at };
+        const payload = buildIngestPayload(p, o.scrub);
+        const body = JSON.stringify({ p_token: cfg.token, p_payload: payload });
+        const bytes = Buffer.byteLength(body, 'utf-8');
+        if (bytes > INGEST_MAX_BYTES) {
+            log(`${tag} → skipped: payload ${bytes} bytes > ${INGEST_MAX_BYTES}`);
+            return { status: 'oversize', reason: 'oversize', contentHash, at };
+        }
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), o.timeoutMs ?? INGEST_TIMEOUT_MS);
+        try {
+            const res = await (o.fetchImpl ?? fetch)(`${cfg.url}/rest/v1/rpc/content_ingest`, {
+                method: 'POST',
+                // This project's PostgREST db_schema lists `storage` first, so the profile headers are required to hit public.content_ingest.
+                headers: { apikey: cfg.anonKey, Authorization: `Bearer ${cfg.anonKey}`, 'Content-Type': 'application/json', 'Content-Profile': 'public', 'Accept-Profile': 'public' },
+                body,
+                signal: ctl.signal,
+            });
+            const text = await res.text().catch(() => '');
+            if (!res.ok) {
+                // Only the sanitized PostgREST code (e.g. 28000) and hint are logged, never the message or body.
+                let code = '';
+                let hint = '';
+                try {
+                    const j = JSON.parse(text);
+                    code = String(j?.code ?? '').replace(/[^A-Za-z0-9]/g, '').slice(0, 8);
+                    hint = String(j?.hint ?? '').replace(/[^A-Za-z0-9 ._-]/g, '').replace(/\s+/g, ' ').trim().slice(0, 80);
+                }
+                catch { /* not JSON */ }
+                log(`${tag} → failed: HTTP ${res.status}${code ? ` code=${code}` : ''}${hint ? ` hint="${hint}"` : ''} (will retry next run)`);
+                return { status: 'error', reason: `http-${res.status}`, httpStatus: res.status, contentHash, at };
+            }
+            let id;
+            try {
+                const v = JSON.parse(text);
+                if (typeof v === 'string' && /^[0-9a-f-]{36}$/i.test(v))
+                    id = v;
+            }
+            catch { /* ignore */ }
+            log(`${tag} → ok: draft saved (HTTP ${res.status})`);
+            return { status: 'ok', httpStatus: res.status, ...(id ? { id } : {}), contentHash, at };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch (e) {
+        const reason = e?.name === 'AbortError' ? 'timeout' : 'network';
+        log(`${tag} → failed: ${reason} (will retry next run)`);
+        return { status: 'error', reason, contentHash, at };
+    }
+}
+/** Does this manifest entry still need an ingest attempt? */
+export function needsIngest(state, currentHash) {
+    if (!state)
+        return true;
+    if (state.contentHash !== currentHash)
+        return true;
+    return state.status !== 'ok' && state.status !== 'oversize';
+}

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

@@ -0,0 +1,46 @@
+/**
+ * lens-launch.ts — HOOK-SIDE launcher for the compaction content lens.
+ *
+ * Called from the PostCompact hook. It only: takes the per-project lock, writes
+ * a tiny 0600 temp JSON payload (session id + transcript_path + cwd — nothing
+ * else), and spawns a DETACHED Node process running compaction-lens-worker.
+ * No awaits, no heavy imports (node: builtins only), never throws.
+ */
+export interface LensLaunchPayload {
+    sessionId: string;
+    transcriptPath?: string;
+    cwd?: string;
+}
+export type LensLaunchResult = {
+    status: 'disabled';
+} | {
+    status: 'no-key';
+} | {
+    status: 'locked';
+    projectDir: string;
+} | {
+    status: 'unlockable';
+    projectDir: string | null;
+} | {
+    status: 'no-worker';
+} | {
+    status: 'spawned';
+    pid?: number;
+    projectDir: string | null;
+    worker: string;
+} | {
+    status: 'error';
+    error: string;
+};
+/** ON by default; kill switch: OSBORN_CONTENT_LENS=0 | off | false | no. */
+export declare function isContentLensEnabled(): boolean;
+/**
+ * Worker entry + node args. From dist → dist/content/compaction-lens-worker.js.
+ * From a tsx/src dev run → the .ts sibling, loaded through tsx's ESM hook.
+ */
+export declare function resolveWorkerCommand(): {
+    args: string[];
+    worker: string;
+} | null;
+/** Fire-and-forget. Returns synchronously; the worker is never awaited. */
+export declare function launchCompactionLens(payload: LensLaunchPayload): LensLaunchResult;

package/dist/content/lens-launch.js

@@ -0,0 +1,111 @@
+/**
+ * lens-launch.ts — HOOK-SIDE launcher for the compaction content lens.
+ *
+ * Called from the PostCompact hook. It only: takes the per-project lock, writes
+ * a tiny 0600 temp JSON payload (session id + transcript_path + cwd — nothing
+ * else), and spawns a DETACHED Node process running compaction-lens-worker.
+ * No awaits, no heavy imports (node: builtins only), never throws.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { LOCK_FILE, acquireLock, findTranscriptBySessionId, releaseLock, resolveProjectDir } from './lens-paths.js';
+/** ON by default; kill switch: OSBORN_CONTENT_LENS=0 | off | false | no. */
+export function isContentLensEnabled() {
+    const v = (process.env.OSBORN_CONTENT_LENS ?? '').trim().toLowerCase();
+    return !['0', 'off', 'false', 'no'].includes(v);
+}
+/**
+ * Worker entry + node args. From dist → dist/content/compaction-lens-worker.js.
+ * From a tsx/src dev run → the .ts sibling, loaded through tsx's ESM hook.
+ */
+export function resolveWorkerCommand() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const js = join(here, 'compaction-lens-worker.js');
+    if (existsSync(js))
+        return { args: [js], worker: js };
+    const ts = join(here, 'compaction-lens-worker.ts');
+    if (existsSync(ts)) {
+        try {
+            const tsxEsm = createRequire(import.meta.url).resolve('tsx/esm');
+            return { args: ['--import', pathToFileURL(tsxEsm).href, ts], worker: ts };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+let warnedSpawn = false;
+/** Fire-and-forget. Returns synchronously; the worker is never awaited. */
+export function launchCompactionLens(payload) {
+    let projectDir = null;
+    let lockHeld = false;
+    try {
+        if (!isContentLensEnabled())
+            return { status: 'disabled' };
+        // OpenRouter is the only model path; without a key the worker can do nothing.
+        if (!(process.env.OPENROUTER_API_KEY || '').trim())
+            return { status: 'no-key' };
+        const cmd = resolveWorkerCommand();
+        if (!cmd)
+            return { status: 'no-worker' };
+        projectDir = resolveProjectDir(payload.transcriptPath, payload.cwd);
+        if (!projectDir) {
+            const t = findTranscriptBySessionId(payload.sessionId);
+            projectDir = t ? dirname(t) : null;
+        }
+        if (!projectDir)
+            return { status: 'unlockable', projectDir: null };
+        // mkdir then lock; if the dir can't be created or locked, skip the launch entirely
+        // (an unlocked worker could race another one on the profile / high-water mark).
+        try {
+            mkdirSync(projectDir, { recursive: true });
+        }
+        catch {
+            return { status: 'unlockable', projectDir };
+        }
+        if (!acquireLock(projectDir)) {
+            return existsSync(join(projectDir, LOCK_FILE)) ? { status: 'locked', projectDir } : { status: 'unlockable', projectDir };
+        }
+        lockHeld = true;
+        const argFile = join(tmpdir(), `osborn-lens-${process.pid}-${randomBytes(6).toString('hex')}.json`);
+        writeFileSync(argFile, JSON.stringify({
+            sessionId: payload.sessionId,
+            transcriptPath: payload.transcriptPath,
+            cwd: payload.cwd,
+            lockDir: lockHeld ? projectDir : null,
+        }), { mode: 0o600, flag: 'wx' });
+        {
+            const child = spawn(process.execPath, [...cmd.args, argFile], {
+                detached: true,
+                stdio: 'ignore',
+                env: { ...process.env },
+            });
+            child.on('error', err => {
+                if (lockHeld && projectDir)
+                    releaseLock(projectDir);
+                if (!warnedSpawn) {
+                    warnedSpawn = true;
+                    console.error('⚠️ content-lens: worker spawn failed:', err?.message);
+                }
+            });
+            child.unref();
+            return { status: 'spawned', pid: child.pid, projectDir, worker: cmd.worker };
+        }
+    }
+    catch (err) {
+        if (lockHeld && projectDir)
+            releaseLock(projectDir);
+        const msg = err instanceof Error ? err.message : String(err);
+        if (!warnedSpawn) {
+            warnedSpawn = true;
+            console.error('⚠️ content-lens: launch failed:', msg);
+        }
+        return { status: 'error', error: msg };
+    }
+}

package/dist/content/lens-library-index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * lens-library-index.ts — rebuild a session library's INDEX.md from the period
+ * pages on disk. The pages are the source of truth (renderPeriodMd format), so
+ * pages written by the manual backfill are listed alongside auto-written ones,
+ * and a rebuild is idempotent: same pages in → same INDEX out.
+ */
+export declare const INDEX_FILE = "INDEX.md";
+export declare const PAGE_RE: RegExp;
+export interface PageStory {
+    title: string;
+    rows: string;
+    anchor: string | null;
+}
+export interface PageSummary {
+    file: string;
+    index: number;
+    rows: string;
+    from: string;
+    to: string;
+    goal: string;
+    topItem: string | null;
+    stories: PageStory[];
+    costUsd: number;
+}
+/** Parse one period page (renderPeriodMd output). Pure. */
+export declare function parsePage(file: string, md: string): PageSummary;
+/** Render INDEX.md. Pure. */
+export declare function renderIndex(sessionLabel: string, pages: PageSummary[]): string;
+/** Rebuild <dir>/INDEX.md from every period page in <dir>. `scrub` = final redaction pass. Returns the path. */
+export declare function rebuildIndex(dir: string, sessionLabel: string, scrub?: (s: string) => string): string;