hippo-memory 1.44.0 → 1.45.0

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/extract.d.ts

@@ -8,6 +8,8 @@ export interface ExtractOptions {
     apiKey: string;
     model?: string;
     fetcher?: typeof fetch;
+    /** Told why a call produced nothing, so callers can surface it instead of guessing. */
+    onError?: (msg: string) => void;
 }
 export declare function extractFacts(text: string, opts: ExtractOptions): Promise<ExtractedFact[]>;
 export declare function storeExtractedFacts(hippoRoot: string, source: MemoryEntry, facts: ExtractedFact[]): MemoryEntry[];

package/dist/extract.js

@@ -1,6 +1,7 @@
 import { Layer, createMemory } from './memory.js';
 import { writeEntry } from './store.js';
 import { RejectedValueError } from './rejection.js';
+import { redactSecrets } from './secret-detect.js';
 function isJsonString(value) {
     return typeof value === 'string';
 }
@@ -31,15 +32,18 @@ export async function extractFacts(text, opts) {
             body: JSON.stringify({
                 model,
                 max_tokens: 1200,
-                messages: [{ role: 'user', content: EXTRACTION_PROMPT + text }],
+                messages: [{ role: 'user', content: EXTRACTION_PROMPT + redactSecrets(text) }],
             }),
         });
     }
-    catch {
+    catch (err) {
+        opts.onError?.(`request failed: ${err instanceof Error ? err.message : String(err)}`);
         return [];
     }
-    if (!res.ok)
+    if (!res.ok) {
+        opts.onError?.(`HTTP ${res.status}`);
         return [];
+    }
     try {
         const data = await res.json();
         const raw = data.content?.[0]?.text?.trim() ?? '';
@@ -69,7 +73,8 @@ export async function extractFacts(text, opts) {
         }
         return facts;
     }
-    catch {
+    catch (err) {
+        opts.onError?.(`unparseable response: ${err instanceof Error ? err.message : String(err)}`);
         return [];
     }
 }

package/dist/mcp/server.js

@@ -10,9 +10,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { createMemory, Layer, calculateStrength, } from '../memory.js';
-import { hybridSearch, physicsSearch, markRetrieved } from '../search.js';
-import { isRecallBoostAblated, evalNow } from '../ablation.js';
-import { loadAllEntries, writeEntry, readEntry, loadFreshActiveTaskSnapshot, listMemoryConflicts, resolveConflict, RECALL_DEFAULT_DENY_SCOPES } from '../store.js';
+import { hybridSearch, physicsSearch } from '../search.js';
+import { evalNow } from '../ablation.js';
+import { loadAllEntries, writeEntry, strengthenRetrieved, readEntry, loadFreshActiveTaskSnapshot, listMemoryConflicts, resolveConflict, RECALL_DEFAULT_DENY_SCOPES, countCreatedSinceLastSleep } from '../store.js';
 import { shareMemory, listPeers, getGlobalRoot } from '../shared.js';
 import { consolidate } from '../consolidate.js';
 import { execSync } from 'child_process';
@@ -359,6 +359,7 @@ const TOOLS = [
 // `${tenantId}:default` if a McpContext is constructed in tests without a
 // pid-bound transport.
 const lastRecalledIds = new Map();
+const autoSleepInFlight = new Set();
 function resolveClientKey(ctx) {
     if (ctx?.clientKey)
         return ctx.clientKey;
@@ -527,15 +528,9 @@ async function executeTool(name, args, ctx) {
                     closeHippoDb(dbForBoost);
                 }
             }
-            // Mark retrieved and persist
-            const retrieved = markRetrieved(results.map((r) => r.entry));
-            // EVAL-ONLY ablation (see ablation.ts): skip persistence under the recall
-            // flag; ids below stay populated for outcome attribution.
-            if (!isRecallBoostAblated()) {
-                for (const entry of retrieved)
-                    writeEntry(hippoRoot, entry, { actor: ctx?.actor ?? 'mcp' });
-            }
-            lastRecalledIds.set(resolveClientKey(ctx), retrieved.map((e) => e.id));
+            const retrievedIds = results.map((r) => r.entry.id);
+            strengthenRetrieved(hippoRoot, retrievedIds);
+            lastRecalledIds.set(resolveClientKey(ctx), retrievedIds);
             // v0.33 / J1 — MCP per-pipeline anchoring detector. UNLIKE J3.2's
             // planningFallacyHint (which is pipeline-invariant because it
             // depends only on queryText + predictions table state), the
@@ -902,22 +897,17 @@ async function executeTool(name, args, ctx) {
                 tags,
             });
             const entry = readEntry(hippoRoot, result.id, tenantId);
-            // Auto-sleep check
-            if (config.autoSleep.enabled) {
-                const allEntries = loadAllEntries(hippoRoot, tenantId);
-                const recentCount = allEntries.filter((e) => {
-                    const age = (Date.now() - new Date(e.created).getTime()) / (1000 * 60 * 60);
-                    return age < 24; // created in last 24 hours
-                }).length;
-                if (recentCount >= config.autoSleep.threshold) {
-                    // Fire-and-forget by design (never block the remember response), but
-                    // an unhandled rejection here can kill the MCP server process — any
-                    // consolidate error (DB contention, or the memoryValue fail-loud
-                    // throw) must land as a logged line, not a crash.
-                    consolidate(hippoRoot).catch((err) => {
-                        console.error(`auto-sleep consolidate failed: ${err instanceof Error ? err.message : err}`);
-                    });
-                }
+            // Auto-sleep: one run per store at a time, triggered by what arrived since the last one.
+            if (config.autoSleep.enabled &&
+                !autoSleepInFlight.has(hippoRoot) &&
+                countCreatedSinceLastSleep(hippoRoot, tenantId) >= config.autoSleep.threshold) {
+                autoSleepInFlight.add(hippoRoot);
+                // Fire-and-forget (never block the response); an unhandled rejection would kill the server, so log it.
+                consolidate(hippoRoot)
+                    .catch((err) => {
+                    console.error(`auto-sleep consolidate failed (tenant ${tenantId}): ${err instanceof Error ? err.message : err}`);
+                })
+                    .finally(() => autoSleepInFlight.delete(hippoRoot));
             }
             const halfLife = entry?.half_life_days ?? config.defaultHalfLifeDays;
             const tagStr = entry?.tags.join(', ') || tags.join(', ') || 'none';
@@ -1000,14 +990,9 @@ async function executeTool(name, args, ctx) {
             const results = usePhysicsCtx
                 ? await physicsSearch(query, entries, { budget, hippoRoot, physicsConfig: config.physics })
                 : await hybridSearch(query, entries, { budget, hippoRoot });
-            const retrieved = markRetrieved(results.map((r) => r.entry));
-            // EVAL-ONLY ablation (see ablation.ts): skip persistence under the recall
-            // flag; ids below stay populated for outcome attribution.
-            if (!isRecallBoostAblated()) {
-                for (const entry of retrieved)
-                    writeEntry(hippoRoot, entry, { actor: ctx?.actor ?? 'mcp' });
-            }
-            lastRecalledIds.set(resolveClientKey(ctx), retrieved.map((e) => e.id));
+            const retrievedIds = results.map((r) => r.entry.id);
+            strengthenRetrieved(hippoRoot, retrievedIds);
+            lastRecalledIds.set(resolveClientKey(ctx), retrievedIds);
             // DF1 (docs/plans/2026-08-23-df1-snapshot-lifecycle.md, T2): bounded
             // read, no session id available on this surface (freshness bound
             // only) — an orphaned snapshot must age out here too, not just on the

package/dist/memory.d.ts

@@ -203,6 +203,9 @@ export declare function confidenceLabel(entry: MemoryEntry, now?: Date): {
  * returns 'stale'. Otherwise returns the stored confidence value.
  */
 export declare function resolveConfidence(entry: MemoryEntry, now?: Date): ConfidenceLevel;
+export declare const DEFAULT_HALF_LIFE_DAYS = 7;
+export declare const AUTO_DELETABLE_SQL = "pinned = 0 AND kind != 'raw'";
+export declare function canAutoDelete(entry: Pick<MemoryEntry, 'pinned' | 'kind'>): boolean;
 /**
  * Create a new memory entry with defaults.
  */

package/dist/memory.js

@@ -296,6 +296,12 @@ export function confidenceLabel(entry, now = evalNow()) {
 export function resolveConfidence(entry, now = evalNow()) {
     return isAgedOut(entry, now) ? 'stale' : entry.confidence;
 }
+export const DEFAULT_HALF_LIFE_DAYS = 7;
+// Pinned means keep; raw rows leave only through archiveRawMemory. The SQL twin guards the DELETE itself.
+export const AUTO_DELETABLE_SQL = "pinned = 0 AND kind != 'raw'";
+export function canAutoDelete(entry) {
+    return !entry.pinned && entry.kind !== 'raw';
+}
 /**
  * Create a new memory entry with defaults.
  */
@@ -314,7 +320,7 @@ export function createMemory(content, options = {}) {
     const emotional_valence = options.emotional_valence ?? inferValence(tags);
     const schema_fit = options.schema_fit ?? 0.5;
     const partial = { tags, schema_fit };
-    const half_life_days = deriveHalfLife(options.baseHalfLifeDays ?? 7, partial);
+    const half_life_days = deriveHalfLife(options.baseHalfLifeDays ?? DEFAULT_HALF_LIFE_DAYS, partial);
     const entry = {
         id: generateId(layer === Layer.Semantic ? 'sem' : 'mem'),
         created: now,

package/dist/refine-llm.js

@@ -14,6 +14,7 @@
  */
 import { Layer } from './memory.js';
 import { loadAllEntries, readEntry, writeEntry } from './store.js';
+import { redactSecrets } from './secret-detect.js';
 const REFINED_TAG = 'llm-refined';
 const CONSOLIDATED_MARKERS = [
     '[Consolidated from',
@@ -29,7 +30,7 @@ export async function refineSemanticMemory(merged, sources, opts) {
     const fetchFn = opts.fetcher ?? fetch;
     const sourceBlock = sources
         .slice(0, 8)
-        .map((s, i) => `[source ${i + 1}] ${s.content.slice(0, 400)}`)
+        .map((s, i) => `[source ${i + 1}] ${redactSecrets(s.content).slice(0, 400)}`)
         .join('\n\n');
     const prompt = `You are refining a semantic memory in an agent's memory store. The rule-based consolidator merged several related episodic memories into one, but the output is clumsy. Produce a single coherent semantic memory that captures the underlying principle.
 
@@ -41,7 +42,7 @@ Rules:
 - Do NOT include the "[Consolidated from N ...]" marker.
 
 Current merged content:
-${merged}
+${redactSecrets(merged)}
 
 Source memories (up to 8 shown):
 ${sourceBlock}`;

package/dist/rerankers/jev.js

@@ -1,4 +1,5 @@
 import { crossEncoderReranker } from './cross-encoder.js';
+import { redactSecrets } from '../secret-detect.js';
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 const DEFAULT_TIMEOUT_MS = 5_000;
 const TRUNCATE_CHARS = 1200;
@@ -32,8 +33,8 @@ async function requestScores(query, head) {
     const key = process.env.TYPESAFE_API_KEY;
     if (!key)
         throw new Error('TYPESAFE_API_KEY not set');
-    const lines = head.map((r, i) => `[${i + 1}] ${truncate(r.entry.content, TRUNCATE_CHARS)}`);
-    const state = `Query: ${query}\n\nNumbered candidate memories from an AI coding agent's project store:\n\n${lines.join('\n\n')}`;
+    const lines = head.map((r, i) => `[${i + 1}] ${truncate(redactSecrets(r.entry.content), TRUNCATE_CHARS)}`);
+    const state = `Query: ${redactSecrets(query)}\n\nNumbered candidate memories from an AI coding agent's project store:\n\n${lines.join('\n\n')}`;
     const questions = {};
     for (let i = 1; i <= head.length; i++) {
         questions[`c${i}`] = {

package/dist/rerankers/llm.js

@@ -1,3 +1,4 @@
+import { redactSecrets } from '../secret-detect.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 /**
  * Track 3 reranker: listwise LLM rerank. Uses a customer-supplied
@@ -21,8 +22,8 @@ export const llmReranker = async (query, results, options) => {
     const head = results.slice(0, topK);
     const prompt = [
         `Rerank the candidates below by relevance to the query. Output a JSON array of indices (zero-indexed) in best-first order.`,
-        `Query: ${query}`,
-        ...head.map((r, i) => `[${i}] ${r.entry.content}`),
+        `Query: ${redactSecrets(query)}`,
+        ...head.map((r, i) => `[${i}] ${redactSecrets(r.entry.content)}`),
         `Output format: [<int>, <int>, ...] with all ${head.length} indices.`,
     ].join('\n');
     const timeoutMs = Number.parseInt(process.env.HIPPO_LLM_RERANKER_TIMEOUT_MS ?? '', 10) || DEFAULT_TIMEOUT_MS;

package/dist/search.js

@@ -237,8 +237,8 @@ export async function hybridSearch(query, entries, options = {}) {
     if (options.hippoRoot) {
         try {
             const provider = resolveEmbeddingProvider(options.hippoRoot);
-            if (provider.isAvailable() && !embeddingModelRequiresReindex(options.hippoRoot, provider.id)) {
-                const idx = loadEmbeddingIndex(options.hippoRoot);
+            const idx = provider.isAvailable() ? loadEmbeddingIndex(options.hippoRoot) : {};
+            if (provider.isAvailable() && !embeddingModelRequiresReindex(options.hippoRoot, provider.id, idx)) {
                 // Only spend a (possibly paid, off-box) query embedding when at least one
                 // of THIS search's entries has a cached vector to compare against. An
                 // index of only orphaned / out-of-scope vectors yields a meaningless
@@ -511,7 +511,7 @@ export async function hybridSearch(query, entries, options = {}) {
         const head = ordered.slice(0, topK);
         const tail = ordered.slice(topK);
         const rerankInputWithRank = head.map((r, i) => ({ ...r, preRerankRank: i + 1 }));
-        const reranked = await options.reranker(query, rerankInputWithRank, options.rerankerOptions);
+        const reranked = await options.reranker(query, rerankInputWithRank, { ...options.rerankerOptions, topK });
         const withPostRank = reranked.map((r, i) => ({ ...r, postRerankRank: i + 1 }));
         ordered = [...withPostRank, ...tail];
     }

package/dist/server.d.ts

@@ -15,6 +15,8 @@ export interface ServeOpts {
     hippoRoot: string;
     port?: number;
     host?: string;
+    /** Stop and exit on SIGINT/SIGTERM. Only `hippo serve` owns the process, so only it sets this. */
+    handleSignals?: boolean;
 }
 /**
  * Recognise loopback remote addresses. Node reports IPv6-mapped IPv4 as
@@ -22,6 +24,9 @@ export interface ServeOpts {
  * the bare v4 and v6 loopbacks. Anything else is treated as remote.
  */
 export declare function isLoopback(remoteAddress: string | undefined): boolean;
+export declare const LOOPBACK_HOST_HEADER: RegExp;
+/** A browser request sent by another site. Non-browser clients send neither header and pass. */
+export declare function isCrossSite(req: IncomingMessage): boolean;
 /**
  * Rate-limit key for a request. Defaults to the socket's remote address.
  *

package/dist/server.js

@@ -22,7 +22,7 @@ export function __resetSessionRecallHistoryHttp() {
 import { PACKAGE_VERSION } from './version.js';
 import { validateApiKey } from './auth.js';
 import { createRateLimiter } from './rate-limit.js';
-import { remember, recall, RecallContractError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, adminActor, } from './api.js';
+import { remember, retrieve, RecallContractError, ForbiddenError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, adminActor, } from './api.js';
 import { buildGraphModel } from './graph-view.js';
 import { MAX_ENTITY_NAME_LEN } from './graph.js';
 import { savePrediction, closePrediction, loadPredictionById, loadPredictionsByClass, loadOpenPredictions, computePredictionBaserate, VALID_CLOSURE_STATES, } from './predictions.js';
@@ -289,10 +289,13 @@ async function parseJsonBody(req) {
  *   - /unknown/i    → 404 (auth_revoke on unknown key_id)
  *   - /already superseded/i → 409 (chain conflict)
  *   - /not raw/i    → 400 (archive_raw on non-raw row)
- * Everything else maps to 400 (bad input).
+ * ForbiddenError maps to 403; everything else to 400 (bad input).
  */
 function mapApiError(err) {
     const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof ForbiddenError) {
+        return { status: 403, message };
+    }
     const lower = message.toLowerCase();
     if (/not found/.test(lower) || /^unknown /.test(lower)) {
         return { status: 404, message };
@@ -354,6 +357,25 @@ export function isLoopback(remoteAddress) {
         return true;
     return false;
 }
+// Any other Host on a loopback socket is DNS rebinding: a hostile page resolved to 127.0.0.1.
+export const LOOPBACK_HOST_HEADER = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;
+/** A browser request sent by another site. Non-browser clients send neither header and pass. */
+export function isCrossSite(req) {
+    const site = req.headers['sec-fetch-site'];
+    if (site !== undefined && site !== 'same-origin' && site !== 'none')
+        return true;
+    const origin = req.headers.origin;
+    return origin !== undefined && origin !== `http://${req.headers.host}`;
+}
+// A browser on this machine is loopback too, so the no-key fallback also needs a local Host and a same-site caller.
+function assertLocalCaller(req) {
+    if (!isLoopback(req.socket.remoteAddress))
+        throw new HttpError(401, 'auth required');
+    const host = req.headers.host;
+    if ((host !== undefined && !LOOPBACK_HOST_HEADER.test(host)) || isCrossSite(req)) {
+        throw new HttpError(403, 'cross-site or non-local request refused; send an API key');
+    }
+}
 function readAuthHeader(req) {
     const raw = req.headers['authorization'];
     if (raw === undefined)
@@ -455,9 +477,7 @@ function buildContextWithAuth(req, hippoRoot) {
     if (process.env.HIPPO_REQUIRE_AUTH === '1') {
         throw new HttpError(401, 'auth required');
     }
-    if (!isLoopback(req.socket.remoteAddress)) {
-        throw new HttpError(401, 'auth required');
-    }
+    assertLocalCaller(req);
     // v1.12.0: loopback fallback is process-local, treat as admin.
     return {
         hippoRoot,
@@ -492,9 +512,7 @@ function requireAuth(req, hippoRoot) {
     if (process.env.HIPPO_REQUIRE_AUTH === '1') {
         throw new HttpError(401, 'auth required');
     }
-    if (!isLoopback(req.socket.remoteAddress)) {
-        throw new HttpError(401, 'auth required');
-    }
+    assertLocalCaller(req);
 }
 function getString(obj, key) {
     const v = obj[key];
@@ -632,10 +650,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             throw new HttpError(400, 'q is required');
         }
         const limitRaw = query.get('limit');
-        const limit = limitRaw === null ? undefined : Number(limitRaw);
-        if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-            throw new HttpError(400, 'limit must be a positive number');
-        }
+        const limit = limitRaw === null ? undefined : parseListLimit(limitRaw);
         const mode = query.get('mode');
         if (mode !== null && mode !== 'bm25' && mode !== 'hybrid' && mode !== 'physics') {
             throw new HttpError(400, "mode must be 'bm25', 'hybrid', or 'physics'");
@@ -671,11 +686,12 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const summarizeOverflow = summarizeOverflowRaw === null
             ? undefined
             : (summarizeOverflowRaw === '1' || summarizeOverflowRaw === 'true');
-        // v1.7.2 T4: forward as Number(...) — NaN, 0, negative all reach
-        // recall() which throws RecallContractError with code='invalid_scorer_window'.
-        // No transport-side validation; recall() owns the contract.
+        // recall() owns the shape rule (NaN, 0 and negatives throw invalid_scorer_window); the transport caps remote cost.
         const scorerWindowRaw = query.get('scorer_window');
         const scorerWindow = scorerWindowRaw === null ? undefined : Number(scorerWindowRaw);
+        if (scorerWindow !== undefined && scorerWindow > 1000) {
+            throw new HttpError(400, 'scorer_window must be <= 1000');
+        }
         // v1.7.4: session_id for the dlPFC goal-stack boost. 256-char cap mirrors
         // fresh_tail_session_id (above). Trim then drop if empty so api.recall
         // sees undefined when the param is omitted or whitespace-only.
@@ -757,7 +773,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             recallExtra.recallHistory = httpRecallHistory;
         if (explain)
             recallExtra.explain = explain;
-        const result = recall(ctx, {
+        const result = await retrieve(ctx, {
             query: q,
             limit,
             mode: mode ?? undefined,
@@ -1038,7 +1054,8 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     // Tenant scope (Episode A follow-up tracked in TODOS.md): api.sleep operates
     // on the WHOLE hippoRoot (cross-tenant by design, matching CLI cmdSleep).
     // The loopback-only guard is the trust boundary today. Future non-loopback
-    // serving needs an admin-role gate before exposing this route.
+    // serving must also zero the cross-tenant counters for other tenants
+    // (D1 in docs/decisions/2026-05-24-blocked-items.md).
     if (method === 'POST' && path === '/v1/sleep') {
         // Defensive per-request loopback guard. Uses the canonical isLoopback()
         // helper above so any future extension (additional mapped/IPv6 forms,
@@ -1084,11 +1101,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         }
         // v1.12.3: optional body.role mirrors the --role CLI flag. Validated
         // strictly — anything other than 'admin'|'member' is a 400 (no silent
-        // fallback to admin). Required note: admin Bearer can mint a member
-        // key for the same tenant; member Bearer minting an admin key is NOT
-        // blocked here today (auth_create is currently unaudited per the A5 v2
-        // note in authCreate doc). The HTTP layer trusts the buildContextWithAuth
-        // role check at admin-gated routes; mint surface remains permissive.
+        // fallback to admin). authCreate refuses a member caller with a 403.
         const roleRaw = body['role'];
         let role;
         if (roleRaw !== undefined) {
@@ -1128,10 +1141,9 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         sendJson(res, 200, result);
         return;
     }
-    // DELETE /v1/auth/keys/:keyId — revoke. authRevoke throws "Unknown key_id"
-    // for missing OR cross-tenant keys (no info leak), which mapApiError
-    // converts to 404. We return 200 with the result body rather than 204 to
-    // surface revokedAt to the caller.
+    // DELETE /v1/auth/keys/:keyId — revoke. Missing or cross-tenant keys are 404
+    // (no info leak); a member key targeting any key but its own is 403.
+    // 200 with the body rather than 204 so the caller sees revokedAt.
     const keyMatch = matchPath('/v1/auth/keys/:keyId', path);
     if (method === 'DELETE' && keyMatch) {
         validateIdSegment(keyMatch.keyId, 'key id');
@@ -3228,9 +3240,7 @@ export async function serve(opts) {
             server.close(() => resolve());
         });
     };
-    // Skip signal handlers under vitest so each test run does not register a
-    // stray SIGTERM/SIGINT listener that survives until the runner exits.
-    if (!process.env.VITEST) {
+    if (opts.handleSignals) {
         let shuttingDown = false;
         const gracefulShutdown = async (signal) => {
             if (shuttingDown)

package/dist/shared.js

@@ -153,7 +153,7 @@ export async function searchBothHybrid(query, localRoot, globalRoot, options = {
         if (!fs.existsSync(root))
             return [];
         return recallScope
-            ? loadRecallSearchEntries(root, query, searchWindow, tenantId, recallScope.requested, recallScope.additive ? 'additive' : 'exact')
+            ? loadRecallSearchEntries(root, query, searchWindow, tenantId, recallScope.requested, recallScope.additive ? 'additive' : 'exact', Boolean(includeSuperseded) || Boolean(asOf))
             : loadSearchEntries(root, query, searchWindow, tenantId);
     };
     let localEntries = loadEntries(localRoot);