hippo-memory 1.63.1 → 1.64.0

package/dist/db/continuity.js

@@ -1,4 +1,5 @@
 import { META_TABLE_DDL } from './meta.js';
+import { tableExists } from './tables.js';
 // Shared by migration v48 and the stamped-store self-heal below.
 export const MEMORY_QUARANTINE_DDL = `
     CREATE TABLE IF NOT EXISTS memory_quarantine (
@@ -27,7 +28,9 @@ const TASK_SNAPSHOTS_DDL = `
       updated_at TEXT NOT NULL,
       session_id TEXT,
       tenant_id TEXT NOT NULL DEFAULT 'default',
-      scope TEXT
+      scope TEXT,
+      owner_subject TEXT,
+      origin_project TEXT
     )
   `;
 const SESSION_EVENTS_DDL = `
@@ -60,7 +63,19 @@ const SESSION_HANDOFFS_DDL = `
       evidence_json TEXT,
       outcome TEXT,
       target_runtime TEXT,
-      card_id TEXT
+      card_id TEXT,
+      owner_subject TEXT,
+      origin_project TEXT
+    )
+  `;
+// Shared by migration v54 and the self-heal: a session id belongs to the first owner that binds it.
+export const SESSION_OWNERS_DDL = `
+    CREATE TABLE IF NOT EXISTS session_owners (
+      tenant_id TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      owner_subject TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      PRIMARY KEY (tenant_id, session_id)
     )
   `;
 const CARDS_DDL = `
@@ -128,6 +143,7 @@ const CONTINUITY_TABLE_DDL = [
     CARD_RUNS_DDL,
     CARD_COMMENTS_DDL,
     MEMORY_QUARANTINE_DDL,
+    SESSION_OWNERS_DDL,
 ];
 const CONTINUITY_INDEX_DDL = [
     `CREATE INDEX IF NOT EXISTS idx_task_snapshots_status_updated ON task_snapshots(status, updated_at DESC, id DESC)`,
@@ -145,19 +161,30 @@ const CONTINUITY_INDEX_DDL = [
     `CREATE INDEX IF NOT EXISTS idx_card_runs_tenant_card ON card_runs(tenant_id, card, started DESC)`,
     `CREATE INDEX IF NOT EXISTS idx_card_comments_tenant_card ON card_comments(tenant_id, card_id, created_at DESC)`,
     `CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_card ON session_handoffs(tenant_id, card_id, created_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_task_snapshots_owner ON task_snapshots(tenant_id, owner_subject, origin_project, status, updated_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_owner ON session_handoffs(tenant_id, owner_subject, origin_project, created_at DESC)`,
 ];
+// A client retry carries the same request id, so a repeat finds the earlier row instead of writing again.
+const REQUEST_INDEX_DDL = {
+    compactions: `CREATE UNIQUE INDEX IF NOT EXISTS idx_compactions_request ON compactions(tenant_id, request_id) WHERE request_id IS NOT NULL`,
+    failure_log: `CREATE UNIQUE INDEX IF NOT EXISTS idx_failure_log_request ON failure_log(tenant_id, request_id) WHERE request_id IS NOT NULL`,
+};
 // Lives with the other re-asserted DDL so the required-object list below derives from one place.
 export const MEMORIES_FTS_DDL = `CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(id UNINDEXED, content, tags)`;
-const CREATED_NAME = /CREATE\s+(?:VIRTUAL\s+)?(?:TABLE|INDEX)\s+IF\s+NOT\s+EXISTS\s+(\w+)/gi;
+const CREATED_NAME = /CREATE\s+(?:VIRTUAL\s+|UNIQUE\s+)?(?:TABLE|INDEX)\s+IF\s+NOT\s+EXISTS\s+(\w+)/gi;
 /** Names of every table and index a `CREATE ... IF NOT EXISTS` in `ddl` makes. */
 export function createdObjectNames(ddl) {
     return [...ddl.matchAll(CREATED_NAME)].map((m) => m[1]);
 }
 /** Every object runMigrations re-asserts on a stamped store; the open fast path requires all of them. */
-export const REQUIRED_SCHEMA_OBJECTS = Object.freeze([META_TABLE_DDL, ...CONTINUITY_TABLE_DDL, ...CONTINUITY_INDEX_DDL, MEMORIES_FTS_DDL].flatMap(createdObjectNames));
+export const REQUIRED_SCHEMA_OBJECTS = Object.freeze([META_TABLE_DDL, ...CONTINUITY_TABLE_DDL, ...CONTINUITY_INDEX_DDL, ...Object.values(REQUEST_INDEX_DDL), MEMORIES_FTS_DDL].flatMap(createdObjectNames));
 // After the loop: tenant_id (v16) and scope (v23) do not exist yet on a genuine old store.
 export function ensureContinuityIndexes(db) {
     for (const ddl of CONTINUITY_INDEX_DDL)
         db.exec(ddl);
+    // A store that lost one of these tables still opens, so its hooks can log the failed step and run the rest.
+    for (const [table, ddl] of Object.entries(REQUEST_INDEX_DDL))
+        if (tableExists(db, table))
+            db.exec(ddl);
 }
 //# sourceMappingURL=continuity.js.map

package/dist/db/meta.d.ts

@@ -5,5 +5,7 @@ export declare function getSchemaVersion(db: DatabaseSyncLike): number;
 export declare function setSchemaVersion(db: DatabaseSyncLike, version: number): void;
 export declare function getMeta(db: DatabaseSyncLike, key: string, fallback?: string): string;
 export declare function setMeta(db: DatabaseSyncLike, key: string, value: string): void;
+/** Raise min_compatible_binary to `version`; never lowers it, since an older floor would let back in a binary a newer write already shut out. */
+export declare function raiseMinBinary(db: DatabaseSyncLike, version: string): void;
 export declare function isFtsAvailable(db: DatabaseSyncLike): boolean;
 //# sourceMappingURL=meta.d.ts.map

package/dist/db/meta.js

@@ -1,3 +1,4 @@
+import { compareSemver } from '../version.js';
 import { tableExists } from './tables.js';
 export const META_TABLE_DDL = `
     CREATE TABLE IF NOT EXISTS meta (
@@ -30,6 +31,12 @@ export function getMeta(db, key, fallback = '') {
 export function setMeta(db, key, value) {
     db.prepare(`INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value`).run(key, value);
 }
+/** Raise min_compatible_binary to `version`; never lowers it, since an older floor would let back in a binary a newer write already shut out. */
+export function raiseMinBinary(db, version) {
+    const existing = getMeta(db, 'min_compatible_binary');
+    if (!existing || compareSemver(version, existing) > 0)
+        setMeta(db, 'min_compatible_binary', version);
+}
 export function isFtsAvailable(db) {
     return getMeta(db, 'fts5_available', '0') === '1';
 }

package/dist/db/migrate.js

@@ -179,13 +179,12 @@ export function repairFtsDrift(db) {
     const counts = ftsRowCounts(db);
     if (counts === null || counts.memories === counts.fts)
         return false;
+    // NOT IN reads the UNINDEXED id column once, not once per memory; one NULL id would make NOT IN match nothing.
     db.exec(`
     INSERT INTO memories_fts(id, content, tags)
     SELECT m.id, m.content, m.tags_json
     FROM memories m
-    WHERE NOT EXISTS (
-      SELECT 1 FROM memories_fts f WHERE f.id = m.id
-    )
+    WHERE m.id NOT IN (SELECT id FROM memories_fts WHERE id IS NOT NULL)
   `);
     db.exec(`
     DELETE FROM memories_fts

package/dist/db/migrations/index.d.ts

@@ -1,5 +1,5 @@
 import type { Migration } from './types.js';
-export declare const CURRENT_SCHEMA_VERSION = 52;
+export declare const CURRENT_SCHEMA_VERSION = 54;
 /** Every schema migration in version order; runMigrations applies each one above the stored version. */
 export declare const MIGRATIONS: Migration[];
 //# sourceMappingURL=index.d.ts.map

package/dist/db/migrations/index.js

@@ -50,7 +50,9 @@ import { v49 } from './v49.js';
 import { v50 } from './v50.js';
 import { v51 } from './v51.js';
 import { v52 } from './v52.js';
-export const CURRENT_SCHEMA_VERSION = 52;
+import { v53 } from './v53.js';
+import { v54 } from './v54.js';
+export const CURRENT_SCHEMA_VERSION = 54;
 /** Every schema migration in version order; runMigrations applies each one above the stored version. */
 export const MIGRATIONS = [
     v01,
@@ -105,5 +107,7 @@ export const MIGRATIONS = [
     v50,
     v51,
     v52,
+    v53,
+    v54,
 ];
 //# sourceMappingURL=index.js.map

package/dist/db/migrations/v39.js

@@ -1,7 +1,7 @@
 import * as os from 'os';
 import * as path from 'path';
-import { compareSemver } from '../../version.js';
 import { deriveOriginProject, originFromSource, isGlobalStoreRoot } from '../../project-identity.js';
+import { raiseMinBinary } from '../meta.js';
 import { tableHasColumn } from '../tables.js';
 export const v39 = {
     version: 39,
@@ -48,12 +48,7 @@ export const v39 = {
         // this DB would ignore origin_project and the secret veto and resume
         // injecting cross-project rows. 1.24.0 is the first version with the
         // isolation behavior. Forward-only - never lower an existing minimum.
-        // SAFETY: this get() result's shape matches the single `value` column
-        // named in the SELECT above.
-        const existingMin = db.prepare(`SELECT value FROM meta WHERE key = 'min_compatible_binary'`).get()?.value;
-        if (!existingMin || compareSemver('1.24.0', existingMin) > 0) {
-            db.prepare(`INSERT INTO meta(key, value) VALUES('min_compatible_binary', ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value`).run('1.24.0');
-        }
+        raiseMinBinary(db, '1.24.0');
     },
 };
 //# sourceMappingURL=v39.js.map

package/dist/db/migrations/v53.d.ts

@@ -0,0 +1,3 @@
+import type { Migration } from './types.js';
+export declare const v53: Migration;
+//# sourceMappingURL=v53.d.ts.map

package/dist/db/migrations/v53.js

@@ -0,0 +1,16 @@
+import { tableHasColumn, tableExists } from '../tables.js';
+export const v53 = {
+    version: 53,
+    up: (db) => {
+        // Self-service keys record who minted them and when they stop working; both stay null for keys minted before this.
+        // No floor raise here: a store with no expiring key is safe for older binaries, so the first expiring key raises it.
+        if (tableExists(db, 'api_keys')) {
+            if (!tableHasColumn(db, 'api_keys', 'owner_subject'))
+                db.exec(`ALTER TABLE api_keys ADD COLUMN owner_subject TEXT`);
+            if (!tableHasColumn(db, 'api_keys', 'expires_at'))
+                db.exec(`ALTER TABLE api_keys ADD COLUMN expires_at TEXT`);
+            db.exec(`CREATE INDEX IF NOT EXISTS idx_api_keys_live_owner ON api_keys(tenant_id, owner_subject) WHERE revoked_at IS NULL`);
+        }
+    },
+};
+//# sourceMappingURL=v53.js.map

package/dist/db/migrations/v54.d.ts

@@ -0,0 +1,3 @@
+import type { Migration } from './types.js';
+export declare const v54: Migration;
+//# sourceMappingURL=v54.d.ts.map

package/dist/db/migrations/v54.js

@@ -0,0 +1,25 @@
+import { SESSION_OWNERS_DDL } from '../continuity.js';
+import { tableHasColumn, tableExists } from '../tables.js';
+const OWNER_COLUMNS = [
+    ['task_snapshots', 'owner_subject'],
+    ['task_snapshots', 'origin_project'],
+    ['session_handoffs', 'owner_subject'],
+    ['session_handoffs', 'origin_project'],
+    ['failure_log', 'owner_subject'],
+    ['failure_log', 'origin_project'],
+    ['compactions', 'request_id'],
+    ['failure_log', 'request_id'],
+];
+export const v54 = {
+    version: 54,
+    up: (db) => {
+        // Rows from before this stay NULL: no backfill, so they never match an owner's key.
+        // No floor raise here: the first session bind or owner snapshot raises it, so an unused store stays open to older binaries.
+        for (const [t, c] of OWNER_COLUMNS) {
+            if (tableExists(db, t) && !tableHasColumn(db, t, c))
+                db.exec(`ALTER TABLE ${t} ADD COLUMN ${c} TEXT`);
+        }
+        db.exec(SESSION_OWNERS_DDL);
+    },
+};
+//# sourceMappingURL=v54.js.map

package/dist/db/open.d.ts

@@ -11,8 +11,19 @@ export declare function withSharedStoreHandles<T>(fn: () => T | Promise<T>, opts
 }): Promise<T>;
 /** Lock wait inside an HTTP request: SQLite waits synchronously, so a long wait would stall every other request on the event loop. */
 export declare const SERVER_DB_WAIT_MS = 250;
+/** Lock wait for each of sleep's short write transactions, even inside a server request: a run stops only on a writer that holds the lock longer. */
+export declare const SLEEP_DB_WAIT_MS = 5000;
 /** Runs `fn` so that every store opened inside it, across awaits, waits at most `busyWaitMs` for a lock unless the open passes its own. */
 export declare function withBusyWait<T>(busyWaitMs: number, fn: () => T): T;
+/** The lock wait an open here would get without its own `busyWaitMs`, in openHippoDb's order; undefined outside both scopes. */
+export declare function scopedBusyWait(): number | undefined;
+/** Thrown by a hippo.db open inside a request served from another store: the code path is not ported to the store port yet. */
+export declare class SqliteBlockedError extends Error {
+    readonly storeKind: string;
+    constructor(storeKind: string);
+}
+/** Runs `fn` so that every hippo.db open inside it, across awaits, throws; otherwise a missed port would create and write a hippo.db nobody reads. */
+export declare function withSqliteBlocked<T>(storeKind: string, fn: () => T): T;
 /** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
 export declare function openHippoDb(hippoRoot: string, opts?: {
     busyWaitMs?: number;

package/dist/db/open.js

@@ -54,13 +54,39 @@ export async function withSharedStoreHandles(fn, opts) {
 }
 /** Lock wait inside an HTTP request: SQLite waits synchronously, so a long wait would stall every other request on the event loop. */
 export const SERVER_DB_WAIT_MS = 250;
+/** Lock wait for each of sleep's short write transactions, even inside a server request: a run stops only on a writer that holds the lock longer. */
+export const SLEEP_DB_WAIT_MS = 5000;
 const scopedBusyWaitMs = new AsyncLocalStorage();
 /** Runs `fn` so that every store opened inside it, across awaits, waits at most `busyWaitMs` for a lock unless the open passes its own. */
 export function withBusyWait(busyWaitMs, fn) {
     return scopedBusyWaitMs.run(busyWaitMs, fn);
 }
+/** The lock wait an open here would get without its own `busyWaitMs`, in openHippoDb's order; undefined outside both scopes. */
+export function scopedBusyWait() {
+    return shareBusyWaitMs ?? scopedBusyWaitMs.getStore();
+}
+/** Thrown by a hippo.db open inside a request served from another store: the code path is not ported to the store port yet. */
+export class SqliteBlockedError extends Error {
+    storeKind;
+    constructor(storeKind) {
+        super(`hippo.db is not opened while the '${storeKind}' store serves this request; this code path is not ported to the store yet`);
+        this.storeKind = storeKind;
+        this.name = 'SqliteBlockedError';
+    }
+}
+const sqliteBlockedBy = new AsyncLocalStorage();
+/** Runs `fn` so that every hippo.db open inside it, across awaits, throws; otherwise a missed port would create and write a hippo.db nobody reads. */
+export function withSqliteBlocked(storeKind, fn) {
+    return sqliteBlockedBy.run(storeKind, fn);
+}
+function assertSqliteAllowed() {
+    const storeKind = sqliteBlockedBy.getStore();
+    if (storeKind !== undefined)
+        throw new SqliteBlockedError(storeKind);
+}
 /** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
 export function openHippoDb(hippoRoot, opts) {
+    assertSqliteAllowed();
     if (shareDepth === 0)
         return openOwnHippoDb(hippoRoot, { busyWaitMs: opts?.busyWaitMs ?? scopedBusyWaitMs.getStore() });
     const busyWaitMs = opts?.busyWaitMs ?? shareBusyWaitMs ?? scopedBusyWaitMs.getStore();
@@ -121,6 +147,7 @@ function openOwnHippoDb(hippoRoot, opts) {
 }
 /** Open an existing store without changing it: no mkdir, WAL switch, migration or mirror cleanup. Throws when hippo.db is missing. */
 export function openHippoDbReadOnly(hippoRoot) {
+    assertSqliteAllowed();
     const db = new DatabaseSync(getHippoDbPath(hippoRoot), { readOnly: true });
     try {
         db.exec('PRAGMA busy_timeout = 5000');

package/dist/db/tables.d.ts

@@ -1,4 +1,6 @@
 import type { DatabaseSyncLike } from './sqlite.js';
+/** Column names of one table; empty when the table is missing. */
+export declare function tableColumns(db: DatabaseSyncLike, tableName: string): Set<string>;
 export declare function tableHasColumn(db: DatabaseSyncLike, tableName: string, columnName: string): boolean;
 export declare function tableExists(db: DatabaseSyncLike, tableName: string): boolean;
 /** Row count of one table; null when the table is missing or unreadable, which callers show as unknown. */

package/dist/db/tables.js

@@ -1,9 +1,13 @@
-export function tableHasColumn(db, tableName, columnName) {
+/** Column names of one table; empty when the table is missing. */
+export function tableColumns(db, tableName) {
     if (!/^[a-z_]+$/i.test(tableName))
         throw new Error(`Invalid table name: ${tableName}`);
     // SAFETY: rows' shape matches PRAGMA table_info's documented `name` column.
     const rows = db.prepare(`PRAGMA table_info(${tableName})`).all();
-    return rows.some((row) => row.name === columnName);
+    return new Set(rows.flatMap((row) => (row.name === undefined ? [] : [row.name])));
+}
+export function tableHasColumn(db, tableName, columnName) {
+    return tableColumns(db, tableName).has(columnName);
 }
 export function tableExists(db, tableName) {
     if (!/^[a-z_]+$/i.test(tableName))

package/dist/db.d.ts

@@ -1,7 +1,7 @@
 export type { DatabaseSyncLike } from './db/sqlite.js';
-export { isSqliteBusy, STORE_BUSY_MESSAGE, execWithBusyRetry } from './db/busy.js';
+export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWithBusyRetry, withWriteScope } from './db/busy.js';
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
 export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
 export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, withBusyWait, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, withBusyWait, scopedBusyWait, SqliteBlockedError, withSqliteBlocked, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
 //# sourceMappingURL=db.d.ts.map

package/dist/db.js

@@ -1,6 +1,6 @@
-export { isSqliteBusy, STORE_BUSY_MESSAGE, execWithBusyRetry } from './db/busy.js';
+export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWithBusyRetry, withWriteScope } from './db/busy.js';
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
 export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
 export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, withBusyWait, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, withBusyWait, scopedBusyWait, SqliteBlockedError, withSqliteBlocked, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
 //# sourceMappingURL=db.js.map

package/dist/doctor.d.ts

@@ -19,7 +19,7 @@ export interface DoctorReport {
 /** Inputs for {@link runDoctor}; defaults come from the process. */
 export interface DoctorOpts {
     cwd?: string;
-    /** Home directory used to find agent configuration (~/.claude, ~/.codex). */
+    /** Home directory used to find agent configuration (~/.claude unless CLAUDE_CONFIG_DIR is set, ~/.codex unless CODEX_HOME is). */
     home?: string;
     version: string;
     nodeVersion?: string;

package/dist/doctor.js

@@ -13,10 +13,12 @@ import { isInitialized } from './store/open.js';
 import { loadConfig } from './config.js';
 import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion, countTableRows, ftsRowCounts, IncompatibleBinaryError } from './db.js';
 import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './compaction-record.js';
+import { SPOOL_DIR, spoolCounts } from './compaction-spool.js';
 import { isEmbeddingAvailable } from './local-embedding.js';
-import { CODEX_TRUST_LINE, codexHomeDir, isCodexPresent, isJsonObject } from './hooks/shared.js';
+import { CODEX_TRUST_LINE, claudeConfigDir, codexHomeDir, isCodexPresent, isJsonObject } from './hooks/shared.js';
 import { planProjectRepair } from './project-merge.js';
 import { resolveTenantId } from './tenant.js';
+import { readJsonFile } from './json.js';
 /** Minimum Node.js version hippo supports (package.json engines). */
 export const MIN_NODE = '22.16.0';
 function versionAtLeast(actual, min) {
@@ -32,8 +34,7 @@ function versionAtLeast(actual, min) {
 }
 function readJson(file) {
     try {
-        // SAFETY: JSON.parse returns a JSON value by definition.
-        return JSON.parse(fs.readFileSync(file, 'utf8'));
+        return readJsonFile(file);
     }
     catch {
         // A missing or corrupt file is the finding doctor reports, so null is the answer.
@@ -101,8 +102,17 @@ function sleepCheck(db, now) {
         return { id: 'sleep', status: 'info', detail: `sleep history unavailable (${message})` };
     }
 }
-/** Compaction records the PostCompact hook left unfinished, which `hippo sleep` replays. */
-function compactionsCheck(db, now) {
+/** Spool counts in their own try, so a spool that cannot be read never hides the database counts. */
+function readSpool(store, now) {
+    try {
+        return { counts: spoolCounts(store, now, REPLAY_AFTER_MS), unread: '' };
+    }
+    catch (err) {
+        return { counts: { waiting: 0, stale: 0, bad: 0 }, unread: `; spool not read: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/** Compaction records the PostCompact hook left unfinished and spool files a replay has not finished, which `hippo sleep` replays. */
+function compactionsCheck(db, store, now) {
     const stuckBefore = new Date(now.getTime() - REPLAY_AFTER_MS).toISOString();
     const transcriptFloor = new Date(now.getTime() - TRANSCRIPT_FILL_WINDOW_MS).toISOString();
     try {
@@ -115,14 +125,20 @@ function compactionsCheck(db, now) {
         const summarised = Number(row?.summarised ?? 0);
         const started = Number(row?.started ?? 0);
         const stuck = summarised + started;
-        if (stuck === 0)
-            return { id: 'compactions', status: 'pass', detail: `${total} compaction${total === 1 ? '' : 's'} recorded, none stuck` };
-        return {
-            id: 'compactions',
-            status: 'warn',
-            detail: `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes (${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`,
-            fix: 'hippo sleep   (replays them)',
-        };
+        const { counts: spool, unread } = readSpool(store, now);
+        const spooled = spool.waiting + spool.stale + spool.bad > 0;
+        const recorded = `${total} compaction${total === 1 ? '' : 's'} recorded, none stuck`;
+        if (stuck === 0 && !spooled && unread === '')
+            return { id: 'compactions', status: 'pass', detail: recorded };
+        const fix = [
+            stuck + spool.waiting + spool.stale > 0 ? 'hippo sleep   (replays them)' : '',
+            spool.bad > 0 ? `open the .bad files in ${path.join(store, SPOOL_DIR)}, save what you still need with hippo remember, then delete them` : '',
+        ].filter((s) => s !== '');
+        const unfinished = stuck === 0
+            ? `${recorded} in the store`
+            : `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes (${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`;
+        const note = spooled ? `; spool: ${spool.waiting} waiting, ${spool.stale} left by a replay that stopped, ${spool.bad} .bad` : '';
+        return { id: 'compactions', status: 'warn', detail: `${unfinished}${note}${unread}`, fix: fix.join('; ') };
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -241,7 +257,7 @@ function databaseChecks(store, now) {
         checks.push(tokensCheck(db, since));
         checks.push(failuresCheck(db, since, have));
         checks.push(sleepCheck(db, now));
-        checks.push(compactionsCheck(db, now));
+        checks.push(compactionsCheck(db, store, now));
     }
     catch (err) {
         checks.push({
@@ -267,7 +283,7 @@ const CLAUDE_CODE_HOOKS = [
     ['hippo capture-error', 'failed-tool capture'],
 ];
 function claudeCodeCheck(home) {
-    const claudeDir = path.join(home, '.claude');
+    const claudeDir = claudeConfigDir(home);
     if (!fs.existsSync(claudeDir)) {
         return { id: 'claude-code', status: 'info', detail: 'Claude Code not found; other agents can use hippo over MCP (hippo mcp)' };
     }

package/dist/dormant.d.ts

@@ -19,8 +19,9 @@
  */
 import type { DatabaseSyncLike } from './db.js';
 import type { MemoryEntry } from './memory.js';
-/** Why a memory went dormant: sleep's decay pass, an imported agent memory whose note was deleted, or `hippo projects repair` splitting a two-project merge. */
-export type DormantReason = 'decay' | 'source-deleted' | 'project-repair';
+import type { SqlFragment } from './recall-scope.js';
+/** Why a memory went dormant: sleep's decay pass, an imported agent memory whose note was deleted, `hippo projects repair` splitting a two-project merge, or `hippo audit repair` setting aside an automatic memory with a certain defect. */
+export type DormantReason = 'decay' | 'source-deleted' | 'project-repair' | 'quality-repair';
 /** 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. */
@@ -39,7 +40,7 @@ export interface DormantMemory {
     tags: string[];
     /** Live strength when it went dormant. */
     strength: number;
-    /** Why it went dormant (`decay` or `source-deleted`). */
+    /** Why it went dormant: one of the {@link DormantReason} values. */
     reason: string;
     /** ISO time it went dormant. */
     dormantAt: string;
@@ -57,8 +58,8 @@ export interface ListDormantOpts {
  * 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 tenant's dormant memories whose scope `admit` passes, newest first, optionally filtered by search terms. */
+export declare function listDormantRows(db: DatabaseSyncLike, tenantId: string, opts?: ListDormantOpts, admit?: SqlFragment): DormantMemory[];
 /** A dormant memory's stored snapshot plus when and why it went dormant. */
 export interface DormantSnapshot {
     entry: MemoryEntry;
@@ -77,21 +78,16 @@ export declare function listDormantSnapshots(db: DatabaseSyncLike, tenantId: str
 export declare function dormantSnapshotsBySourcePrefix(db: DatabaseSyncLike, tenantId: string, prefix: string): DormantSnapshot[];
 /** Put `entry` in place of a tenant's dormant memory `id`, keeping when and why that one went dormant. */
 export declare function replaceDormantEntry(db: DatabaseSyncLike, tenantId: string, id: string, entry: MemoryEntry): void;
-/** 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;
+/** Whether a tenant has a dormant memory with this id whose scope `admit` passes (snapshot readable or not). */
+export declare function hasDormantRow(db: DatabaseSyncLike, tenantId: string, id: string, admit?: SqlFragment): 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;
+/** Deletes the tenant's dormant copies of a rejected digest whose snapshot scope `inReach` admits, so the value cannot linger; returns their ids. */
+export declare function purgeDormantByDigest(db: DatabaseSyncLike, tenantId: string, digest: string, inReach: (scope: string | null) => boolean): string[];
+export interface DormantKey {
+    readonly tenantId: string;
+    readonly id: string;
+}
+export declare function expiredDormantKeys(db: DatabaseSyncLike, cutoffIso: string): DormantKey[];
+export declare function deleteExpiredDormantRow(db: DatabaseSyncLike, key: DormantKey, cutoffIso: string): number;
 //# sourceMappingURL=dormant.d.ts.map

package/dist/dormant.js

@@ -49,8 +49,11 @@ function rowToDormantMemory(row) {
         dormantAt: row.dormant_at,
     };
 }
-/** A tenant's dormant memories, newest first, optionally filtered by search terms. */
-export function listDormantRows(db, tenantId, opts = {}) {
+// The snapshot's scope as a `scope` column, so recall-scope's SQL fragments read it as they read memories.scope.
+const DORMANT_WITH_SCOPE = `(SELECT *, CASE WHEN json_valid(entry_json) THEN json_extract(entry_json, '$.scope') END AS scope FROM dormant_memories)`;
+const EVERY_SCOPE = { sql: '1', params: [] };
+/** A tenant's dormant memories whose scope `admit` passes, newest first, optionally filtered by search terms. */
+export function listDormantRows(db, tenantId, opts = {}, admit = EVERY_SCOPE) {
     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)
@@ -58,10 +61,10 @@ export function listDormantRows(db, tenantId, opts = {}) {
     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}
+       FROM ${DORMANT_WITH_SCOPE}
+      WHERE tenant_id = ? AND ${admit.sql}${termClauses}
       ORDER BY dormant_at DESC, id ASC
-      LIMIT ?`).all(tenantId, ...terms.map((t) => `%${escapeLike(t)}%`), limit);
+      LIMIT ?`).all(tenantId, ...admit.params, ...terms.map((t) => `%${escapeLike(t)}%`), limit);
     return rows.map(rowToDormantMemory);
 }
 /**
@@ -99,45 +102,36 @@ export function replaceDormantEntry(db, tenantId, id, entry) {
     db.prepare(`UPDATE dormant_memories SET id = ?, content = ?, entry_json = ? WHERE tenant_id = ? AND id = ?`)
         .run(entry.id, entry.content, JSON.stringify(entry), tenantId, id);
 }
-/** 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;
+/** Whether a tenant has a dormant memory with this id whose scope `admit` passes (snapshot readable or not). */
+export function hasDormantRow(db, tenantId, id, admit = EVERY_SCOPE) {
+    return db.prepare(`SELECT 1 FROM ${DORMANT_WITH_SCOPE} WHERE tenant_id = ? AND id = ? AND ${admit.sql}`).get(tenantId, id, ...admit.params) !== 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);
+/** Deletes the tenant's dormant copies of a rejected digest whose snapshot scope `inReach` admits, so the value cannot linger; returns their ids. */
+export function purgeDormantByDigest(db, tenantId, digest, inReach) {
+    // SAFETY: rows' shape matches the three columns named in the SELECT.
+    const rows = db.prepare(`SELECT id, content, CASE WHEN json_valid(entry_json) THEN json_extract(entry_json, '$.scope') END AS scope
+       FROM dormant_memories WHERE tenant_id = ?`).all(tenantId);
     const removed = [];
     for (const row of rows) {
-        if (rejectionDigest(row.content) !== digest)
+        if (rejectionDigest(row.content) !== digest || !inReach(row.scope))
             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);
+export function expiredDormantKeys(db, cutoffIso) {
+    const sql = `SELECT tenant_id AS tenantId, id FROM dormant_memories WHERE dormant_at < ?`;
+    // SAFETY: rows' shape matches the two columns named in the SELECT.
+    return db.prepare(sql).all(cutoffIso);
 }
-/**
- * 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);
+export function deleteExpiredDormantRow(db, key, cutoffIso) {
+    const sql = `DELETE FROM dormant_memories WHERE tenant_id = ? AND id = ? AND dormant_at < ?`;
+    return Number(db.prepare(sql).run(key.tenantId, key.id, cutoffIso).changes ?? 0);
 }
 //# sourceMappingURL=dormant.js.map

package/dist/entry/json-hooks.d.ts

@@ -0,0 +1,3 @@
+export { installJsonHooks, resolveJsonHookPaths, uninstallJsonHooks, writeSettingsFile, type InstallResult, type JsonHookPaths } from '../hooks/json-hooks.js';
+export { readJsonFile } from '../json.js';
+//# sourceMappingURL=json-hooks.d.ts.map

package/dist/entry/json-hooks.js

@@ -0,0 +1,4 @@
+// The hippo-memory/json-hooks subpath: only what the changelog publishes, so the module's other exports stay internal.
+export { installJsonHooks, resolveJsonHookPaths, uninstallJsonHooks, writeSettingsFile } from '../hooks/json-hooks.js';
+export { readJsonFile } from '../json.js';
+//# sourceMappingURL=json-hooks.js.map

package/dist/entry/project-identity.d.ts

@@ -0,0 +1,2 @@
+export { MAX_PROJECT_ALIASES, MCP_PROJECT_SCOPED_HEADER, resolveProjectIdentity, type ProjectIdentity, type ResolveProjectIdentityOpts } from '../project-identity.js';
+//# sourceMappingURL=project-identity.d.ts.map

package/dist/entry/project-identity.js

@@ -0,0 +1,3 @@
+// The hippo-memory/project-identity subpath: only what the changelog publishes, so the module's other exports stay internal.
+export { MAX_PROJECT_ALIASES, MCP_PROJECT_SCOPED_HEADER, resolveProjectIdentity } from '../project-identity.js';
+//# sourceMappingURL=project-identity.js.map