osborn 0.9.251 → 0.9.252

package/dist/content/content-llm.js

@@ -0,0 +1,412 @@
+/**
+ * content-llm.ts — Stage A's flags, spend caps and its ONE model-call path.
+ * OpenRouter ONLY (OPENROUTER_API_KEY) — never the Claude subscription / Anthropic SDK.
+ *
+ * Flags:
+ *   OSBORN_CONTENT_PIPELINE  default ON; 0/off/false/no = off. OSBORN_CONTENT_LENS=0 also turns it off.
+ * Caps (a hit = status "capped", never an error):
+ *   OSBORN_CONTENT_PERIOD_USD  default 0.75 (cumulative per period, kept in the content manifest)
+ *   OSBORN_CONTENT_DAILY_USD   default 2.00 (UTC day, per MACHINE: $OSBORN_HOME or ~/.osborn/content-spend-ledger.json,
+ *                              locked read-modify-write so concurrent workers across projects share one cap)
+ *   OSBORN_CONTENT_MAX_PIECES  default 4 (1 highlight + up to 3 how-tos)
+ * Every call reserves its WORST case (prompt + max output) against both caps up
+ * front and writes it to the ledger before the fetch; it is reconciled to the
+ * actual cost after. A failed call is charged the worst case, and a hard exit
+ * mid-call leaves the worst case in the ledger, so the caps stay hard.
+ * All outbound prompt text goes through the caller's scrub() first.
+ */
+import { closeSync, fstatSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isContentLensEnabled } from './lens-launch.js';
+const OPENROUTER = 'https://openrouter.ai/api/v1';
+const OFF = ['0', 'off', 'false', 'no'];
+export const LEDGER_FILE = 'content-spend-ledger.json';
+export const DEFAULT_GEN_MODEL = 'minimax/minimax-m3';
+/** Pinned judge (proven in videos-test-3/vt3-render.ts): model + provider endpoint, no fallbacks. */
+export const CHECK_MODEL = 'deepseek/deepseek-chat';
+export const CHECK_PROVIDER = 'deepinfra/fp4';
+export const CHECK_PROVIDER_NAME = 'DeepInfra';
+const CALL_TIMEOUT_MS = 4 * 60_000;
+/** USD per token. Unknown models get a deliberately high price so the cap still binds. */
+const PRICES = {
+    'minimax/minimax-m3': { p: 0.3e-6, c: 1.2e-6 },
+    'deepseek/deepseek-chat': { p: 0.5e-6, c: 1.5e-6 },
+};
+const UNKNOWN_PRICE = { p: 3e-6, c: 15e-6 };
+export const priceFor = (model) => PRICES[model] ?? UNKNOWN_PRICE;
+/** OFF when OSBORN_CONTENT_PIPELINE, OSBORN_CONTENT_LENS or OSBORN_CONTENT_INGEST is 0/off/false/no: ingest off ⇒ no LLM spend at all. */
+export function isContentPipelineEnabled() {
+    if (!isContentLensEnabled())
+        return false;
+    const off = (k) => OFF.includes((process.env[k] ?? '').trim().toLowerCase());
+    return !off('OSBORN_CONTENT_PIPELINE') && !off('OSBORN_CONTENT_INGEST');
+}
+/**
+ * OSBORN_CONTENT_STRICT=1 restores hard blocks for the quality gates (structure,
+ * over-length tolerance, missing stake, audience). Default: those are advisory —
+ * the piece is still scripted and ingested as a draft with quality_flags attached.
+ * Dev-voice, truth-check, redaction, the outbound-query gate and the caps are hard either way.
+ */
+export function isContentStrict() {
+    return ['1', 'on', 'true', 'yes'].includes((process.env.OSBORN_CONTENT_STRICT ?? '').trim().toLowerCase());
+}
+const envNum = (k, d) => {
+    const raw = (process.env[k] ?? '').trim();
+    const n = Number(raw);
+    return raw !== '' && Number.isFinite(n) && n >= 0 ? n : d;
+};
+export function contentCaps() {
+    // Official names first; the plan's earlier names (…_PERIOD_CAP_USD / …_DAY_CAP_USD) are accepted as fallback aliases.
+    return {
+        periodUsd: envNum('OSBORN_CONTENT_PERIOD_USD', envNum('OSBORN_CONTENT_PERIOD_CAP_USD', 0.75)),
+        dailyUsd: envNum('OSBORN_CONTENT_DAILY_USD', envNum('OSBORN_CONTENT_DAY_CAP_USD', 2.0)),
+        maxPieces: Math.max(0, Math.floor(envNum('OSBORN_CONTENT_MAX_PIECES', 4))),
+    };
+}
+export const genModel = () => (process.env.OSBORN_CONTENT_MODEL || '').trim() || DEFAULT_GEN_MODEL;
+const today = (now = Date.now()) => new Date(now).toISOString().slice(0, 10);
+/** Machine-scoped ledger dir: $OSBORN_HOME, else ~/.osborn. The DAY cap is per machine, not per project. */
+export function ledgerDir() {
+    return (process.env.OSBORN_HOME || '').trim() || join(homedir(), '.osborn');
+}
+export const ledgerPath = () => join(ledgerDir(), LEDGER_FILE);
+function readLedgerAt(path) {
+    try {
+        const o = JSON.parse(readFileSync(path, 'utf-8'));
+        if (o && typeof o.days === 'object' && !Array.isArray(o.days))
+            return { days: o.days };
+    }
+    catch {
+        /* missing → empty */
+    }
+    return { days: {} };
+}
+/** The machine ledger (UTC day → USD). */
+export function readLedger() {
+    return readLedgerAt(ledgerPath());
+}
+/** Spend recorded (incl. open reservations) on this machine today, across every project. */
+export function daySpent(now = Date.now()) {
+    return Number(readLedger().days[today(now)]) || 0;
+}
+const LOCK_STALE_MS = 30_000;
+const LOCK_TRIES = 40;
+const LOCK_WAIT_MS = 50;
+const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const lockToken = () => `${process.pid}.${randomBytes(8).toString('hex')}`;
+/**
+ * Remove `path` if it is stale: rename it to a unique name (only ONE caller's
+ * rename can succeed), check the renamed file is the same stale file we judged
+ * (inode, mtime, content), and put it back with link() if a fresh one was
+ * swapped in (link fails rather than clobbers). True only to the caller that
+ * removed a stale file; any error = keep waiting.
+ */
+function removeIfStale(path) {
+    let seen;
+    try {
+        const fd = openSync(path, 'r');
+        try {
+            const st = fstatSync(fd);
+            if (Date.now() - st.mtimeMs <= LOCK_STALE_MS)
+                return false;
+            seen = { ino: st.ino, mtimeMs: st.mtimeMs, body: readFileSync(fd, 'utf-8') };
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return false; // vanished between calls
+    }
+    const claimed = `${path}.stale.${process.pid}.${randomBytes(6).toString('hex')}`;
+    try {
+        renameSync(path, claimed);
+    }
+    catch {
+        return false; // another caller claimed it first
+    }
+    let same = false;
+    try {
+        const st = statSync(claimed);
+        same = st.ino === seen.ino && st.mtimeMs === seen.mtimeMs && readFileSync(claimed, 'utf-8') === seen.body;
+    }
+    catch {
+        /* treat as not ours */
+    }
+    if (!same) {
+        try {
+            linkSync(claimed, path); // a live file was swapped in: restore it
+        }
+        catch {
+            /* a newer one already exists */
+        }
+    }
+    try {
+        unlinkSync(claimed);
+    }
+    catch {
+        /* already gone */
+    }
+    return same;
+}
+/**
+ * Claim a stale ledger lock. The judge-then-rename step runs under a short
+ * `<lock>.reap` guard so two waiters can never both act on one stale lock (or
+ * rename away the fresh lock the other just created). A guard left by a crash
+ * goes stale too and is removed the same way.
+ */
+function claimStaleLock(lock) {
+    const guard = `${lock}.reap`;
+    let g;
+    try {
+        g = openSync(guard, 'wx');
+    }
+    catch {
+        removeIfStale(guard);
+        return false;
+    }
+    const token = lockToken();
+    try {
+        writeSync(g, token);
+        return removeIfStale(lock);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        closeSync(g);
+        releaseLock(guard, token);
+    }
+}
+/** Release only a lock this holder owns (its token is still in the file). */
+function releaseLock(lock, token) {
+    try {
+        if (readFileSync(lock, 'utf-8') === token)
+            unlinkSync(lock);
+    }
+    catch {
+        /* already gone */
+    }
+}
+/**
+ * Atomic read-modify-write of the machine ledger under a short `wx` lock file
+ * holding a unique token (stale after 30s, claimed via rename so only one waiter
+ * can remove it). `fn` returns the new ledger, or null to leave it unchanged.
+ * Returns false when the lock could not be taken (callers decide fail-closed vs best-effort).
+ */
+function withLedger(fn, tries = LOCK_TRIES) {
+    const dir = ledgerDir();
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, LEDGER_FILE);
+    const lock = `${path}.lock`;
+    for (let i = 0; i < tries; i++) {
+        let fd;
+        try {
+            fd = openSync(lock, 'wx');
+        }
+        catch (e) {
+            if (e?.code !== 'EEXIST')
+                throw e;
+            if (claimStaleLock(lock))
+                continue; // we removed the stale lock: retry the wx create now
+            sleepSync(LOCK_WAIT_MS);
+            continue;
+        }
+        const token = lockToken();
+        try {
+            writeSync(fd, token);
+            const next = fn(readLedgerAt(path));
+            if (next) {
+                const cutoff = today(Date.now() - 14 * 86_400_000);
+                for (const k of Object.keys(next.days))
+                    if (k < cutoff)
+                        delete next.days[k];
+                const tmp = `${path}.${process.pid}.tmp`;
+                writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', 'utf-8');
+                renameSync(tmp, path);
+            }
+            return true;
+        }
+        finally {
+            closeSync(fd);
+            releaseLock(lock, token);
+        }
+    }
+    return false;
+}
+export class CapError extends Error {
+    cap;
+    needUsd;
+    constructor(cap, needUsd) {
+        super(`content cap reached (${cap})`);
+        this.cap = cap;
+        this.needUsd = needUsd;
+    }
+}
+/**
+ * Per-run spend guard: the per-period cap (cumulative, per project, in memory +
+ * content manifest), the per-day cap (per MACHINE, in the locked ledger) and an
+ * optional wall-clock deadline after which no new call starts.
+ */
+export class SpendGuard {
+    projectDir;
+    caps;
+    periodUsd;
+    deadline;
+    runUsd = 0;
+    calls = 0;
+    capHit = null;
+    constructor(
+    /** Kept for callers/logs; the day ledger is machine-scoped, not under this dir. */
+    projectDir, caps, 
+    /** Spend already recorded for this period by earlier runs. */
+    periodUsd = 0, 
+    /** Epoch ms after which reserve() refuses new calls (CapError 'time'). */
+    deadline = null) {
+        this.projectDir = projectDir;
+        this.caps = caps;
+        this.periodUsd = periodUsd;
+        this.deadline = deadline;
+    }
+    /**
+     * Reserve a worst-case spend of `usd`: throws CapError if it would cross a cap
+     * (or the deadline passed); otherwise writes it to the machine ledger BEFORE the
+     * call, so a hard exit mid-call still counts it. Fails closed if the ledger lock
+     * cannot be taken.
+     */
+    reserve(usd) {
+        if (this.deadline !== null && Date.now() >= this.deadline)
+            throw this.hit('time', usd);
+        if (this.periodUsd + usd > this.caps.periodUsd)
+            throw this.hit('period', usd);
+        const day = today();
+        let over = false;
+        let locked;
+        try {
+            locked = withLedger(l => {
+                const cur = Number(l.days[day]) || 0;
+                if (cur + usd > this.caps.dailyUsd) {
+                    over = true;
+                    return null;
+                }
+                l.days[day] = Number((cur + usd).toFixed(6));
+                return l;
+            });
+        }
+        catch {
+            locked = false;
+        }
+        if (over || !locked)
+            throw this.hit('day', usd);
+        return { day, usd, inLedger: true, settled: false };
+    }
+    hit(cap, usd) {
+        this.capHit = cap;
+        return new CapError(cap, usd);
+    }
+    /** Reconcile a reservation to the actual cost (once). The in-memory totals always move; the ledger is best-effort. */
+    settle(r, actualUsd) {
+        if (r.settled)
+            return;
+        r.settled = true;
+        const usd = actualUsd > 0 ? actualUsd : 0;
+        this.runUsd += usd;
+        this.periodUsd += usd;
+        if (!r.inLedger)
+            return;
+        const delta = usd - r.usd;
+        if (delta === 0)
+            return;
+        try {
+            // Long wait for the lock; if still held, write anyway — losing a reconcile would under-count (actual > worst).
+            const apply = (l) => {
+                l.days[r.day] = Math.max(0, Number(((Number(l.days[r.day]) || 0) + delta).toFixed(6)));
+                return l;
+            };
+            if (!withLedger(apply, LOCK_TRIES * 4) && delta > 0) {
+                const path = ledgerPath();
+                const tmp = `${path}.${process.pid}.tmp`;
+                writeFileSync(tmp, JSON.stringify(apply(readLedgerAt(path)), null, 2) + '\n', 'utf-8');
+                renameSync(tmp, path);
+            }
+        }
+        catch {
+            /* ledger write failure never blocks; the in-memory guard still holds */
+        }
+    }
+}
+/** Lenient JSON extraction: strips fences, takes the outermost {...} or [...]. Null when unparseable. */
+export function parseJsonLoose(s) {
+    const t = String(s ?? '').replace(/^\s*```(?:json)?\s*/i, '').replace(/```\s*$/i, '').trim();
+    for (const [o, c] of [['{', '}'], ['[', ']']]) {
+        const a = t.indexOf(o);
+        const b = t.lastIndexOf(c);
+        if (a >= 0 && b > a) {
+            try {
+                return JSON.parse(t.slice(a, b + 1));
+            }
+            catch {
+                /* try the other shape */
+            }
+        }
+    }
+    return null;
+}
+/** One chat call → JSON. Throws CapError on a cap, Error on HTTP/timeout/provider mismatch. */
+export async function llmJson(o, call) {
+    const model = call.model ?? genModel();
+    const system = o.scrub(call.system);
+    const user = o.scrub(call.user);
+    const price = priceFor(model);
+    const estPrompt = Math.ceil((system.length + user.length) / 3.5);
+    const worst = estPrompt * price.p + call.maxOut * price.c;
+    const res = o.guard.reserve(worst);
+    o.guard.calls++;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), CALL_TIMEOUT_MS);
+    try {
+        const body = {
+            model,
+            temperature: call.temperature ?? 0.2,
+            max_tokens: call.maxOut,
+            usage: { include: true },
+            messages: [
+                { role: 'system', content: system },
+                { role: 'user', content: user },
+            ],
+            provider: call.pin ? { order: [call.pin.endpoint], allow_fallbacks: false } : { sort: 'price' },
+        };
+        if (!call.pin)
+            body.reasoning = { enabled: false };
+        const resp = await (o.fetchImpl ?? fetch)(`${OPENROUTER}/chat/completions`, {
+            method: 'POST',
+            signal: ctrl.signal,
+            headers: { Authorization: `Bearer ${o.apiKey}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        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 * price.p + ct * price.c;
+        o.guard.settle(res, cost);
+        const provider = String(data?.provider ?? '');
+        if (call.pin && provider !== call.pin.name)
+            throw new Error(`${call.what}: served by ${provider || '?'}, expected pinned ${call.pin.name}`);
+        const content = String(data?.choices?.[0]?.message?.content ?? '');
+        return { content, json: parseJsonLoose(content), costUsd: cost, provider, model, finish: String(data?.choices?.[0]?.finish_reason ?? '') };
+    }
+    catch (e) {
+        if (e instanceof CapError)
+            throw e;
+        o.guard.settle(res, worst);
+        throw e?.name === 'AbortError' ? new Error(`${call.what}: timeout`) : e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/content/content-manifest.d.ts

@@ -0,0 +1,115 @@
+/**
+ * content-manifest.ts — Stage A per-period / per-piece state in
+ *   <library dir>/.content-manifest.json
+ * mirroring lens-library.ts's .library-manifest.json (same dir, keyed on the
+ * period's opening row id).
+ *
+ * Idempotency rules (content-run.ts):
+ *   - period "done"  → skipped, no model call, no spend.
+ *   - piece "ready"   → checks passed; only the ingest is (re)tried, no model call.
+ *   - piece "ingested" / "blocked" → terminal. Blocked is NEVER auto-fixed or retried.
+ *   - piece "error" / "capped" → regenerated next run (research + truth-check caches still apply).
+ *   - the period's plan (topics, research refs, briefs) is stored once and reused.
+ * Never throws on read (missing / unreadable → empty).
+ */
+import type { IngestState } from './lens-ingest.js';
+export declare const CONTENT_MANIFEST_FILE = ".content-manifest.json";
+/** Script drafts on disk: <library dir>/content/period-NN/<piece>.{json,md} */
+export declare const CONTENT_DIR = "content";
+export type PieceKind = 'highlight' | 'howto';
+export type PieceStatus = 'ready' | 'ingested' | 'blocked' | 'error' | 'capped';
+export type PeriodStatus = 'done' | 'partial' | 'capped' | 'error' | 'dry' | 'no-pieces';
+export interface CheckSummary {
+    prepass: {
+        ok: boolean;
+        flags: string[];
+        rows: {
+            line: number;
+            row: number;
+            match: string;
+        }[];
+    };
+    truth: {
+        ok: boolean;
+        flags: string[];
+        model: string;
+        provider: string;
+        cacheKey: string;
+        cached: boolean;
+    } | null;
+    audience: {
+        ok: boolean;
+        flags: string[];
+        model: string;
+        provider: string;
+    } | null;
+    length: {
+        ok: boolean;
+        seconds: number;
+        min: number;
+        max: number;
+    };
+    /** WHAT-WORKS deterministic gate: stake present, causes vs duration, terms/min, no spoken versions/codes. */
+    structure?: {
+        ok: boolean;
+        flags: string[];
+        causes: number;
+        termsPerMin: number;
+    };
+}
+export interface PieceEntry {
+    id: string;
+    kind: PieceKind;
+    status: PieceStatus;
+    title: string;
+    /** Every HARD flag from every check (empty unless blocked). */
+    flags: string[];
+    /** Advisory quality flags (piece still scripted + ingested as a draft); see OSBORN_CONTENT_STRICT. */
+    warnings?: string[];
+    checks?: CheckSummary;
+    /** Stable per piece (session + period + piece id), so later media attach hits the same row. */
+    contentHash?: string;
+    ingest?: IngestState;
+    /** Script JSON on disk, relative to the library dir. */
+    file?: string;
+    costUsd: number;
+    errors: string[];
+    updatedAt: string;
+}
+export interface PeriodEntry {
+    startRowId: number;
+    endRowId: number;
+    index: number;
+    /** The library page this period's content was built from (file name in the library dir). */
+    page: string;
+    status: PeriodStatus;
+    /** Cumulative spend for this period across runs (the per-period cap reads this). */
+    costUsd: number;
+    /** Topics + briefs, stored once so a rerun never re-plans. */
+    plan?: unknown;
+    pieces: Record<string, PieceEntry>;
+    errors: string[];
+    updatedAt: string;
+}
+export interface ContentManifest {
+    version: 1;
+    sessionId: string;
+    /** key = String(startRowId) */
+    periods: Record<string, PeriodEntry>;
+}
+export declare function readContentManifest(dir: string, sessionId: string): ContentManifest;
+export declare function writeAtomic(path: string, text: string): void;
+export declare function writeContentManifest(dir: string, m: ContentManifest): void;
+export declare const isPieceTerminal: (p: PieceEntry | undefined) => boolean;
+/** Checks done (ready / ingested / blocked): never regenerated. */
+export declare const isPieceSettled: (p: PieceEntry | undefined) => boolean;
+/**
+ * Period status from its pieces. `ingestPending` = some ready piece still needs an
+ * ingest that can be retried for free; the period then stays "partial".
+ */
+export declare function periodStatusFor(e: PeriodEntry, o: {
+    dry: boolean;
+    ingestPending: boolean;
+    planned: boolean;
+}): PeriodStatus;
+export declare const periodDirName: (index: number) => string;

package/dist/content/content-manifest.js

@@ -0,0 +1,59 @@
+/**
+ * content-manifest.ts — Stage A per-period / per-piece state in
+ *   <library dir>/.content-manifest.json
+ * mirroring lens-library.ts's .library-manifest.json (same dir, keyed on the
+ * period's opening row id).
+ *
+ * Idempotency rules (content-run.ts):
+ *   - period "done"  → skipped, no model call, no spend.
+ *   - piece "ready"   → checks passed; only the ingest is (re)tried, no model call.
+ *   - piece "ingested" / "blocked" → terminal. Blocked is NEVER auto-fixed or retried.
+ *   - piece "error" / "capped" → regenerated next run (research + truth-check caches still apply).
+ *   - the period's plan (topics, research refs, briefs) is stored once and reused.
+ * Never throws on read (missing / unreadable → empty).
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const CONTENT_MANIFEST_FILE = '.content-manifest.json';
+/** Script drafts on disk: <library dir>/content/period-NN/<piece>.{json,md} */
+export const CONTENT_DIR = 'content';
+export function readContentManifest(dir, sessionId) {
+    try {
+        const o = JSON.parse(readFileSync(join(dir, CONTENT_MANIFEST_FILE), 'utf-8'));
+        if (o && typeof o.periods === 'object' && !Array.isArray(o.periods))
+            return { version: 1, sessionId, periods: o.periods };
+    }
+    catch {
+        /* missing / unreadable → empty */
+    }
+    return { version: 1, sessionId, periods: {} };
+}
+export function writeAtomic(path, text) {
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, text, 'utf-8');
+    renameSync(tmp, path);
+}
+export function writeContentManifest(dir, m) {
+    mkdirSync(dir, { recursive: true });
+    writeAtomic(join(dir, CONTENT_MANIFEST_FILE), JSON.stringify(m, null, 2) + '\n');
+}
+export const isPieceTerminal = (p) => !!p && (p.status === 'ingested' || p.status === 'blocked');
+/** Checks done (ready / ingested / blocked): never regenerated. */
+export const isPieceSettled = (p) => !!p && (isPieceTerminal(p) || p.status === 'ready');
+/**
+ * Period status from its pieces. `ingestPending` = some ready piece still needs an
+ * ingest that can be retried for free; the period then stays "partial".
+ */
+export function periodStatusFor(e, o) {
+    const ps = Object.values(e.pieces);
+    if (o.planned && ps.length === 0)
+        return 'no-pieces';
+    if (ps.some(p => p.status === 'capped'))
+        return 'capped';
+    if (!o.planned || ps.some(p => p.status === 'error'))
+        return ps.some(p => isPieceSettled(p)) ? 'partial' : 'error';
+    if (o.dry)
+        return 'dry';
+    return o.ingestPending ? 'partial' : 'done';
+}
+export const periodDirName = (index) => `period-${String(index).padStart(2, '0')}`;

package/dist/content/content-query-gate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * content-query-gate.ts — deterministic gate on every search query that leaves
+ * the machine (HN Algolia stories/comments, GitHub issue search). Runs AFTER
+ * the scrubber, as a second, rule-based line: a query either passes untouched
+ * or is dropped whole (never "repaired").
+ *
+ * A query is DROPPED when it:
+ *   - has any character outside [A-Za-z0-9 .+#-] (this covers / \ @ :// _ etc.)
+ *   - has a token containing "_" or CamelCase in the middle (refreshToken, MyApp)
+ *   - has a token equal to the project basename or a cwd path segment, or
+ *     contains such a segment as a phrase (acme-billing ⇔ "acme billing"), case-insensitive
+ *   - is not 2-5 plain words
+ *
+ * The allowlist is structural only: it cannot recognise private plain words
+ * (client names, IPs, people), so it relies on the scrubber running first.
+ */
+/** Private path terms: every segment of each path, plus each path's basename (and the raw value of non-path terms). */
+export declare function privateSegments(paths: (string | null | undefined)[]): string[];
+/** Returns the query (whitespace-collapsed) if it may leave the machine, else null. */
+export declare function gateQuery(q: string, privateTerms?: string[]): string | null;
+/** Gate a list: survivors only, de-duplicated, order kept. */
+export declare function gateQueries(qs: string[], privateTerms?: string[]): string[];

package/dist/content/content-query-gate.js

@@ -0,0 +1,78 @@
+/**
+ * content-query-gate.ts — deterministic gate on every search query that leaves
+ * the machine (HN Algolia stories/comments, GitHub issue search). Runs AFTER
+ * the scrubber, as a second, rule-based line: a query either passes untouched
+ * or is dropped whole (never "repaired").
+ *
+ * A query is DROPPED when it:
+ *   - has any character outside [A-Za-z0-9 .+#-] (this covers / \ @ :// _ etc.)
+ *   - has a token containing "_" or CamelCase in the middle (refreshToken, MyApp)
+ *   - has a token equal to the project basename or a cwd path segment, or
+ *     contains such a segment as a phrase (acme-billing ⇔ "acme billing"), case-insensitive
+ *   - is not 2-5 plain words
+ *
+ * The allowlist is structural only: it cannot recognise private plain words
+ * (client names, IPs, people), so it relies on the scrubber running first.
+ */
+import { basename } from 'node:path';
+const ALLOWED = /^[A-Za-z0-9 .+#-]+$/;
+const CAMEL_MID = /[a-z0-9][A-Z]/;
+const MIN_WORDS = 2;
+const MAX_WORDS = 5;
+const norm = (s) => s.toLowerCase().replace(/[-_.\s]+/g, ' ').trim();
+/** Private path terms: every segment of each path, plus each path's basename (and the raw value of non-path terms). */
+export function privateSegments(paths) {
+    const out = new Set();
+    for (const p of paths) {
+        const s = String(p ?? '').trim();
+        if (!s)
+            continue;
+        for (const seg of s.split(/[\\/]+/))
+            if (seg.trim())
+                out.add(seg.trim().toLowerCase());
+        const b = basename(s.replace(/[\\/]+$/, ''));
+        if (b)
+            out.add(b.toLowerCase());
+    }
+    return [...out];
+}
+/** Returns the query (whitespace-collapsed) if it may leave the machine, else null. */
+export function gateQuery(q, privateTerms = []) {
+    const s = String(q ?? '').replace(/\s+/g, ' ').trim();
+    if (!s || !ALLOWED.test(s))
+        return null;
+    if (/:\/\/|[\\/@_]/.test(s))
+        return null;
+    const tokens = s.split(' ');
+    if (tokens.length < MIN_WORDS || tokens.length > MAX_WORDS)
+        return null;
+    for (const t of tokens) {
+        if (!/[A-Za-z0-9]/.test(t))
+            return null;
+        if (t.includes('_') || CAMEL_MID.test(t))
+            return null;
+    }
+    const lowTokens = new Set(tokens.map(t => t.toLowerCase()));
+    const phrase = ` ${norm(s)} `;
+    for (const term of privateTerms) {
+        const raw = term.trim().toLowerCase();
+        if (!raw)
+            continue;
+        if (lowTokens.has(raw))
+            return null;
+        const n = norm(raw);
+        if (n && phrase.includes(` ${n} `))
+            return null;
+    }
+    return s;
+}
+/** Gate a list: survivors only, de-duplicated, order kept. */
+export function gateQueries(qs, privateTerms = []) {
+    const out = [];
+    for (const q of qs) {
+        const g = gateQuery(q, privateTerms);
+        if (g && !out.some(o => o.toLowerCase() === g.toLowerCase()))
+            out.push(g);
+    }
+    return out;
+}