hippo-memory 1.57.0 → 1.58.0

package/dist/embeddings.js

@@ -13,6 +13,7 @@ import { initializeParticle, savePhysicsState, loadPhysicsState, resetAllPhysics
 import { loadConfig } from './config.js';
 import { resolveEmbeddingProvider } from './embedding-provider.js';
 import { redactSecretsStrict } from './secret-detect.js';
+import { log } from './log.js';
 // Use createRequire for synchronous module resolution check in ESM
 const _require = createRequire(import.meta.url);
 // Cached availability check
@@ -270,6 +271,9 @@ async function rebuildEmbeddingIndex(entries, provider) {
         if (vec && vec.length > 0) {
             rebuilt[entries[i].id] = vec;
         }
+        else {
+            noteSkippedEmbedding(entries[i].id);
+        }
     }
     return rebuilt;
 }
@@ -283,10 +287,15 @@ function resetPhysicsFromIndex(hippoRoot, entries, index) {
             closeHippoDb(db);
         }
     }
-    catch {
-        // Physics reset is best-effort; retrieval will still fall back gracefully.
+    catch (err) {
+        // Best effort: retrieval still falls back without physics state.
+        log.warn(`physics reset after reindex failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/** A provider's `[]` row is a swallowed per-item failure; name the memory so the gap can be traced. */
+function noteSkippedEmbedding(id) {
+    log.warn('memory not embedded; the next embed run retries it', { id });
+}
 /**
  * Get an embedding vector for a piece of text.
  * Returns an empty array if transformers is not available or fails.
@@ -314,7 +323,9 @@ export async function getEmbedding(text, model = DEFAULT_EMBEDDING_MODEL, role)
         // pipeline's documented tensor output shape.
         return Array.from(output.data);
     }
-    catch {
+    catch (err) {
+        // The caller sees `[]` and names the memory; the reason only shows at debug.
+        log.debug(`local embedding failed: ${err instanceof Error ? err.message : String(err)}`);
         return [];
     }
 }
@@ -340,23 +351,66 @@ export function cosineSimilarity(a, b) {
     return Math.min(1, Math.max(-1, dot / denom));
 }
 const EMBEDDINGS_FILE = 'embeddings.json';
+// Never equal to a real index identity, so the next embed run treats it as a model change and rebuilds every vector.
+const QUARANTINED_INDEX_IDENTITY = 'quarantined-corrupt-index';
+function isErrnoCode(err, code) {
+    return err instanceof Error && 'code' in err && err.code === code;
+}
+function parseEmbeddingIndex(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        // SAFETY: saveEmbeddingIndex is the only writer and always writes this shape; anything that is not an object is corrupt.
+        return parsed instanceof Object && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Move a corrupt index aside and flag a full rebuild, so no later save can write over the only copy of those bytes. */
+function quarantineCorruptIndex(hippoRoot, fp) {
+    const aside = `${fp}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}`;
+    try {
+        fs.renameSync(fp, aside);
+    }
+    catch (err) {
+        if (isErrnoCode(err, 'ENOENT'))
+            return;
+        // A rename blocked by an open handle (Windows) still gets a copy kept; if the copy fails too, the throw stops the save.
+        fs.copyFileSync(fp, aside, fs.constants.COPYFILE_EXCL);
+    }
+    log.error(`${EMBEDDINGS_FILE} could not be parsed; kept it as ${path.basename(aside)} and the next embed rebuilds the index`, { hippoRoot });
+    try {
+        const db = openHippoDb(hippoRoot);
+        try {
+            setMeta(db, EMBEDDING_MODEL_META_KEY, QUARANTINED_INDEX_IDENTITY);
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch (err) {
+        log.warn(`could not flag the embedding index for rebuild; run 'hippo embed' to restore vectors (${err instanceof Error ? err.message : String(err)})`, { hippoRoot });
+    }
+}
 /**
- * Load the cached embedding index from disk.
- * Returns an empty object if the file doesn't exist or is corrupt.
+ * Load the cached embedding index; `{}` when the file is missing. A corrupt file is moved aside and rebuilt on the next embed; any other read error throws, so nothing saves over an index it could not read.
  */
 export function loadEmbeddingIndex(hippoRoot) {
     const fp = path.join(hippoRoot, EMBEDDINGS_FILE);
-    if (!fs.existsSync(fp))
-        return {};
+    let raw;
     try {
-        // SAFETY: embeddings.json is written exclusively by saveEmbeddingIndex with
-        // this exact shape; a corrupt or foreign file is caught by the try/catch
-        // below and treated as an empty index.
-        return JSON.parse(fs.readFileSync(fp, 'utf8'));
+        raw = fs.readFileSync(fp, 'utf8');
     }
-    catch {
-        return {};
+    catch (err) {
+        if (isErrnoCode(err, 'ENOENT'))
+            return {};
+        throw err;
     }
+    const index = parseEmbeddingIndex(raw);
+    if (index)
+        return index;
+    quarantineCorruptIndex(hippoRoot, fp);
+    return {};
 }
 /**
  * Save the embedding index to disk.
@@ -543,10 +597,9 @@ export async function embedMemory(hippoRoot, entry, model) {
 /**
  * Embed all entries in hippoRoot that don't already have cached vectors.
  * Prunes orphaned embeddings for memories that no longer exist.
- * Returns the count of newly embedded entries.
+ * Returns the count of newly embedded entries. `provider` defaults to the store's configured one.
  */
-export async function embedAll(hippoRoot, model) {
-    const provider = resolveEmbeddingProvider(hippoRoot, { model });
+export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProvider(hippoRoot, { model })) {
     if (!provider.isAvailable()) {
         // A configured (non-disabled) API provider with a missing key is a
         // misconfiguration, not a no-op: surface it so programmatic callers of the
@@ -618,6 +671,9 @@ export async function embedAll(hippoRoot, model) {
                     dirty = true;
                     chunkDirty = true;
                 }
+                else {
+                    noteSkippedEmbedding(chunk[j].id);
+                }
             }
             if (chunkDirty)
                 saveEmbeddingIndex(hippoRoot, index);

package/dist/extract.js

@@ -3,6 +3,7 @@ import { writeEntry } from './store.js';
 import { loadConfig } from './config.js';
 import { RejectedValueError } from './rejection.js';
 import { redactSecrets } from './secret-detect.js';
+import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
 import { neverAutoShareTags } from './shared.js';
 function isJsonString(value) {
     return typeof value === 'string';
@@ -24,7 +25,7 @@ export async function extractFacts(text, opts) {
     const fetchFn = opts.fetcher ?? fetch;
     let res;
     try {
-        res = await fetchFn('https://api.anthropic.com/v1/messages', {
+        res = await fetchWithRetry('https://api.anthropic.com/v1/messages', {
             method: 'POST',
             headers: {
                 'content-type': 'application/json',
@@ -36,7 +37,7 @@ export async function extractFacts(text, opts) {
                 max_tokens: 1200,
                 messages: [{ role: 'user', content: EXTRACTION_PROMPT + redactSecrets(text) }],
             }),
-        });
+        }, { timeoutMs: llmTimeoutMs(), fetchFn });
     }
     catch (err) {
         opts.onError?.(`request failed: ${err instanceof Error ? err.message : String(err)}`);

package/dist/http-retry.d.ts

@@ -0,0 +1,21 @@
+/** One retry policy for outbound HTTP: a timeout on every attempt, and backoff on 429 and 5xx only. */
+export interface RetryPolicy {
+    /** Per-attempt limit; a stalled peer ends as a thrown `TimeoutError`, never a hang. */
+    timeoutMs: number;
+    /** Total attempts including the first. */
+    attempts?: number;
+    baseDelayMs?: number;
+    /** A Retry-After longer than this hands the response back, so a caller with its own long pause keeps it. */
+    maxDelayMs?: number;
+    fetchFn?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+}
+/** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS` overrides it. */
+export declare function llmTimeoutMs(): number;
+export declare function isRetryableStatus(status: number): boolean;
+/** Retry-After as milliseconds: delta-seconds or an HTTP date; null when absent or unreadable. */
+export declare function parseRetryAfterMs(header: string | null, now?: number): number | null;
+/** `fetch` with a per-attempt timeout and up to `attempts` tries on 429 and 5xx; the last response comes back as is and transport errors throw at once. */
+export declare function fetchWithRetry(url: string | URL, init: RequestInit, policy: RetryPolicy): Promise<Response>;
+//# sourceMappingURL=http-retry.d.ts.map

package/dist/http-retry.js

@@ -0,0 +1,50 @@
+/** One retry policy for outbound HTTP: a timeout on every attempt, and backoff on 429 and 5xx only. */
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_BASE_DELAY_MS = 250;
+const DEFAULT_MAX_DELAY_MS = 8_000;
+const DEFAULT_LLM_TIMEOUT_MS = 60_000;
+/** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS` overrides it. */
+export function llmTimeoutMs() {
+    const parsed = Number.parseInt(process.env.HIPPO_LLM_TIMEOUT_MS ?? '', 10);
+    return parsed > 0 ? parsed : DEFAULT_LLM_TIMEOUT_MS;
+}
+export function isRetryableStatus(status) {
+    return status === 429 || (status >= 500 && status <= 599);
+}
+/** Retry-After as milliseconds: delta-seconds or an HTTP date; null when absent or unreadable. */
+export function parseRetryAfterMs(header, now = Date.now()) {
+    if (header === null || header.trim() === '')
+        return null;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const at = Date.parse(header);
+    return Number.isNaN(at) ? null : Math.max(0, at - now);
+}
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** `fetch` with a per-attempt timeout and up to `attempts` tries on 429 and 5xx; the last response comes back as is and transport errors throw at once. */
+export async function fetchWithRetry(url, init, policy) {
+    const fetchFn = policy.fetchFn ?? fetch;
+    const attempts = Math.max(1, policy.attempts ?? DEFAULT_ATTEMPTS);
+    const baseDelayMs = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    const maxDelayMs = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    const sleep = policy.sleep ?? realSleep;
+    const random = policy.random ?? Math.random;
+    for (let attempt = 1;; attempt++) {
+        const timeout = AbortSignal.timeout(policy.timeoutMs);
+        const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+        const res = await fetchFn(url, { ...init, signal });
+        if (!isRetryableStatus(res.status) || attempt >= attempts)
+            return res;
+        const retryAfter = parseRetryAfterMs(res.headers.get('retry-after'));
+        if (retryAfter !== null && retryAfter > maxDelayMs)
+            return res;
+        // Jitter over the upper half keeps parallel callers from retrying in lockstep.
+        const ceiling = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
+        const delay = retryAfter ?? ceiling / 2 + random() * (ceiling / 2);
+        // Frees the pooled socket before the next attempt.
+        await res.body?.cancel();
+        await sleep(delay);
+    }
+}
+//# sourceMappingURL=http-retry.js.map

package/dist/http-util.d.ts

@@ -13,6 +13,14 @@ export declare class HttpError extends Error {
 }
 export declare class BodyTooLargeError extends Error {
 }
+/** The status and client-facing message for one failed request. */
+export interface ApiErrorReply {
+    status: number;
+    message: string;
+}
+export declare const INTERNAL_ERROR_MESSAGE = "internal server error";
+/** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
+export declare function mapApiError<E>(err: E): ApiErrorReply;
 export declare function sendJson<T>(res: ServerResponse, status: number, body: T): void;
 /**
  * Read the entire request body into a Buffer. Caps at MAX_BODY_BYTES to keep

package/dist/http-util.js

@@ -1,3 +1,4 @@
+import { ApiError } from './api-errors.js';
 export function isJsonObjectRecord(value) {
     return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -19,6 +20,15 @@ export class HttpError extends Error {
 }
 export class BodyTooLargeError extends Error {
 }
+export const INTERNAL_ERROR_MESSAGE = 'internal server error';
+/** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
+export function mapApiError(err) {
+    if (err instanceof HttpError || err instanceof ApiError)
+        return { status: err.status, message: err.message };
+    if (err instanceof BodyTooLargeError)
+        return { status: 413, message: err.message };
+    return { status: 500, message: INTERNAL_ERROR_MESSAGE };
+}
 export function sendJson(res, status, body) {
     res.writeHead(status, JSON_HEADERS);
     res.end(JSON.stringify(body));

package/dist/importers.d.ts

@@ -20,6 +20,8 @@ export interface ImportResult {
     /** K1 vault import: rows archived this run (changed + source-deleted). In a
      *  dryRun this is the would-be count (a true deletion-sync preview). */
     archived?: number;
+    /** Entries stored with secret-shaped text redacted; optional for the same published-surface reason as `rejected`. */
+    redacted?: number;
     entries: MemoryEntry[];
 }
 export interface ImportOptions {

package/dist/importers.js

@@ -13,6 +13,7 @@ import { remember, archiveRaw, isPrivateScope } from './api.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { RejectedValueError, checkRejectionGuard } from './rejection.js';
 import { loadConfig } from './config.js';
+import { vetSecrets } from './secret-detect.js';
 // ---------------------------------------------------------------------------
 // Shared core: dedup + write
 // ---------------------------------------------------------------------------
@@ -33,6 +34,7 @@ export function importEntries(chunks, source, tags, options) {
     let imported = 0;
     let skipped = 0;
     let rejected = 0;
+    let redacted = 0;
     const entries = [];
     // AT1 P2 fix: a dry-run preview never called writeEntry, so it never
     // checked tombstones either — every non-duplicate chunk counted as
@@ -42,7 +44,9 @@ export function importEntries(chunks, source, tags, options) {
     const dryRunDb = options.dryRun ? openHippoDb(targetRoot) : null;
     try {
         for (const raw of chunks) {
-            const trimmed = raw.trim();
+            const original = raw.trim();
+            const trimmed = vetSecrets(original, allTags, true).content;
+            const wasRedacted = trimmed !== original;
             if (trimmed.length > 1000) {
                 console.error(`Warning: imported memory truncated from ${trimmed.length} to 1000 chars`);
             }
@@ -109,8 +113,10 @@ export function importEntries(chunks, source, tags, options) {
             }
             entries.push(entry);
             imported++;
+            if (wasRedacted)
+                redacted++;
         }
-        return { total, imported, skipped, rejected, entries };
+        return { total, imported, skipped, rejected, redacted, entries };
     }
     finally {
         if (dryRunDb)
@@ -430,6 +436,7 @@ export function importMarkdown(filePath, options) {
             // AT1 P2 fix: `rejected` is now optional on ImportResult (compat) — tolerate
             // undefined on either side of the accumulation.
             rejected: (totalResult.rejected ?? 0) + (result.rejected ?? 0),
+            redacted: (totalResult.redacted ?? 0) + (result.redacted ?? 0),
             entries: [...totalResult.entries, ...result.entries],
         };
     }
@@ -695,6 +702,7 @@ export function importVault(folderPath, options) {
     let skipped = 0;
     let rejected = 0;
     let archived = 0;
+    let redacted = 0;
     const entries = [];
     const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
     // AT1 P2 fix: dry-run never called remember(), so it never probed
@@ -796,7 +804,8 @@ export function importVault(folderPath, options) {
             // remember() owns the actual write. We build an `echo` of the SAME content +
             // tags via createMemory purely for the ImportResult, then reconcile its id to
             // remember()'s real row id so entries[] reflects the row that landed.
-            const echo = createMemory(body, {
+            const content = vetSecrets(body, tags, true).content;
+            const echo = createMemory(content, {
                 kind: 'raw',
                 tags,
                 scope,
@@ -815,7 +824,7 @@ export function importVault(folderPath, options) {
                 // loud each time via the rejected count.
                 try {
                     const result = remember(ctx, {
-                        content: body,
+                        content,
                         kind: 'raw',
                         artifactRef,
                         owner: 'agent:vault-import',
@@ -848,6 +857,8 @@ export function importVault(folderPath, options) {
             }
             entries.push(echo);
             imported++;
+            if (content !== body)
+                redacted++;
         }
     }
     finally {
@@ -867,7 +878,7 @@ export function importVault(folderPath, options) {
                 archiveRaw(ctx, row.id, `source_deleted:${artifactRef}`);
         }
     }
-    return { total, imported, skipped, rejected, archived, entries };
+    return { total, imported, skipped, rejected, archived, redacted, entries };
 }
 /** Local tolerant JSON-array parse for the loader's `tags_json` column. The
  *  store's own `parseJsonArray` is not exported; this matches its contract

package/dist/incidents.js

@@ -25,6 +25,7 @@
  * the row, default `[]`. On save, every id must exist in the SAME tenant; a
  * cross-tenant or nonexistent id is rejected (throw) before the insert.
  */
+import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry } from './store.js';
 import { assertTenantId } from './tenant.js';
@@ -89,7 +90,7 @@ const INCIDENT_COLS = `
 export function saveIncident(hippoRoot, tenantId, opts, actor = 'cli') {
     assertTenantId('saveIncident', tenantId);
     if (!opts.incidentText)
-        throw new Error('saveIncident: incidentText is required');
+        throw new BadRequestError('saveIncident: incidentText is required');
     const now = new Date().toISOString();
     const content = opts.context
         ? `${opts.incidentText}\n\nContext: ${opts.context}`
@@ -118,7 +119,7 @@ export function saveIncident(hippoRoot, tenantId, opts, actor = 'cli') {
                 // SAFETY: row shape matches the single `id` column named in the SELECT above.
                 const exists = db.prepare(`SELECT id FROM memories WHERE id = ? AND tenant_id = ?`).get(linkId, tenantId);
                 if (!exists) {
-                    throw new Error(`saveIncident: linked memory ${linkId} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`saveIncident: linked memory ${linkId} not found for tenant ${tenantId}`);
                 }
                 validated.push(linkId);
             }
@@ -164,7 +165,7 @@ export function saveIncident(hippoRoot, tenantId, opts, actor = 'cli') {
 export function resolveIncident(hippoRoot, tenantId, id, resolutionText, actor = 'cli') {
     assertTenantId('resolveIncident', tenantId);
     if (!resolutionText || !resolutionText.trim()) {
-        throw new Error('resolveIncident: resolutionText is required (non-empty)');
+        throw new BadRequestError('resolveIncident: resolutionText is required (non-empty)');
     }
     const now = new Date().toISOString();
     const db = openHippoDb(hippoRoot);
@@ -180,15 +181,15 @@ export function resolveIncident(hippoRoot, tenantId, id, resolutionText, actor =
                 // SAFETY: row shape matches the single `status` column named in the SELECT above.
                 const existing = db.prepare(`SELECT status FROM incidents WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`resolveIncident: incident ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`resolveIncident: incident ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`resolveIncident: incident ${id} is not open (status='${existing.status}'); only open incidents can be resolved.`);
+                throw new ConflictError(`resolveIncident: incident ${id} is not open (status='${existing.status}'); only open incidents can be resolved.`);
             }
             // SAFETY: row's shape matches the columns named in INCIDENT_COLS above.
             const row = db.prepare(`SELECT ${INCIDENT_COLS} FROM incidents WHERE id = ? AND tenant_id = ?`)
                 .get(id, tenantId);
             if (!row)
-                throw new Error(`resolveIncident: incident ${id} not found after UPDATE`);
+                throw new NotFoundError(`resolveIncident: incident ${id} not found after UPDATE`);
             appendAuditEvent(db, {
                 tenantId,
                 actor,
@@ -235,15 +236,15 @@ export function closeIncident(hippoRoot, tenantId, id, actor = 'cli') {
                 // SAFETY: row shape matches the single `status` column named in the SELECT above.
                 const existing = db.prepare(`SELECT status FROM incidents WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`closeIncident: incident ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`closeIncident: incident ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`closeIncident: incident ${id} is already closed (status='${existing.status}'); only open or resolved incidents can be closed.`);
+                throw new ConflictError(`closeIncident: incident ${id} is already closed (status='${existing.status}'); only open or resolved incidents can be closed.`);
             }
             // SAFETY: row's shape matches the columns named in INCIDENT_COLS above.
             const row = db.prepare(`SELECT ${INCIDENT_COLS} FROM incidents WHERE id = ? AND tenant_id = ?`)
                 .get(id, tenantId);
             if (!row)
-                throw new Error(`closeIncident: incident ${id} not found after UPDATE`);
+                throw new NotFoundError(`closeIncident: incident ${id} not found after UPDATE`);
             appendAuditEvent(db, {
                 tenantId,
                 actor,
@@ -289,7 +290,7 @@ export function loadIncidents(hippoRoot, tenantId, opts = {}) {
         let rows;
         if (opts.status) {
             if (!VALID_INCIDENT_STATES.has(opts.status)) {
-                throw new Error(`loadIncidents: status must be one of ${Array.from(VALID_INCIDENT_STATES).join('|')}; got ${opts.status}`);
+                throw new BadRequestError(`loadIncidents: status must be one of ${Array.from(VALID_INCIDENT_STATES).join('|')}; got ${opts.status}`);
             }
             // SAFETY: rows' shape matches the columns named in INCIDENT_COLS above.
             rows = db.prepare(`

package/dist/judgment.js

@@ -1,10 +1,10 @@
 /** Typed judgment over capture candidates via TypeSafe's Jev (System One).
  *  Regex picks WHAT is a candidate; it cannot say what is worth keeping, so
  *  every captured memory currently lands on a flat schema_fit of 0.5. */
+import { fetchWithRetry } from './http-retry.js';
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 const DEFAULT_MODEL = 'jev-1.13.0';
 const MAX_CONCURRENCY = 8;
-const RETRY_STATUS = new Set([429, 529]);
 const QUESTIONS = {
     durable: {
         type: 'noul',
@@ -48,11 +48,12 @@ function toConfidenceTier(kindConfidence) {
         return 'observed';
     return 'inferred';
 }
-async function postOnce(content, opts) {
-    const fetchFn = opts.fetcher ?? fetch;
+/** Capture-time judging must not hold a write for long: one budget per attempt, shorter than the LLM calls. */
+const JUDGE_TIMEOUT_MS = 15_000;
+async function post(content, opts) {
     let res;
     try {
-        res = await fetchFn(ENDPOINT, {
+        res = await fetchWithRetry(ENDPOINT, {
             method: 'POST',
             headers: {
                 'content-type': 'application/json',
@@ -63,16 +64,12 @@ async function postOnce(content, opts) {
                 model: opts.model ?? DEFAULT_MODEL,
                 questions: QUESTIONS,
             }),
-        });
+        }, { timeoutMs: JUDGE_TIMEOUT_MS, fetchFn: opts.fetcher });
     }
     catch {
         return null;
     }
-    if (RETRY_STATUS.has(res.status))
-        return { retryable: true };
-    if (!res.ok)
-        return null;
-    return { res };
+    return res.ok ? res : null;
 }
 /** `null` on any failure, so a Jev outage degrades capture to today's
  *  behaviour instead of blocking the write. */
@@ -80,19 +77,15 @@ export async function judge(content, opts) {
     const trimmed = content.trim();
     if (trimmed.length < 3)
         return null;
-    let attempt = await postOnce(trimmed, opts);
-    if (attempt && 'retryable' in attempt) {
-        await new Promise((resolve) => setTimeout(resolve, 500));
-        attempt = await postOnce(trimmed, opts);
-    }
-    if (!attempt || 'retryable' in attempt)
+    const res = await post(trimmed, opts);
+    if (!res)
         return null;
     let data;
     try {
         // SAFETY: the documented Jev response is `{ answers: { <name>: Answer } }`
         // keyed by the question names posted above; every field read below is
         // optional-chained and range-checked before use, so a lie here returns null.
-        data = await attempt.res.json();
+        data = await res.json();
     }
     catch {
         return null;

package/dist/log.d.ts

@@ -0,0 +1,25 @@
+/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+/** Extra key=value pairs appended to the line; `requestId` ties a line to one HTTP request. */
+export interface LogFields {
+    requestId?: string;
+    [key: string]: string | number | boolean | undefined;
+}
+/** The active threshold, read on every call so a test or a long-lived server can change it without a restart. */
+export declare function logThreshold(): LogLevel;
+export declare function isLevelEnabled(level: LogLevel): boolean;
+/** Same `[hippo] ` prefix the existing stderr lines use, so default-level output reads as before. */
+export declare function formatLogLine(level: LogLevel, message: string, fields?: LogFields): string;
+/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. */
+declare function once(key: string, level: LogLevel, message: string, fields?: LogFields): void;
+export declare const log: {
+    readonly error: (message: string, fields?: LogFields) => void;
+    readonly warn: (message: string, fields?: LogFields) => void;
+    readonly info: (message: string, fields?: LogFields) => void;
+    readonly debug: (message: string, fields?: LogFields) => void;
+    readonly once: typeof once;
+};
+/** Test hook: forget which once-keys have fired. */
+export declare function resetLogOnce(): void;
+export {};
+//# sourceMappingURL=log.d.ts.map

package/dist/log.js

@@ -0,0 +1,48 @@
+/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. */
+const RANK = { error: 0, warn: 1, info: 2, debug: 3 };
+function isLogLevel(value) {
+    return Object.hasOwn(RANK, value);
+}
+/** The active threshold, read on every call so a test or a long-lived server can change it without a restart. */
+export function logThreshold() {
+    const raw = process.env.HIPPO_LOG?.trim().toLowerCase() ?? '';
+    return isLogLevel(raw) ? raw : 'warn';
+}
+export function isLevelEnabled(level) {
+    return RANK[level] <= RANK[logThreshold()];
+}
+// A field value is caller data; flattening newlines keeps one event on one line.
+const oneLine = (value) => value.replace(/[\r\n]+/g, ' ');
+/** Same `[hippo] ` prefix the existing stderr lines use, so default-level output reads as before. */
+export function formatLogLine(level, message, fields = {}) {
+    const extras = Object.entries(fields)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => ` ${k}=${oneLine(String(v))}`)
+        .join('');
+    return `[hippo] ${level}: ${oneLine(message)}${extras}`;
+}
+function write(level, message, fields) {
+    if (!isLevelEnabled(level))
+        return;
+    process.stderr.write(`${formatLogLine(level, message, fields)}\n`);
+}
+const onceKeys = new Set();
+/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. */
+function once(key, level, message, fields) {
+    if (onceKeys.has(key))
+        return;
+    onceKeys.add(key);
+    write(level, message, fields);
+}
+export const log = {
+    error: (message, fields) => write('error', message, fields),
+    warn: (message, fields) => write('warn', message, fields),
+    info: (message, fields) => write('info', message, fields),
+    debug: (message, fields) => write('debug', message, fields),
+    once,
+};
+/** Test hook: forget which once-keys have fired. */
+export function resetLogOnce() {
+    onceKeys.clear();
+}
+//# sourceMappingURL=log.js.map