hippo-memory 1.44.0 → 1.46.0

package/dist/doctor.js

@@ -0,0 +1,174 @@
+/**
+ * `hippo doctor`: a health check people and agents can run after installing
+ * hippo, or when something seems off. Read-only: it never creates a store,
+ * installs a hook or migrates a database. Every non-passing check names the
+ * command that fixes it, so an agent can act on the `--json` output.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { findHippoStoreDir } from './project-identity.js';
+import { getGlobalRoot } from './shared.js';
+import { isInitialized, loadStats } from './store.js';
+import { openHippoDb, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion } from './db.js';
+import { isEmbeddingAvailable } from './embeddings.js';
+/** Minimum Node.js version hippo supports (package.json engines). */
+export const MIN_NODE = '22.16.0';
+function versionAtLeast(actual, min) {
+    const a = actual.replace(/^v/, '').split('.').map(Number);
+    const b = min.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y)
+            return x > y;
+    }
+    return true;
+}
+function readJson(file) {
+    try {
+        // SAFETY: JSON.parse returns a JSON value by definition.
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function countRows(db, table) {
+    try {
+        // SAFETY: COUNT(*) returns one row with one numeric column.
+        const row = db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get();
+        return Number(row?.n ?? 0);
+    }
+    catch {
+        return null;
+    }
+}
+/** Run every check. Never throws for a broken install; broken parts become failed checks. */
+export function runDoctor(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? os.homedir();
+    const now = opts.now ?? new Date();
+    const checks = [];
+    const node = opts.nodeVersion ?? process.versions.node;
+    checks.push(versionAtLeast(node, MIN_NODE)
+        ? { id: 'node', status: 'pass', detail: `Node.js ${node}` }
+        : { id: 'node', status: 'fail', detail: `Node.js ${node} is older than ${MIN_NODE}`, fix: `Install Node.js ${MIN_NODE} or newer` });
+    const local = findHippoStoreDir(cwd);
+    const globalRoot = getGlobalRoot();
+    const hasGlobal = isInitialized(globalRoot);
+    let store = null;
+    if (local !== null) {
+        store = local;
+        checks.push({ id: 'store', status: 'pass', detail: `project store at ${local}${hasGlobal ? ` (global store at ${globalRoot} too)` : ''}` });
+    }
+    else if (hasGlobal) {
+        store = globalRoot;
+        checks.push({ id: 'store', status: 'warn', detail: `no project store here; using the global store at ${globalRoot}`, fix: 'hippo init   (in the project root)' });
+    }
+    else {
+        checks.push({ id: 'store', status: 'fail', detail: 'no hippo store found (project or global)', fix: 'hippo init   (in the project root), or hippo init --global' });
+    }
+    if (store !== null) {
+        let db = null;
+        try {
+            db = openHippoDb(store);
+            const have = getSchemaVersion(db);
+            const want = getCurrentSchemaVersion();
+            checks.push(have === want
+                ? { id: 'schema', status: 'pass', detail: `database schema v${have}` }
+                : have > want
+                    ? { id: 'schema', status: 'fail', detail: `database schema v${have} is newer than this hippo (v${want})`, fix: 'npm install -g hippo-memory@latest' }
+                    : { id: 'schema', status: 'info', detail: `database schema v${have}; hippo migrates it to v${want} on the next write` });
+            const memories = countRows(db, 'memories');
+            const dormant = countRows(db, 'dormant_memories');
+            const memoryCheck = { id: 'memories', status: 'info', detail: `${memories ?? '?'} memories${dormant !== null ? `, ${dormant} dormant` : ''}` };
+            if (memories === 0) {
+                memoryCheck.status = 'warn';
+                memoryCheck.fix = 'hippo learn --git   (seed lessons from git history)';
+            }
+            checks.push(memoryCheck);
+            const since = new Date(now.getTime() - 7 * 86_400_000).toISOString();
+            try {
+                // SAFETY: COUNT/SUM aggregate row.
+                const row = db.prepare(`SELECT COUNT(*) AS n, COALESCE(SUM(tokens), 0) AS t FROM token_ledger WHERE ts >= ? AND event = 'inject'`).get(since);
+                checks.push({ id: 'tokens', status: 'info', detail: `${Number(row?.n ?? 0)} memory blocks sent to agents in 7 days, about ${Number(row?.t ?? 0)} tokens (hippo tokens for detail)` });
+            }
+            catch {
+                checks.push({ id: 'tokens', status: 'info', detail: 'no token ledger yet (created on the next write)' });
+            }
+        }
+        catch (err) {
+            checks.push({ id: 'schema', status: 'fail', detail: `cannot open the database: ${err instanceof Error ? err.message : String(err)}`, fix: 'check file permissions on the .hippo folder' });
+        }
+        finally {
+            if (db !== null)
+                closeHippoDb(db);
+        }
+        try {
+            const runs = loadStats(store)['consolidation_runs'];
+            const last = Array.isArray(runs) && runs.length > 0 ? runs[runs.length - 1] : null;
+            // SAFETY: the constructor check above narrows `last` to a plain JSON object.
+            const ts = last !== null && last !== undefined && !Array.isArray(last) && last.constructor === Object ? last.timestamp : undefined;
+            const when = ts !== undefined && ts !== null ? Date.parse(String(ts)) : Number.NaN;
+            if (Number.isNaN(when)) {
+                checks.push({ id: 'sleep', status: 'warn', detail: 'hippo has never slept (consolidated) in this store', fix: 'hippo sleep   (the session-end hook runs it automatically)' });
+            }
+            else {
+                const days = Math.floor((now.getTime() - when) / 86_400_000);
+                checks.push(days > 7
+                    ? { id: 'sleep', status: 'warn', detail: `last sleep ${days} days ago`, fix: 'hippo sleep, and check the session-end hook is installed' }
+                    : { id: 'sleep', status: 'pass', detail: `last sleep ${days === 0 ? 'today' : `${days} day${days === 1 ? '' : 's'} ago`}` });
+            }
+        }
+        catch {
+            checks.push({ id: 'sleep', status: 'info', detail: 'sleep history unavailable' });
+        }
+    }
+    const claudeDir = path.join(home, '.claude');
+    if (fs.existsSync(claudeDir)) {
+        const settings = readJson(path.join(claudeDir, 'settings.json'));
+        const text = settings === null ? '' : JSON.stringify(settings);
+        const viaPlugin = /hippo-memory@/.test(text);
+        // Each hook and what it does, so a partial install says what is missing.
+        const hooks = [
+            ['hippo context --pinned-only', 'per-prompt memory'],
+            ['hippo session-end', 'session-end capture and sleep'],
+            ['hippo pre-compact', 'compaction snapshot and capture'],
+            ['hippo compact-resume', 'resume after compaction'],
+            ['hippo post-compact', 'the message after compaction'],
+            ['hippo capture-error', 'failed-tool capture'],
+        ];
+        const missing = hooks.filter(([marker]) => !text.includes(marker)).map(([, what]) => what);
+        if (viaPlugin) {
+            checks.push({ id: 'claude-code', status: 'pass', detail: 'Claude Code: hippo plugin enabled (all hooks, including compaction and failed-tool capture)' });
+        }
+        else if (missing.length === 0) {
+            checks.push({ id: 'claude-code', status: 'pass', detail: 'Claude Code: all hippo hooks installed, including compaction and failed-tool capture' });
+        }
+        else if (missing.length === hooks.length) {
+            checks.push({ id: 'claude-code', status: 'warn', detail: 'Claude Code found, but no hippo hooks are installed', fix: 'hippo hook install claude-code' });
+        }
+        else {
+            checks.push({ id: 'claude-code', status: 'warn', detail: `Claude Code: hippo hooks missing for ${missing.join(', ')}`, fix: 'hippo hook install claude-code   (adds only what is missing)' });
+        }
+    }
+    else {
+        checks.push({ id: 'claude-code', status: 'info', detail: 'Claude Code not found; other agents can use hippo over MCP (hippo mcp)' });
+    }
+    checks.push({ id: 'embeddings', status: 'info', detail: isEmbeddingAvailable() ? 'local embeddings available (hybrid search)' : 'embeddings not installed; recall uses BM25 (optional: hippo embed --help)' });
+    return { ok: !checks.some((c) => c.status === 'fail'), version: opts.version, store, checks };
+}
+/** Human-readable rendering of a {@link DoctorReport}. */
+export function formatDoctor(report) {
+    const mark = { pass: 'ok  ', warn: 'warn', fail: 'FAIL', info: 'info' };
+    const lines = [`hippo ${report.version} doctor`, ''];
+    for (const c of report.checks) {
+        lines.push(`  [${mark[c.status]}] ${c.id.padEnd(11)} ${c.detail}`);
+        if (c.fix && (c.status === 'warn' || c.status === 'fail'))
+            lines.push(`         ${''.padEnd(11)} fix: ${c.fix}`);
+    }
+    lines.push('', report.ok ? 'No failures.' : 'Some checks failed; run the fix commands above.');
+    return lines.join('\n');
+}
+//# sourceMappingURL=doctor.js.map

package/dist/dormant.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Dormant memories: what sleep does with a faded memory instead of deleting
+ * it (config `dormant.enabled`, on by default; `retentionDays` bounds how
+ * long one is kept).
+ *
+ * A dormant memory keeps its full content in `dormant_memories` (schema v44)
+ * but is no longer a `memories` row, so recall, context, every sleep pass and
+ * every other reader of `memories` stop seeing it exactly as if it had been
+ * deleted. `hippo dormant` lists and searches them, `hippo dormant restore`
+ * brings one back, `hippo dormant forget` deletes one for good.
+ *
+ * Not to be confused with the raw archive (`raw_archive`, `archiveRawMemory`,
+ * `hippo forget --archive`): that path removes a raw receipt's content and
+ * keeps only its metadata. A dormant memory keeps its content.
+ *
+ * DB-only helpers: the caller owns the handle and any transaction. The
+ * tenant-scoped entry points are api.listDormant / restoreDormant /
+ * forgetDormant.
+ */
+import type { DatabaseSyncLike } from './db.js';
+import type { MemoryEntry } from './memory.js';
+/** Why sleep made a memory dormant. Only the decay pass does today. */
+export type DormantReason = 'decay';
+/** One memory that sleep is moving out of active memory into the dormant store. */
+export interface DormantMove {
+    /** The memory as it stood when it faded; restored verbatim apart from its recall clock. */
+    entry: MemoryEntry;
+    /** Live strength at the moment it went dormant (below the decay threshold). */
+    strength: number;
+    reason: DormantReason;
+    /** ISO time of the sleep that made it dormant. */
+    dormantAt: string;
+}
+/** A dormant memory as listed to a user. */
+export interface DormantMemory {
+    id: string;
+    tenantId: string;
+    content: string;
+    tags: string[];
+    /** Live strength when it went dormant. */
+    strength: number;
+    /** Why it went dormant (`decay`). */
+    reason: string;
+    /** ISO time it went dormant. */
+    dormantAt: string;
+}
+/** Options for {@link listDormantRows}. */
+export interface ListDormantOpts {
+    /** Whitespace-separated terms; a row must contain every term (case-insensitive substring). */
+    query?: string;
+    /** Maximum rows returned, newest first. Default 20. */
+    limit?: number;
+}
+/**
+ * Insert (or refresh) the dormant snapshot for `move.entry`. Does not touch
+ * the `memories` row: the caller deletes it in the same transaction, so the
+ * memory is never in both places or in neither.
+ */
+export declare function insertDormantRow(db: DatabaseSyncLike, move: DormantMove): void;
+/** A tenant's dormant memories, newest first, optionally filtered by search terms. */
+export declare function listDormantRows(db: DatabaseSyncLike, tenantId: string, opts?: ListDormantOpts): DormantMemory[];
+/** A dormant memory's stored snapshot plus when and why it went dormant. */
+export interface DormantSnapshot {
+    entry: MemoryEntry;
+    reason: string;
+    strength: number;
+    dormantAt: string;
+}
+/**
+ * The stored snapshot for a tenant's dormant memory, or null when the tenant
+ * has no dormant memory with that id (another tenant's id reads as absent).
+ */
+export declare function readDormantSnapshot(db: DatabaseSyncLike, tenantId: string, id: string): DormantSnapshot | null;
+/** Whether a tenant has a dormant memory with this id (snapshot readable or not). */
+export declare function hasDormantRow(db: DatabaseSyncLike, tenantId: string, id: string): boolean;
+/** Delete a tenant's dormant memory. Returns false when there was none. */
+export declare function deleteDormantRow(db: DatabaseSyncLike, tenantId: string, id: string): boolean;
+/**
+ * Delete every dormant memory in the tenant whose content has this rejection
+ * digest, so a rejected value cannot linger in dormant storage. Returns the
+ * ids removed. Same O(N) scan as the live-row sweep in reject-flow.ts.
+ */
+export declare function purgeDormantByDigest(db: DatabaseSyncLike, tenantId: string, digest: string): string[];
+/** How many dormant memories went dormant before `cutoffIso` (a dry-run count). */
+export declare function countExpiredDormant(db: DatabaseSyncLike, cutoffIso: string): number;
+/**
+ * Delete every dormant memory (all tenants) that went dormant before
+ * `cutoffIso`: the `dormant.retentionDays` window. Returns how many went.
+ */
+export declare function purgeExpiredDormant(db: DatabaseSyncLike, cutoffIso: string): number;
+//# sourceMappingURL=dormant.d.ts.map

package/dist/dormant.js

@@ -0,0 +1,121 @@
+import { rejectionDigest } from './rejection.js';
+const DEFAULT_LIST_LIMIT = 20;
+/**
+ * Insert (or refresh) the dormant snapshot for `move.entry`. Does not touch
+ * the `memories` row: the caller deletes it in the same transaction, so the
+ * memory is never in both places or in neither.
+ */
+export function insertDormantRow(db, move) {
+    db.prepare(`
+    INSERT INTO dormant_memories (tenant_id, id, content, entry_json, reason, strength, dormant_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(tenant_id, id) DO UPDATE SET
+      content = excluded.content,
+      entry_json = excluded.entry_json,
+      reason = excluded.reason,
+      strength = excluded.strength,
+      dormant_at = excluded.dormant_at
+  `).run(move.entry.tenantId, move.entry.id, move.entry.content, JSON.stringify(move.entry), move.reason, move.strength, move.dormantAt);
+}
+/** Escape LIKE metacharacters so a search term matches literally (ESCAPE '\'). */
+function escapeLike(term) {
+    return term.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+/**
+ * Parse a stored snapshot back into a MemoryEntry, or null when the row no
+ * longer matches the snapshot it carries (edited by hand, or truncated).
+ */
+function parseSnapshot(row) {
+    try {
+        // SAFETY: entry_json is only written by insertDormantRow from a MemoryEntry;
+        // the id / tenant / content checks below reject a row edited out of shape.
+        const entry = JSON.parse(row.entry_json);
+        if (entry.id !== row.id || entry.tenantId !== row.tenant_id || entry.content !== row.content) {
+            return null;
+        }
+        return entry;
+    }
+    catch {
+        return null;
+    }
+}
+function rowToDormantMemory(row) {
+    const entry = parseSnapshot(row);
+    return {
+        id: row.id,
+        tenantId: row.tenant_id,
+        content: row.content,
+        tags: entry && Array.isArray(entry.tags) ? entry.tags.map(String) : [],
+        strength: row.strength,
+        reason: row.reason,
+        dormantAt: row.dormant_at,
+    };
+}
+/** A tenant's dormant memories, newest first, optionally filtered by search terms. */
+export function listDormantRows(db, tenantId, opts = {}) {
+    const terms = (opts.query ?? '').trim().split(/\s+/).filter((t) => t.length > 0);
+    const limit = opts.limit !== undefined && Number.isFinite(opts.limit) && opts.limit >= 1
+        ? Math.floor(opts.limit)
+        : DEFAULT_LIST_LIMIT;
+    const termClauses = terms.map(() => ` AND content LIKE ? ESCAPE '\\'`).join('');
+    // SAFETY: rows' shape matches the seven columns named in the SELECT.
+    const rows = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
+       FROM dormant_memories
+      WHERE tenant_id = ?${termClauses}
+      ORDER BY dormant_at DESC, id ASC
+      LIMIT ?`).all(tenantId, ...terms.map((t) => `%${escapeLike(t)}%`), limit);
+    return rows.map(rowToDormantMemory);
+}
+/**
+ * The stored snapshot for a tenant's dormant memory, or null when the tenant
+ * has no dormant memory with that id (another tenant's id reads as absent).
+ */
+export function readDormantSnapshot(db, tenantId, id) {
+    // SAFETY: row's shape matches the seven columns named in the SELECT.
+    const row = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
+       FROM dormant_memories WHERE tenant_id = ? AND id = ?`).get(tenantId, id);
+    const entry = row ? parseSnapshot(row) : null;
+    return row && entry ? { entry, reason: row.reason, strength: row.strength, dormantAt: row.dormant_at } : null;
+}
+/** Whether a tenant has a dormant memory with this id (snapshot readable or not). */
+export function hasDormantRow(db, tenantId, id) {
+    return db.prepare(`SELECT 1 FROM dormant_memories WHERE tenant_id = ? AND id = ?`).get(tenantId, id) !== undefined;
+}
+/** Delete a tenant's dormant memory. Returns false when there was none. */
+export function deleteDormantRow(db, tenantId, id) {
+    const result = db.prepare(`DELETE FROM dormant_memories WHERE tenant_id = ? AND id = ?`).run(tenantId, id);
+    return Number(result.changes ?? 0) > 0;
+}
+/**
+ * Delete every dormant memory in the tenant whose content has this rejection
+ * digest, so a rejected value cannot linger in dormant storage. Returns the
+ * ids removed. Same O(N) scan as the live-row sweep in reject-flow.ts.
+ */
+export function purgeDormantByDigest(db, tenantId, digest) {
+    // SAFETY: rows' shape matches the two columns named in the SELECT.
+    const rows = db.prepare(`SELECT id, content FROM dormant_memories WHERE tenant_id = ?`)
+        .all(tenantId);
+    const removed = [];
+    for (const row of rows) {
+        if (rejectionDigest(row.content) !== digest)
+            continue;
+        deleteDormantRow(db, tenantId, row.id);
+        removed.push(row.id);
+    }
+    return removed;
+}
+/** How many dormant memories went dormant before `cutoffIso` (a dry-run count). */
+export function countExpiredDormant(db, cutoffIso) {
+    // SAFETY: row's shape matches the single aliased COUNT column in the SELECT.
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM dormant_memories WHERE dormant_at < ?`).get(cutoffIso);
+    return Number(row.n);
+}
+/**
+ * Delete every dormant memory (all tenants) that went dormant before
+ * `cutoffIso`: the `dormant.retentionDays` window. Returns how many went.
+ */
+export function purgeExpiredDormant(db, cutoffIso) {
+    const result = db.prepare(`DELETE FROM dormant_memories WHERE dormant_at < ?`).run(cutoffIso);
+    return Number(result.changes ?? 0);
+}
+//# sourceMappingURL=dormant.js.map

package/dist/embedding-provider.js

@@ -31,6 +31,7 @@
  */
 import { getEmbedding, isEmbeddingAvailable, resolveEmbeddingModel, DEFAULT_EMBEDDING_MODEL, } from './embeddings.js';
 import { loadConfig } from './config.js';
+import { redactSecrets } from './secret-detect.js';
 export const API_PROVIDER_KINDS = ['openai', 'voyage', 'cohere'];
 function isApiProviderKind(x) {
     return x === 'openai' || x === 'voyage' || x === 'cohere';
@@ -188,7 +189,7 @@ class ApiEmbeddingProvider {
                     'content-type': 'application/json',
                     authorization: `Bearer ${key}`,
                 },
-                body: JSON.stringify(spec.buildBody(this.model, chunk, role)),
+                body: JSON.stringify(spec.buildBody(this.model, chunk.map(redactSecrets), role)),
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
         }

package/dist/embeddings.js

@@ -5,6 +5,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { randomUUID } from 'crypto';
 import { createRequire } from 'module';
 import { loadAllEntries } from './store.js';
 import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
@@ -244,13 +245,13 @@ export function saveStoredEmbeddingModel(hippoRoot, model) {
         closeHippoDb(db);
     }
 }
-export function resolveIndexedEmbeddingModel(hippoRoot, index = loadEmbeddingIndex(hippoRoot)) {
+export function resolveIndexedEmbeddingModel(hippoRoot, index) {
     const stored = loadStoredEmbeddingModel(hippoRoot);
     if (stored)
         return stored;
-    return Object.keys(index).length > 0 ? DEFAULT_EMBEDDING_MODEL : null;
+    return Object.keys(index ?? loadEmbeddingIndex(hippoRoot)).length > 0 ? DEFAULT_EMBEDDING_MODEL : null;
 }
-export function embeddingModelRequiresReindex(hippoRoot, model, index = loadEmbeddingIndex(hippoRoot)) {
+export function embeddingModelRequiresReindex(hippoRoot, model, index) {
     const stored = resolveIndexedEmbeddingModel(hippoRoot, index);
     return stored !== null && stored !== embeddingIndexIdentity(model);
 }
@@ -374,16 +375,86 @@ export function saveEmbeddingIndex(hippoRoot, index) {
         throw err;
     }
 }
-// Mutex to serialize embedding writes and prevent read-modify-write races
+const EMBED_LOCK_FILE = 'embeddings.lock';
+const EMBED_LOCK_WAIT_MS = 10_000;
+const EMBED_LOCK_OWNER = `${process.pid}:${randomUUID()}`;
+// In-process mutex plus an O_EXCL "<pid>:<token>" lock file: our token is a lock we leaked; our PID with another token is a live worker thread, unless the lock predates this process (a reused PID).
 let _embedWriteLock = Promise.resolve();
-async function withEmbedLock(fn) {
+function embedLockHolderAlive(lockPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(lockPath, 'utf8');
+    }
+    catch (err) {
+        return !(err instanceof Error && 'code' in err && err.code === 'ENOENT');
+    }
+    const mtimeMs = fs.statSync(lockPath, { throwIfNoEntry: false })?.mtimeMs ?? 0;
+    const pid = Number(raw.split(':')[0]);
+    // An empty lock is a holder between create and write; after 5 s it is a crashed one.
+    if (!Number.isInteger(pid) || pid <= 0)
+        return Date.now() - mtimeMs < 5_000;
+    if (raw === EMBED_LOCK_OWNER)
+        return false;
+    if (pid === process.pid)
+        return mtimeMs >= Date.now() - process.uptime() * 1000;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err instanceof Error && 'code' in err && err.code === 'EPERM';
+    }
+}
+// After the double-break race below the file can be another writer's lock, so remove only our own.
+function releaseEmbedFileLock(lockPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(lockPath, 'utf8');
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    if (raw === EMBED_LOCK_OWNER)
+        fs.rmSync(lockPath, { force: true });
+}
+async function acquireEmbedFileLock(hippoRoot) {
+    const lockPath = path.join(hippoRoot, EMBED_LOCK_FILE);
+    const deadline = Date.now() + EMBED_LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            fs.writeFileSync(lockPath, EMBED_LOCK_OWNER, { flag: 'wx' });
+            return () => releaseEmbedFileLock(lockPath);
+        }
+        catch (err) {
+            if (!(err instanceof Error && 'code' in err && err.code === 'EEXIST'))
+                throw err;
+        }
+        // SHORTCUT: two waiters can both break one dead holder's lock; a vector lost that way is backfilled by the next `hippo embed`.
+        if (!embedLockHolderAlive(lockPath)) {
+            fs.rmSync(lockPath, { force: true });
+            continue;
+        }
+        if (Date.now() >= deadline)
+            throw new Error(`embeddings.json is busy: another hippo process holds ${lockPath}`);
+        await new Promise((r) => setTimeout(r, 50));
+    }
+}
+async function withEmbedLock(hippoRoot, fn) {
     let resolve;
     const next = new Promise(r => { resolve = r; });
     const prev = _embedWriteLock;
     _embedWriteLock = next;
     await prev;
     try {
-        return await fn();
+        const release = await acquireEmbedFileLock(hippoRoot);
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
     }
     finally {
         resolve();
@@ -396,7 +467,7 @@ export async function embedMemory(hippoRoot, entry, model) {
     const provider = resolveEmbeddingProvider(hippoRoot, { model });
     if (!provider.isAvailable())
         return;
-    return withEmbedLock(async () => {
+    return withEmbedLock(hippoRoot, async () => {
         // embedMemory is best-effort: an embedding failure (API down / bad key / 5xx)
         // must not reject the caller's write — `getEmbedding` historically swallowed
         // failures and returned []. The explicit `hippo embed` / `embedAll` path is
@@ -445,6 +516,8 @@ export async function embedMemory(hippoRoot, entry, model) {
         catch {
             // Provider failure (API down / bad key). Best-effort: leave the index as-is.
         }
+    }).catch((err) => {
+        console.error(`hippo: skipped embedding ${entry.id} (${err instanceof Error ? err.message : String(err)}); run 'hippo embed' to backfill`);
     });
 }
 /**
@@ -468,7 +541,7 @@ export async function embedAll(hippoRoot, model) {
         }
         return 0;
     }
-    return withEmbedLock(async () => {
+    return withEmbedLock(hippoRoot, async () => {
         const identity = provider.id;
         // L9: host-wide by design. embedAll backfills vectors for all tenants'
         // entries into the per-host embedding index. Per-tenant filtering would

package/dist/eval-stats.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Statistics and cost accounting for the token-efficiency evals (ROADMAP
+ * Part IX, TE3-TE5).
+ *
+ * - Cost: price provider usage over four buckets (uncached input, cache
+ *   write, cache read, output). Raw token counts overstate savings when most
+ *   input is already cache reads, so every dollar claim goes through here.
+ * - Uncertainty: paired bootstrap over tasks, cluster bootstrap (tasks that
+ *   share a repository are not independent), and a paired ratio bootstrap for
+ *   dollars per resolved task.
+ *
+ * Deterministic: every resampling function takes a seed, so a published
+ * result can be reproduced exactly.
+ */
+/** Token usage for one model call or one whole task, split by how it is billed. */
+export interface Usage {
+    /** Input tokens billed at the base input price (not read from or written to a cache). */
+    inputTokens: number;
+    /** Input tokens written to a prompt cache. */
+    cacheWriteTokens: number;
+    /** Input tokens read from a prompt cache. */
+    cacheReadTokens: number;
+    /** Output tokens, including any reasoning tokens the provider bills as output. */
+    outputTokens: number;
+}
+/**
+ * Prices in dollars per million tokens. Take them from the provider's
+ * current price page for the exact model; this module has no built-in
+ * prices because they change.
+ */
+export interface Prices {
+    inputPerMTok: number;
+    cacheWritePerMTok: number;
+    cacheReadPerMTok: number;
+    outputPerMTok: number;
+}
+/** Sum several usages bucket by bucket. */
+export declare function addUsage(...usages: Usage[]): Usage;
+/** Dollar cost of `usage` at `prices`. */
+export declare function priceUsage(usage: Usage, prices: Prices): number;
+/**
+ * Relative prices of the cache buckets against the base input price, for
+ * cost in "uncached-equivalent tokens" when no dollar prices are given.
+ * Defaults follow Anthropic's published ratios (5-minute cache write 1.25x,
+ * cache read 0.1x); pass the ratios for another provider when needed.
+ */
+export interface CacheRatios {
+    write: number;
+    read: number;
+}
+/** Default cache price ratios (write 1.25x, read 0.1x of base input). */
+export declare const DEFAULT_CACHE_RATIOS: Readonly<CacheRatios>;
+/** Input cost of `usage` in uncached-equivalent tokens (output excluded). */
+export declare function uncachedEquivalentInput(usage: Usage, ratios?: CacheRatios): number;
+/**
+ * Mulberry32: a small seeded PRNG returning floats in [0, 1). Same seed,
+ * same stream, on every platform.
+ */
+export declare function seededRandom(seed: number): () => number;
+/** A point estimate with a percentile bootstrap confidence interval. */
+export interface Estimate {
+    estimate: number;
+    low: number;
+    high: number;
+    /** Resamples drawn. */
+    iterations: number;
+}
+/** Options shared by the bootstrap functions. */
+export interface BootstrapOpts {
+    /** Resamples. Default 5000. */
+    iterations?: number;
+    /** Two-sided level, e.g. 0.05 for a 95% interval. Default 0.05. */
+    alpha?: number;
+    /** PRNG seed. Default 1. */
+    seed?: number;
+}
+/**
+ * Paired bootstrap for the mean of per-task differences (treatment minus
+ * control on the same task). An interval that excludes zero is the bar for
+ * calling a difference real.
+ */
+export declare function pairedBootstrap(diffs: number[], opts?: BootstrapOpts): Estimate;
+/**
+ * Cluster bootstrap for the mean of per-task differences: resamples whole
+ * clusters (for example all tasks from one repository), because tasks in a
+ * cluster share causes and are not independent draws.
+ */
+export declare function clusteredPairedBootstrap(diffsByCluster: ReadonlyMap<string, number[]>, opts?: BootstrapOpts): Estimate;
+/** One task's outcome in one arm, for {@link costPerResolvedDelta}. */
+export interface ArmOutcome {
+    /** Dollars (or uncached-equivalent tokens) spent on the task. */
+    cost: number;
+    /** Whether the task was resolved. */
+    resolved: boolean;
+}
+/** Result of {@link costPerResolvedDelta}. */
+export interface CostPerResolvedDelta {
+    control: number;
+    treatment: number;
+    /** treatment minus control, with its interval. */
+    delta: Estimate;
+    /** (treatment minus control) / control, with its interval. Negative is a saving. */
+    relative: Estimate;
+}
+/**
+ * Cost per resolved task in two arms run on the same tasks, with a paired
+ * bootstrap over tasks (a task is resampled with both of its arm outcomes).
+ * `control[i]` and `treatment[i]` must be the same task. Resamples in which
+ * an arm resolves nothing are dropped; `iterations` reports how many were
+ * kept.
+ */
+export declare function costPerResolvedDelta(control: ArmOutcome[], treatment: ArmOutcome[], opts?: BootstrapOpts): CostPerResolvedDelta;
+/**
+ * pass@k: share of tasks with at least one success in their first k runs.
+ * NaN when no task has k runs (not measured, which is not the same as 0).
+ */
+export declare function passAtK(runsByTask: boolean[][], k: number): number;
+/**
+ * pass^k: share of tasks whose first k runs all succeed (consistency).
+ * NaN when no task has k runs.
+ */
+export declare function passHatK(runsByTask: boolean[][], k: number): number;
+//# sourceMappingURL=eval-stats.d.ts.map