@elvisw/dsh-magic-context 0.0.0-bootstrap.0

package/lib/core/global-domains.js

@@ -0,0 +1,302 @@
+/**
+ * Global-domain candidates: what may become org/machine knowledge, and why.
+ *
+ * The plan's original source was a recurrence scan — "the same normalized hash
+ * seen in two different projects". Measured against the live store on
+ * 2026-10-10 that source is EMPTY, and not because of a bug:
+ *
+ *   active rows 1292 · distinct projects 33 · hashes shared by 2+ projects 0
+ *   content identical across projects 0 · even the first 60 characters 0
+ *
+ * Historian facts are project-bound (file paths, decisions, incident details),
+ * so exact-normalized recurrence does not happen at this corpus size and has no
+ * reason to start. Building the lane on that gate would produce an
+ * always-empty pool while looking implemented — the "feed it a source we know
+ * is inaccurate" failure this project explicitly rejects.
+ *
+ * So the scan stays here as a MEASUREMENT (it answers "is recurrence a thing
+ * yet?" and is cheap to re-run), and the actual source is a human promotion:
+ * someone who recognises a project memory as organisation-level knowledge. That
+ * is also the only source consistent with the design rule that global memories
+ * are human-confirmed and never auto-promoted.
+ *
+ * Both paths write ONLY the adapter's own `global_candidates` table. Publishing
+ * into the shared store under a domain identity is a separate step with its own
+ * gate: `publishGlobalCandidate` (WP9) does the write, and an approval that has
+ * not happened yet can never reach it.
+ */
+import { DatabaseSync } from 'node:sqlite';
+/** The provider identity that owns organisation-scoped memories. */
+export const ORG_DOMAIN_ID = 'dir:global:org';
+/**
+ * Credential shapes that must never cross a project boundary.
+ *
+ * The design rule is "global memories store only POINTERS to secrets, never
+ * credential bodies" — a project-local note may legitimately contain a
+ * credential, but promoting it to a shared domain would leak it to every member
+ * project.
+ *
+ * Deliberately conservative: long hex/base64 runs are NOT flagged, because this
+ * corpus is full of commit ids and digests (40-hex sha1s everywhere) and a rule
+ * that fires on those would block almost every candidate. Only contextual
+ * assignments, URL userinfo, private-key headers and known credential prefixes
+ * count.
+ */
+const CREDENTIAL_RULES = [
+    // The leading boundary is `[^A-Za-z0-9]` rather than `\b`, because the shapes
+    // that matter most are SCREAMING_SNAKE env names (`DB_PASSWORD=…`), and `_` is
+    // a word character — `\bpassword` never matches there.
+    { rule: 'assign:password', pattern: /(?:^|[^A-Za-z0-9])(pass(word|wd|phrase)?|pwd)\s*[:=]\s*\S/i },
+    { rule: 'assign:secret', pattern: /(?:^|[^A-Za-z0-9])(client[_-]?secret|secret[_-]?key|secret)\s*[:=]\s*\S/i },
+    { rule: 'assign:api-key', pattern: /(?:^|[^A-Za-z0-9])(api[_-]?key|apikey|access[_-]?key|auth[_-]?token)\s*[:=]\s*\S/i },
+    { rule: 'assign:token', pattern: /(?:^|[^A-Za-z0-9])(token|credential|private[_-]?key)\s*[:=]\s*\S/i },
+    { rule: 'header:bearer', pattern: /authorization\s*[:=]\s*bearer\s+\S/i },
+    { rule: 'url-userinfo', pattern: /[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:[^/\s@]+@/i },
+    { rule: 'pem:private-key', pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+    { rule: 'prefix:openai', pattern: /\bsk-[A-Za-z0-9_-]{16,}/ },
+    { rule: 'prefix:github', pattern: /\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/ },
+    { rule: 'prefix:aws', pattern: /\bAKIA[0-9A-Z]{16}\b/ },
+    { rule: 'prefix:slack', pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,}/ },
+    { rule: 'prefix:google', pattern: /\bAIza[0-9A-Za-z_-]{30,}/ },
+];
+/** Which credential rules a piece of text trips (empty = safe to share). */
+export function scanForCredentials(content) {
+    return CREDENTIAL_RULES.filter(rule => rule.pattern.test(content)).map(rule => rule.rule);
+}
+/**
+ * The recurrence scan. Today this is a measurement: see the module comment.
+ * Returns the counts AND a sample of what it found, so a report can state the
+ * number instead of implying the lane works.
+ */
+export function detectGlobalCandidates(store, options) {
+    const domainId = options.domainId ?? ORG_DOMAIN_ID;
+    const limit = options.limit ?? 25;
+    const db = new DatabaseSync(options.corpusDbPath, { readOnly: true });
+    try {
+        const groups = db.prepare(`SELECT normalized_hash AS hash, COUNT(DISTINCT project_path) AS projects, MAX(id) AS newest
+         FROM memories
+        WHERE status = 'active' AND normalized_hash IS NOT NULL AND normalized_hash <> ''
+          AND project_path NOT LIKE 'dir:global:%' AND project_path NOT LIKE 'git:global:%'
+        GROUP BY normalized_hash
+       HAVING COUNT(DISTINCT project_path) >= 2
+        ORDER BY projects DESC, newest DESC
+        LIMIT ?`).all(limit);
+        const samples = [];
+        let upserted = 0;
+        let blocked = 0;
+        for (const group of groups) {
+            const members = db.prepare(`SELECT id, project_path, content, category FROM memories
+          WHERE status = 'active' AND normalized_hash = ? ORDER BY id`).all(group.hash);
+            const representative = members[members.length - 1];
+            if (representative === undefined)
+                continue;
+            if (scanForCredentials(representative.content).length > 0) {
+                blocked += 1;
+                continue;
+            }
+            const candidate = store.upsertGlobalCandidate({
+                domainId,
+                content: representative.content,
+                normalizedHash: group.hash,
+                firstIdentity: representative.project_path,
+                category: representative.category,
+                sourceMemoryId: representative.id,
+            }, options.now);
+            for (const member of members) {
+                // `memory:<id>` marks an observation that came from a stored memory
+                // rather than a live session.
+                store.recordCandidateObservation({ candidateId: candidate.id, identity: member.project_path, sessionId: `memory:${String(member.id)}` }, options.now);
+            }
+            upserted += 1;
+            samples.push({
+                hash: group.hash,
+                projects: group.projects,
+                newestMemoryId: group.newest,
+                content: representative.content.slice(0, 120),
+            });
+        }
+        return { hashes: groups.length, upserted, blocked, samples };
+    }
+    finally {
+        db.close();
+    }
+}
+/** Read one memory from the contract (read-only) for a promotion decision. */
+export function readCorpusMemory(corpusDbPath, memoryId) {
+    const db = new DatabaseSync(corpusDbPath, { readOnly: true });
+    try {
+        const row = db.prepare('SELECT id, project_path AS projectPath, category, content, normalized_hash AS normalizedHash, status '
+            + 'FROM memories WHERE id = ?').get(memoryId);
+        return row;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Promote one project memory into a domain's candidate pool — the human-
+ * initiated source. Writes only the adapter's own table; publishing is a
+ * separate step.
+ *
+ * Eligibility is checked HERE rather than at publish time so the reviewer never
+ * sees a candidate that could not be published: the memory must exist, be
+ * active, live in a real project (not already a domain identity), and carry no
+ * credential body.
+ */
+export function promoteMemoryToCandidate(store, options) {
+    const domainId = options.domainId ?? ORG_DOMAIN_ID;
+    if (store.getDomain(domainId) === undefined) {
+        return { ok: false, error: `unknown domain '${domainId}' — define it before promoting into it` };
+    }
+    const memory = readCorpusMemory(options.corpusDbPath, options.memoryId);
+    if (memory === undefined)
+        return { ok: false, error: `no memory #${String(options.memoryId)} in the shared store` };
+    if (memory.status !== 'active') {
+        return { ok: false, error: `memory #${String(memory.id)} is ${memory.status}, not active` };
+    }
+    if (memory.projectPath.startsWith('dir:global:') || memory.projectPath.startsWith('git:global:')) {
+        return { ok: false, error: `memory #${String(memory.id)} already lives in a global domain` };
+    }
+    const credentials = scanForCredentials(memory.content);
+    if (credentials.length > 0) {
+        return {
+            ok: false,
+            error: `memory #${String(memory.id)} trips ${credentials.join(', ')} — global memories carry POINTERS to secrets, `
+                + 'never credential bodies. Rewrite it as a reference and promote that.',
+        };
+    }
+    const candidate = store.upsertGlobalCandidate({
+        domainId,
+        content: memory.content,
+        normalizedHash: memory.normalizedHash,
+        firstIdentity: memory.projectPath,
+        category: memory.category,
+        sourceMemoryId: memory.id,
+        ...(options.suggestedDomain === undefined ? {} : { suggestedDomain: options.suggestedDomain }),
+        ...(options.suggestionReason === undefined ? {} : { suggestionReason: options.suggestionReason }),
+    }, options.now);
+    store.recordCandidateObservation({ candidateId: candidate.id, identity: memory.projectPath, sessionId: `memory:${String(memory.id)}` }, options.now);
+    // Re-read: the upsert deliberately writes zeroed counters and lets the
+    // observation rows define the weight, so the inserted snapshot is already
+    // stale by the time it is returned.
+    const refreshed = store.getGlobalCandidate(candidate.id) ?? candidate;
+    return { ok: true, candidate: refreshed, memory };
+}
+/**
+ * Whether a candidate may be approved.
+ *
+ * The recurrence gate exists to stop a MACHINE-detected one-off from becoming
+ * organisation-wide truth. A human promotion is a different signal: someone
+ * already judged it org-level, and approving it is a second human act — so the
+ * gate that applies is the publish pre-check (credentials, category), not the
+ * count.
+ */
+export function approvalGate(store, candidate, capProbe) {
+    if (candidate.state !== 'pending') {
+        return { ok: false, error: `candidate #${String(candidate.id)} is ${candidate.state}, not pending` };
+    }
+    const credentials = scanForCredentials(candidate.content);
+    if (credentials.length > 0) {
+        return { ok: false, error: `candidate #${String(candidate.id)} trips ${credentials.join(', ')}` };
+    }
+    const domain = store.getDomain(candidate.domainId);
+    if (domain === undefined)
+        return { ok: false, error: `unknown domain '${candidate.domainId}'` };
+    // A published row needs a category (the contract has it NOT NULL and the
+    // reader filters on the allowlist) — refuse here rather than letting the
+    // INSERT fail with a constraint error the reviewer cannot act on.
+    if (candidate.category === undefined || candidate.category === '') {
+        return {
+            ok: false,
+            error: `candidate #${String(candidate.id)} carries no category; a published memory needs one `
+                + `(one of: ${domain.shareCategories.join(', ') || 'the domain allowlist'})`,
+        };
+    }
+    if (!domain.shareCategories.includes(candidate.category)) {
+        // Publishing under a category outside the allowlist succeeds and is then
+        // invisible forever — a silent failure, so it is refused up front.
+        return {
+            ok: false,
+            error: `category ${candidate.category} is outside ${candidate.domainId}'s allowlist `
+                + `(${domain.shareCategories.join(', ') || 'nothing'}) — publishing it would be invisible`,
+        };
+    }
+    // The admission cap (2026-10-16): `domains.cap` is DERIVED from the domain's
+    // token budget and was, until this check existed, displayed by /ctx-global
+    // list and enforced by nothing — a domain could grow past its ceiling with no
+    // signal anywhere. Counted against LIVE rows, so an archived row frees its slot.
+    if (capProbe !== undefined) {
+        const live = capProbe.countDomainMemories(candidate.domainId);
+        if (live >= domain.cap) {
+            return {
+                ok: false,
+                error: `${candidate.domainId} is at its cap (${String(live)}/${String(domain.cap)} live row(s)) — `
+                    + 'withdraw a row or raise the domain budget before publishing another',
+            };
+        }
+    }
+    if (candidate.sourceMemoryId !== undefined)
+        return { ok: true };
+    if (candidate.distinctIdentities < 2) {
+        return {
+            ok: false,
+            error: `candidate #${String(candidate.id)} was observed by only ${String(candidate.distinctIdentities)} project(s); `
+                + 'a machine-detected promotion needs independent recurrence in at least two',
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Publish an approved candidate into the shared store, under its domain
+ * identity. This is the step that makes organisation knowledge real: the domain
+ * identity IS a peer project, so the existing peer lane carries the row with no
+ * second pool, no second watermark and no second digest.
+ *
+ * Order is load-bearing and deliberate:
+ *
+ *   1. the approval gate (credentials, category allowlist, recurrence) — a
+ *      refusal here must cost nothing;
+ *   2. the write;
+ *   3. the state transition, LAST.
+ *
+ * A candidate whose write failed therefore stays `pending` and can be retried,
+ * instead of being marked approved with an empty store behind it.
+ */
+export function publishGlobalCandidate(store, options) {
+    const candidate = store.getGlobalCandidate(options.candidateId);
+    if (candidate === undefined) {
+        return { ok: false, error: `no candidate #${String(options.candidateId)}` };
+    }
+    // The gate is the single implementation of every publish prerequisite, so the
+    // command surface, the tests and this function can never disagree about what
+    // is publishable.
+    const gate = approvalGate(store, candidate, options.writer);
+    if (!gate.ok)
+        return { ok: false, error: gate.error };
+    const domain = store.getDomain(candidate.domainId);
+    if (domain === undefined)
+        return { ok: false, error: `unknown domain '${candidate.domainId}'` };
+    // The gate guarantees these; re-reading narrows the optional fields for the
+    // writer without a non-null assertion.
+    const category = candidate.category;
+    if (category === undefined || category === '') {
+        return { ok: false, error: `candidate #${String(candidate.id)} carries no category` };
+    }
+    const written = options.writer.publishDomainMemory({
+        identity: candidate.domainId,
+        category,
+        content: options.contentOverride ?? candidate.content,
+        ...options.importance === undefined ? {} : { importance: options.importance },
+    });
+    if (!written.ok)
+        return { ok: false, error: `publish refused: ${written.detail}` };
+    store.setGlobalCandidateState(candidate.id, 'approved', options.now);
+    return {
+        ok: true,
+        memoryId: written.id,
+        created: written.created,
+        ...written.revived === true ? { revived: true } : {},
+        identity: candidate.domainId,
+        category,
+    };
+}

package/lib/core/journal.js

@@ -0,0 +1,248 @@
+/**
+ * The activity journal — the adapter's observability layer for the validation
+ * period.
+ *
+ * Why it exists: the harness's `ctx.logger` output is not persisted by the
+ * Desktop application (there is no plugin log file to inspect afterwards), and
+ * the adapter's other tables hold *state*, not *history* — they can say what is
+ * true now, never why a pass deferred or what a request cost. The journal is an
+ * append-only record of decisions and outcomes, written to the adapter's own
+ * SQLite database next to that state, plus an optional human-readable mirror
+ * file for `tail`/grep.
+ *
+ * Privacy and size discipline: message text is NEVER recorded. Call sites pass
+ * counts, tag numbers, token estimates, reasons and durations; every string is
+ * truncated and every array capped by {@link redactData}, so a long session
+ * cannot bloat the store.
+ *
+ * The review side lives in `scripts/mc-report.mjs`, which reads this table
+ * read-only and prints per-day rollups, key metrics and health hints.
+ */
+import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { errText } from "./types.js";
+/**
+ * Close the historian runs a previous mount left open. An hmr remount (or an
+ * app restart) disposes the stores while a run is in flight, so its `start`
+ * row never gets a terminal sibling — indistinguishable from a wedged run and
+ * a standing acceptance failure. At mount time no run of the NEW composition
+ * can be in flight yet, so every still-open start predates this process and
+ * gets exactly one synthetic terminal (`kind: 'adapter-remount'`). The audit
+ * invariant — start + exactly one terminal — is restored, not rewritten:
+ * the original start row stays untouched.
+ *
+ * @returns the number of recovered runs.
+ */
+export function recoverOrphanHistorianRuns(stores, journal) {
+    const recovered = [];
+    try {
+        const rows = stores.listJournal({ kinds: ['historian'], limit: 10_000 });
+        // Pass 1: starts already banked by a previous mount carry
+        // `recoveredStartAt` on their synthetic terminal. The markers sit at the
+        // journal tail — after the historic rows they repair — so they must be
+        // collected BEFORE pairing, or the supersede branch would re-report the
+        // same historic double-start on every remount.
+        const alreadyRecovered = new Set();
+        for (const row of rows) {
+            const data = row.data;
+            if (data?.phase === 'failed' && typeof data.recoveredStartAt === 'number') {
+                alreadyRecovered.add(`${row.sessionId ?? '-'}:${String(data.recoveredStartAt)}`);
+            }
+        }
+        // Pass 2: the pairing scan (chronological).
+        const open = new Map();
+        for (const row of [...rows].reverse()) {
+            const phase = row.data?.phase;
+            const key = row.sessionId ?? '-';
+            if (phase === 'start') {
+                // A second start in one session means the first was superseded while
+                // still open — the pairing maps would silently overwrite it (the same
+                // shape the acceptance audit counts as a silent evaporate), so the
+                // superseded start is recovered right here.
+                const previous = open.get(key);
+                if (previous !== undefined && !alreadyRecovered.has(`${key}:${String(previous.at)}`)) {
+                    recovered.push({ entry: previous, sessionId: row.sessionId });
+                }
+                open.set(key, row);
+            }
+            else if (phase === 'done' || phase === 'failed') {
+                open.delete(key);
+            }
+        }
+        for (const [key, start] of open) {
+            if (!alreadyRecovered.has(`${key}:${String(start.at)}`)) {
+                recovered.push({ entry: start, sessionId: key === '-' ? undefined : key });
+            }
+        }
+    }
+    catch {
+        return 0;
+    }
+    let count = 0;
+    for (const { entry: start, sessionId } of recovered) {
+        try {
+            journal.error('historian', 'historian run failed (adapter-remount): a previous mount was disposed before this run finished', {
+                phase: 'failed',
+                kind: 'adapter-remount',
+                reason: 'the adapter remounted (hmr or restart) while the run was in flight',
+                recovered: true,
+                recoveredStartAt: start.at,
+            }, sessionId);
+            count += 1;
+        }
+        catch {
+            /* a failing recovery must never block the mount */
+        }
+    }
+    return count;
+}
+const LEVEL_RANK = { info: 0, warn: 1, error: 2 };
+const MAX_STRING = 300;
+const MAX_ARRAY = 20;
+const MAX_DEPTH = 3;
+/**
+ * Bound one entry's structured payload: truncate long strings, cap arrays,
+ * limit nesting. Message content must never be passed here in the first place;
+ * this is the safety net that keeps a slip from bloating the store.
+ */
+export function redactData(value, depth = 0) {
+    if (value === null || typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        return value.length <= MAX_STRING ? value : `${value.slice(0, MAX_STRING)}…(${String(value.length)} chars)`;
+    }
+    if (value === undefined)
+        return undefined;
+    if (depth >= MAX_DEPTH)
+        return '[depth]';
+    if (Array.isArray(value)) {
+        const items = value.slice(0, MAX_ARRAY).map(item => redactData(item, depth + 1));
+        return value.length > MAX_ARRAY ? [...items, `…(${String(value.length)} items)`] : items;
+    }
+    if (typeof value === 'object') {
+        const source = value;
+        const result = {};
+        let index = 0;
+        for (const [key, item] of Object.entries(source)) {
+            if (index >= MAX_ARRAY) {
+                result['…'] = 'more keys omitted';
+                break;
+            }
+            if (item === undefined)
+                continue;
+            result[key] = redactData(item, depth + 1);
+            index += 1;
+        }
+        return result;
+    }
+    return String(value);
+}
+/** One mirror line: `ISO LEVEL kind [session] summary {json}`. */
+export function formatJournalLine(entry) {
+    const iso = new Date(entry.at).toISOString();
+    const session = entry.sessionId === undefined ? '' : ` ${entry.sessionId.slice(0, 12)}`;
+    const data = entry.data === undefined || Object.keys(entry.data).length === 0
+        ? ''
+        : ` ${JSON.stringify(entry.data)}`;
+    return `${iso} ${entry.level.toUpperCase().padEnd(5)} ${entry.kind}${session} ${entry.summary}${data}\n`;
+}
+/** Rotate the mirror once at open so it cannot grow without bound. */
+function rotateMirror(path, maxBytes) {
+    try {
+        const size = statSync(path).size;
+        if (size > maxBytes)
+            renameSync(path, `${path}.1`);
+    }
+    catch {
+        /* missing file is the normal first-open case */
+    }
+}
+/**
+ * Open the journal. Pruning and mirror rotation happen once here; every later
+ * write is a single small insert. Journal failures never propagate: they are
+ * reported through the harness logger and the adapter keeps working (the
+ * journal must not be able to break a turn).
+ */
+export function openJournal(options) {
+    const now = options.now ?? (() => Date.now());
+    const retentionDays = options.retentionDays ?? 30;
+    const mirrorMaxBytes = options.mirrorMaxBytes ?? 5 * 1024 * 1024;
+    const resolveLevel = () => {
+        if (typeof options.level !== 'function')
+            return options.level ?? 'info';
+        return options.level() ?? 'info';
+    };
+    const resolveMirror = () => {
+        const path = typeof options.mirrorPath === 'function' ? options.mirrorPath() : options.mirrorPath;
+        return typeof path === 'string' && path.length > 0 ? path : undefined;
+    };
+    /** Each distinct mirror path is prepared (mkdir + rotate) exactly once. */
+    const preparedMirrors = new Set();
+    const prepareMirror = (path) => {
+        if (preparedMirrors.has(path))
+            return;
+        preparedMirrors.add(path);
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            rotateMirror(path, mirrorMaxBytes);
+        }
+        catch (error) {
+            options.logger?.warn(`magic-context journal: mirror unavailable: ${errText(error)}`);
+        }
+    };
+    try {
+        const pruned = options.stores.pruneJournal(now() - retentionDays * 24 * 60 * 60_000);
+        if (pruned > 0)
+            options.logger?.info(`magic-context journal: pruned ${String(pruned)} entries past retention`);
+    }
+    catch (error) {
+        options.logger?.warn(`magic-context journal: retention prune failed: ${errText(error)}`);
+    }
+    const write = (entry) => {
+        try {
+            options.stores.appendJournal(entry);
+        }
+        catch (error) {
+            options.logger?.warn(`magic-context journal: write failed (${entry.kind}): ${errText(error)}`);
+        }
+        const mirror = resolveMirror();
+        if (mirror !== undefined) {
+            prepareMirror(mirror);
+            try {
+                appendFileSync(mirror, formatJournalLine(entry));
+            }
+            catch {
+                /* the mirror is a convenience; the database is authoritative */
+            }
+        }
+    };
+    const record = (level, kind, summary, data, sessionId) => {
+        if (LEVEL_RANK[level] < LEVEL_RANK[resolveLevel()])
+            return;
+        const entry = {
+            at: now(),
+            level,
+            kind,
+            summary,
+            ...sessionId === undefined ? {} : { sessionId },
+            ...data === undefined ? {} : { data: redactData(data) },
+        };
+        write(entry);
+        if (level === 'error')
+            options.logger?.warn(`magic-context [${kind}] ${summary}`);
+    };
+    return {
+        enabled: true,
+        record,
+        info: (kind, summary, data, sessionId) => record('info', kind, summary, data, sessionId),
+        warn: (kind, summary, data, sessionId) => record('warn', kind, summary, data, sessionId),
+        error: (kind, summary, data, sessionId) => record('error', kind, summary, data, sessionId),
+        tail: (limit = 50, sessionId) => options.stores.listJournal({
+            limit,
+            ...sessionId === undefined ? {} : { sessionId },
+        }),
+        byKind: since => options.stores.journalByKind(since),
+        /** Live: follows a getter-backed `mirrorPath` option without a reopen. */
+        get mirrorPath() { return resolveMirror(); },
+    };
+}

package/lib/core/llm-deadline.js

@@ -0,0 +1,53 @@
+/**
+ * Wall-clock budgets for one auxiliary LLM round trip.
+ *
+ * The historian has carried this guard since it was wired (see
+ * `src/dsh/historian.ts` `collectAttempt`): its policy note spells the rule out —
+ * "a provider that never settles must not leave the run unaccounted". The
+ * maintenance lane (verify + profile review) never got one, and there the
+ * consequence is worse than a lost row: the ticker's `setInterval` is installed
+ * only after the FIRST tick resolves, so one never-settling stream would stop
+ * TTL expiry, verification, profile review and vector backfill for the whole
+ * life of the process — silently, because the lane simply never reports again.
+ *
+ * The budget is enforced twice on purpose, exactly like the historian's:
+ *
+ * - the abort signal tells a compliant provider stream to stop, so the socket is
+ *   released instead of lingering until the host's own transport timeout;
+ * - `Promise.race` rejects even when the seam ignores the signal entirely, which
+ *   is the case this module exists for (a stream that yields nothing forever
+ *   never observes an abort).
+ */
+export class LlmDeadlineError extends Error {
+    budgetMs;
+    constructor(budgetMs) {
+        super(`no terminal event within ${String(budgetMs)}ms`);
+        this.name = 'LlmDeadlineError';
+        this.budgetMs = budgetMs;
+    }
+}
+/**
+ * Run `work` against a fresh abort signal, rejecting with {@link LlmDeadlineError}
+ * once `budgetMs` elapses. The timer is `unref`ed so a pending budget never holds
+ * the host process open by itself.
+ */
+export async function withDeadline(work, budgetMs) {
+    const controller = new AbortController();
+    let timer;
+    const expiry = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            // Abort first: a stream that *would* have stopped on a signal gets the
+            // chance to release its socket before the rejection unwinds.
+            controller.abort(new LlmDeadlineError(budgetMs));
+            reject(new LlmDeadlineError(budgetMs));
+        }, budgetMs);
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([work(controller.signal), expiry]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}